代码诗词动画（code-poem-film）

把一首诗做成一条片子（绝句 20–40 秒，一阕百字的词 60–80 秒）：宣纸底、水墨淡彩，一个红点落在纸上、长出眼睛，把这首诗走一遍；每句诗在右上角的题签上随朗诵写出来；最后一句红点自己提笔写，念到哪个字写到哪个字，然后落成一枚红印章。画面每一帧都是代码画的，配乐和音效是 numpy 算的，没有图片素材、视频素材、曲库。

这套做法来自两条成片：《早发白帝城》（examples/qingzhou，七绝，25.5 秒）和《念奴娇·赤壁怀古》（examples/chibi，词，72 秒）。它们翻过的车——猿挂的树悬空、鼓把旋律盖住、多音字怕念错、开头是白纸导致缩略图是白纸、一帧出错后画面静默卡住、小舟画在了礁石「上面」、淡出的东西压住片尾小字——现在都由引擎、检查脚本和 references/qa.md 兜住。你的工作是把这首诗的画面想好、演好，而不是重新踩一遍。

它擅长什么、不擅长什么

擅长：绝句、律诗，百字以内的词，一句名句，几十字的短文。有景、有动作、有转折的最好做（行舟、登楼、望月、送别、怀古、江雪）。画法库里有：山（远峰、群山、峡谷绝壁、渐隐的远山、石峰）、岸、江水、长浪、开阔水面、巨浪和浪花、日、月、星、祥云、雾、雨、雪、飞鸟、松、柳、城楼、多层楼阁、残垒、带帆小舟、乌篷小舟、战船、火、烟、人物剪影（文士、武将、仕女）、猿、酒杯、手卷的装裱，以及溅水、浪头、落地的墨点。看 references/kit-1.jpg … kit-4.jpg 就知道库里有什么、长什么样。

不擅长：人物的戏（库里的人是没有脸的远景剪影，只能站、举手、转身；主角永远是红点）；一百字以上的长文（按每秒不到 3 个字算，一百字就是 70 秒，再长要节选）；竖版（版式是按 1920×1080 排的）；抽象说理、没有画面的句子（要先和用户商量画什么）。库里没有的东西可以现画（见 references/scenes.md），但要多花时间，开工前说清楚：赤壁那条现画了 14 样东西，整条从提出到成片用了 63 分钟。

用户只说了一句话时

「做一条《静夜思》的动画」就够开工。默认这样走：

1. 先定题材。用户没指定诗，就给三四个候选，每个一句话说清「红点在里面干什么」，推荐一个，让用户选。用户指定了诗，就直接进入下一步。
2. 只问会改变做法的事：发在哪（现在只能横版）、要不要朗诵、男声还是女声。用上次的选择或默认值时说一声就行，不要一项项问。
3. 用户确认题材后一路做到出片。中途只在两种情况停下来：要花钱（真配音按次计费：先 film.py voice --plan 看会调用几次、多少字，告诉用户）、要画库里没有的大件东西。
4. 朗诵你听不到。能做的是量：语速、停顿、轻重变化、人声比配乐高多少。选音色拿不准时出两版让用户听，不要替用户说「这个更有感情」。

流程

所有命令在工程目录里运行，tools/film.py 是唯一入口。渲染用 HyperFrames（通过 npx hyperframes 调用），工程也是一个 HyperFrames 工程，但这类片子不需要再走它的问答和分镜流程——这份文档就是完整流程。

# SK = 这份 SKILL.md 所在的目录
python3 $SK/scripts/new_project.py videos/<slug>     # 新建工程：HyperFrames 初始化 + 引擎 + 起步片子 + 笔画数据
cd videos/<slug>

每到一个节点记一笔：python3 tools/film.py log "分镜确认"。

四个文件各管一件事

engine/ 和 tools/ 是引擎，新片子一般不用改；现画的新东西如果别的诗也用得上，就写进工程的 engine/，出片后同步回这个 skill 的 template/engine/ 并在 examples/gallery 里加一格。舞台（engine/stage.js）已经包了：封面及其淡出、题签逐句写字、末句随朗诵逐字书写、红点变印章、落款、整片的宣纸质感。你交给舞台的只有四样：build（一次性画好的贴图）、scene(ctx, t)（每一帧）、cover(c, time)（封面那张画）、titleFrom()（红点从哪儿跳起来去写字）。

film/timing.js 里时间表的写法：

const T = { drop: 0.35, land1: 0.85, …, bloom: 3.0, launch: 8.6, hop: 17.15, write0: 17.9 };
PoemTiming.finish(T, {
  lines: [
    { at: 3.3 },                 // 第 1 句：这个时刻开始念
    { gapAt: T.launch },         // 第 2 句：把句中的停顿（千里江陵｜一日还）对在 launch 这一刻
    { after: 0.3, min: 10.3 },   // 第 3 句：上一句念完 0.3 秒后，但不早于 10.3
  ],
});

句子少（绝句）就像上面这样，先定画面的时刻，再把每句朗诵摆上去。句子多（词、律诗）反过来：先定每句之间停多久（全用 after，长的停顿是留给画面的），朗诵的时刻由配音实际长度推出来，再把画面的动作挂在「第几句的哪个位置」上（T.v[i] 是第 i 句开口的时刻，T.vEnd[i] 是念完的时刻）。这样换音色、改语速，画面跟着走。写法见 examples/chibi/film/timing.js。

做的时候守住的几条（为什么）

• 每一帧只由时间决定。不用时钟、不用 Math.random（用 QZ.hash / QZ.rng）。渲染是多个进程乱序抓帧的，画面依赖「上一帧」就会错位。
• 全片只有红点是正红色。印章是它变的，所以也是红的；别的东西（太阳、旗子、花）用藤黄、胭脂、赭石。观众的眼睛靠这一点红跟住主角，检查脚本也靠它判断主角在不在画面里。
• 先空跑再配音。voice --dry 估出来的时长足够排场景；真配音按次收费，分镜没定就配是白花钱。同一音色同一段文字有缓存，重跑不再花钱。
• 动作卡在字上，写在时间表里。「千里江陵」和「一日还」之间朗诵会换气，小舟就在这口气里弹射出去；猿在念「猿声」的时候叫。这种对位是这类片子好看的原因，用 gapAt / at 把它写死，不要靠凑。
• 多音字写进 poem.json 的 say（朝→昭、还→环、重→崇）。合成用同音字，读音必然对；画面上写的永远是原字。你听不到，这是唯一能保证不念错的办法。
• 东西站在山上时，问贴图要高度（tile.hs），并且算对「画面 x → 贴图 x」的偏移。上次猿挂的树悬在半空，就是偏移加错了，看截图才发现。
• 末句的每个字要对着频谱图标时间（voice --spec，写进 poem.json 的 onsets）。不标就是平均分，笔会和声音错开。
• 水面上的东西，谁的水线低谁在前面。小舟的水线比礁石的水线高，却画在礁石后面，看上去就像船搁在石头上。先定每样东西的水线，再按从远到近的顺序画。
• 会淡到大字后面的场景里，别留东西在落款和片尾小字底下。两条片子都在这里翻过车；最干净的办法是让那样东西在红点离开后自己淡出。
• 声音没人听过。film.py score 会打印每段的频段占比和人声高出配乐多少分贝：60–150Hz 超过 45% 就是鼓太重，人声余量低于 7 分贝就是被盖住。交付时必须请用户听，并且如实说你没听过。

检查是流程的一部分

python3 tools/film.py qa

它做三件事：跑 HyperFrames 的工程检查；按时间表里的每个时刻抓一帧，自动查「几乎是白纸」「红点不在画面里」「红色太多」「画面没动」「这一帧报错了」；把这些帧拼成带时刻和事件名的总览图 build/qa/contact-N.jpg。总览图要自己打开看——脚本看不出构图空、字压住了主体、东西悬在半空。

一帧出错时，错误信息会用红底白字写在画面顶上（而不是静默卡住上一帧），所以看图就能发现。

film.py render 渲染后还会核对：帧数和时长对不对、响度是不是 −16 LUFS、每段朗诵在成片里的位置和计划差多少毫秒、中间有没有画面不动的片段、第一帧是不是白的。

参考文档

用范例新建一个能直接跑的工程：

python3 $SK/scripts/new_project.py videos/demo --example qingzhou

升级已有工程的引擎（不动 poem.json、film/、assets/、audio/）：

python3 $SK/scripts/new_project.py videos/<slug> --sync