Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

fix: no blank picture while the narration opens a step

yzr4aacd73ace27
diff --git a/.claude/skills/animebook-chapter/SKILL.md b/.claude/skills/animebook-chapter/SKILL.md
index 9d073d3..29a8e32 100644
--- a/.claude/skills/animebook-chapter/SKILL.md
+++ b/.claude/skills/animebook-chapter/SKILL.md
@@ -37,6 +37,10 @@ description: 为 AnimeBook 制作或修改一章数学动画课:读参考书
7. **端到端检查**:参照 `tools/e2e_ch02.py` 写 `tools/e2e_chNN.py`,用纯键盘把每道题走一遍,覆盖答对、答错、看答案三种情况,最后逐步快进全部步骤;控制台不能有报错。有拖拽题时,参照 `tools/e2e_ch01.py` 补一遍鼠标操作。
8. **更新文档**:`plan.md` 记录新决定,`CLAUDE.md` 更新目录地图。提交前先问用户。
+## 开场不留白(用户 2026-10-03 指出)
+
+旁白开始时画面不能是空的。新的一步清空画面(`panel(0)`)后,引擎会把开场一组动作前移到 0.4 秒(见 `engine.md` 的 `leadIn`),但编排时仍应主动让本步的主题算式、题目或图形先出现,再随旁白逐步标注。做完一章后运行 `uv run --with playwright tools/check_blank.py chNN`,没有输出才算通过。正常转场和思考停顿保留,不要求画面一直在动。
+
## 第一章踩过的坑
- **重播靠快进**:跳到第 N 步时,页面重建场景,再把前面每一步的 `run` 以 `evalTo(Infinity)` 瞬间执行一遍。因此 `run` 里只能用补间函数(`tw/prog/show/draw…`)排动作,不能用 `setTimeout`、随机数或读取当前时间,否则跳步后画面和正常播放不一致。交互元素只能在 `ask` 里创建。
diff --git a/.claude/skills/animebook-chapter/references/engine.md b/.claude/skills/animebook-chapter/references/engine.md
index cf32c6d..9d5a427 100644
--- a/.claude/skills/animebook-chapter/references/engine.md
+++ b/.claude/skills/animebook-chapter/references/engine.md
@@ -66,6 +66,7 @@
- `m(name, 偏移)` 返回讲稿里 `[[name]]` 后第一个词开始的秒数;拼错名字会直接报错。`D` 是本段语音时长。
- 补间函数:`tw(e, to, t0, dur, ease)`、`prog(q => …, t0, dur)`(自定义进度,例如滚动圆、弧线运动)、`show/hide/draw/pop/pulse`、`glow/glowRun`(集合圈描边闪亮)、`stream`(数字逐位出现)。缓动有 `io`、`out`、`back`、`lin`。
- 普通步骤播完自动进入下一步;带 `ask` 的步骤播完旁白后等待学生答完再继续。
+- 开场前移(`leadIn`):本步在 0.5 秒前调用了 `panel()`(清空画面,或标题后的第一个面板),且 0.8 秒内没有新对象出现时,`runBeat` 把首个出现对象之后 1.2 秒内的全部补间整体前移到 0.4 秒开始。某步需要刻意留白时,在步骤的第四项写 `{ lead: false }`。
## 小测与练习
diff --git a/CLAUDE.md b/CLAUDE.md
index c0a4325..92f2d53 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -62,7 +62,8 @@ AnimeBook/
├── .claude/skills/animebook-chapter/ # 做章节的流程、已定约定、踩过的坑、引擎速查(新章节先读)
├── tools/
│ ├── tts.py # Edge TTS 生成 MP3、词级时间点与逐句字幕
-│ └── e2e_chNN.py # 各章浏览器端到端检查(Playwright);改引擎后全部重跑
+│ ├── e2e_chNN.py # 各章浏览器端到端检查(Playwright);改引擎后全部重跑
+│ └── check_blank.py # 检测开场留白:旁白已开始、画面仍为空的步骤
├── site/ # 可部署的静态站点(只部署此目录)
│ ├── index.html # 书架、书封与章节目录(同一页,hash 切换;章节数据在 UNITS;localStorage 记进度)
│ ├── lib/ # 共用引擎 engine.js / engine.css;书架数据与样式 bookshelf.js / bookshelf.css
diff --git a/plan.md b/plan.md
index e1c2814..4d8cbf7 100644
--- a/plan.md
+++ b/plan.md
@@ -120,6 +120,8 @@
用户明确指出问题出现在开场:旁白已经开始讲解,主画面却还没有内容,属于编排留白。后续动画审查重点检查开场的画面承接,需要时更早呈现主题、相关数学对象、算式或关键文字,再随旁白展开逐步标注、图形变化和计算推演。用户确认正常转场与思考停顿没有问题,保留这些停顿,不要求画面持续运动;适当增加的动画效果仍应服务于数学讲解。
+开场留白已处理(2026-10-03):`tools/check_blank.py` 逐步检测“旁白已开始、画面仍为空”的时长,全书原有 267 步超过 1 秒(中位 2.8 秒,最长 8.6 秒)。引擎在每步清空画面后,若 0.8 秒内没有新内容出现,就把开场一组(首个出现对象之后 1.2 秒内的全部动作)整体前移到 0.4 秒,即上一画面淡出完毕时,后续动作仍按词的时间点;某步不需要时可在步骤上写 `lead: false`。处理后全书在 0.6 秒阈值下检测为零,267 个开场画面逐一截图核对,1–68 章端到端测试全部通过。
+
### 6.2 制作前先有可检查的分镜
每段动画的分镜至少写清:
diff --git a/site/ch01/index.html b/site/ch01/index.html
index 495268f..ad40a8a 100644
--- a/site/ch01/index.html
+++ b/site/ch01/index.html
@@ -231,7 +231,7 @@ const BEATS = [
], [['rat', 'Rational', COL.rat], ['irr', 'Irrational', COL.irr]], { multi: false }),
}], done) }],
['map', 'The number map', (m) => {
- hide(S.list, 0, .7); hide(S.line, 0, .7); hide(S.panel, 0, .7);
+ hide(S.list, 0, .7); hide(S.line, 0, .7); panel(0);
S.ring = buildVenn(S.venn, true);
const samples = { nat: [[['1 2 3'], 500, 548]], whole: [[['0'], 332, 578]], int: [[['−5'], 248, 560], [['−1'], 752, 560]],
rat: [[[F(3, 4)], 150, 512], [['0.6'], 850, 512]], irr: [[[R(2)], 1060, 462]] };
diff --git a/site/lib/engine.js b/site/lib/engine.js
index 03c7036..681ed5e 100644
--- a/site/lib/engine.js
+++ b/site/lib/engine.js
@@ -849,6 +849,7 @@ function dot(key, v, r = 9, name = v) {
}
const arrow = (x, dir) => `M${x - 15 * dir} ${Y0 - 10}L${x} ${Y0}L${x - 15 * dir} ${Y0 + 10}`;
function panel(t0) {
+ if (t0 < .5) S.cleared = true; // the old panel fades, or this is the first panel after the title
if (S.panel) hide(S.panel, t0, .4);
return (S.panel = G(scene));
}
@@ -1427,10 +1428,27 @@ function runBeat(i) {
if (!(k in tm.marks)) throw new Error(`${b.id}: missing mark ${k}`);
return tm.marks[k] + off;
};
+ S.cleared = false;
b.run(m, tm.dur);
+ if (S.cleared && b.lead !== false) leadIn();
TW.sort((a, c) => a.t0 - c.t0);
return Math.max(tm.dur, ...TW.map(w => w.t0 + w.dur)) + .6;
}
+// A beat that clears the picture must not leave it empty while the narration has started.
+// If nothing appears before LEAD_MAX, the opening group (every tween that starts within LEAD_GROUP s of the
+// first reveal) moves earlier so it begins at LEAD_AT, just after the old panel has faded. Later steps keep their word timing.
+const LEAD_AT = .4, LEAD_MAX = .8, LEAD_GROUP = 1.2;
+function leadIn() {
+ const reveals = TW.filter(w => {
+ if (!w.e) return false;
+ const s = st(w.e), to = w.to;
+ return (to.o > 0 && s.o === 0) || (to.s > 0 && s.s === 0) || (to.d > 0 && (s.d ?? 1) === 0);
+ });
+ if (!reveals.length) return;
+ const first = Math.min(...reveals.map(w => w.t0));
+ if (first <= LEAD_MAX) return;
+ for (const w of TW) if (w.t0 >= first && w.t0 < first + LEAD_GROUP) w.t0 -= first - LEAD_AT;
+}
function stopAudio() {
const a = P.audio;
if (!a) return;
diff --git a/tools/check_blank.py b/tools/check_blank.py
new file mode 100644
index 0000000..dc5b6da
--- /dev/null
+++ b/tools/check_blank.py
@@ -0,0 +1,59 @@
+"""Find opening blanks: narration has started but the picture is still empty.
+
+ python3 -m http.server 8765 -d site &
+ uv run --with playwright tools/check_blank.py # every chapter
+ uv run --with playwright tools/check_blank.py ch05 ch06 # some chapters
+ LIMIT=0.6 uv run --with playwright tools/check_blank.py # stricter
+
+Prints chapter, beat index, beat id, empty from, empty until, seconds, for each lesson beat whose
+picture stays empty longer than LIMIT (default 1 s) near its start. Question beats are skipped.
+No output means no opening blank.
+"""
+import asyncio, sys, json
+from playwright.async_api import async_playwright
+LIMIT = float(__import__("os").environ.get("LIMIT", "1.0"))
+JS = r"""
+(i) => {
+ seek(i, false);
+ const b = BEATS[i], tm = TIMINGS[b.id];
+ const first = (tm.cues[0] || [0])[0];
+ // A leaf is visible if its box has size, nothing hides it, and the opacity product up to the scene is > .05.
+ const vis = () => {
+ let n = 0;
+ for (const e of scene.querySelectorAll('text,path,circle,rect,ellipse,line,polygon')) {
+ if (e.closest('.qlayer')) continue;
+ let o = 1, x = e;
+ while (x && x !== scene) { o *= +(x.getAttribute('opacity') ?? 1); if (x.style && x.style.visibility === 'hidden') o = 0; x = x.parentNode; }
+ if (o < .05) continue;
+ const r = e.getBoundingClientRect();
+ if (r.width < 2 && r.height < 2) continue;
+ n++;
+ }
+ return n;
+ };
+ const out = [];
+ for (let t = 0; t <= Math.min(tm.dur, 12); t += .2) { P.t = t; evalTo(t); out.push([+t.toFixed(1), vis()]); }
+ return { id: b.id, ask: !!b.ask, first, dur: tm.dur, out };
+}
+"""
+async def main(chs):
+ async with async_playwright() as p:
+ b = await p.chromium.launch(); pg = await b.new_page(viewport={"width": 1600, "height": 960})
+ rows = []
+ for ch in chs:
+ await pg.goto(f"http://localhost:8765/{ch}/index.html?beat=0&t=0"); await pg.wait_for_timeout(300)
+ n = await pg.evaluate("BEATS.length")
+ for i in range(n):
+ r = await pg.evaluate(JS, i)
+ if r["ask"] or r["id"] in ("finish",): continue
+ # blank = the longest run of empty frames that starts before 3 s, measured from the first word
+ empty = [t for t, c in r["out"] if c == 0]
+ if not empty: continue
+ start = max(empty[0], r["first"])
+ end = next((t for t, c in r["out"] if t > empty[0] and c > 0), r["dur"])
+ gap = end - start
+ if gap > LIMIT and empty[0] < 3: rows.append((ch, i, r["id"], round(start, 1), round(end, 1), round(gap, 1)))
+ for row in rows: print(*row)
+ await b.close()
+chs = sys.argv[1:] or [f"ch{n:02d}" for n in range(1, 69)]
+asyncio.run(main(chs))