code-poem-film

---
name: code-poem-film
description: 把一首古诗、一阕词（或一句诗、一段短文）做成 20–80 秒的「代码画的水墨手绘风 2D 动画」——一个红点小角色把诗走一遍，题签逐句写字，带朗诵，末句边念边写，红印章收尾；配乐和音效用 numpy 合成，封面是第一帧，最后给上传版和实测帖草稿。用户说「把 XX 这首诗 / 这首词做成动画」「做一条诗词动画 / 古诗动画 / 水墨动画」「像《早发白帝城》《赤壁怀古》那条一样做」「用代码画一首诗」「红点动画」「给这句诗配个动画和朗诵」「再来一首大气点的」时都用这个 skill；用户只给了一句诗、一个诗名、一个词牌，或者只说「下一首」也要用。不适用：有地图、有路线的历史纪录片（走 code-doc-film）、真人口播剪辑、产品宣传片、竖版视频（目前只做横版 16:9）。
---

# 代码诗词动画（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 工程，但这类片子不需要再走它的问答和分镜流程——这份文档就是完整流程。

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

| 步骤 | 做什么 | 命令 / 文件 |
|---|---|---|
| 1 定稿 | 把诗填进 `poem.json`：标题、作者、每句、印文、多音字 | `references/poem-json.md` |
| 2 空跑 | 不花钱：估每句时长，让起步片子先跑起来 | `film.py voice --dry` → `film.py build` → `film.py qa` |
| 3 分镜 | 每句诗画什么、红点做什么、哪个动作卡在哪个字上 | 写进 `film/timing.js` 的注释里；`references/acting.md` |
| 4 画场景 | 把起步片子里的「长卷」换成这首诗自己的画面 | `film/timing.js`、`film/scenes.js`；`references/scenes.md` |
| 5 看图 | 抓关键帧、看总览图，改到干净 | `film.py qa`；`references/qa.md` |
| 6 朗诵 | 真配音（缓存，同一段只花一次钱；长篇逐句合成）；读得太快的句子本地放慢；末句对着频谱图标每个字的时间 | `film.py voice --plan` → `film.py voice --spec`；`references/audio.md` |
| 7 编曲 | 每个声音绑在时间表的一个时刻上 | `film/score.py` → `film.py score` |
| 8 出片 | 检查 → 渲染 → 核对 → 上传版（长片另出 720p 小版）、封面、总览图、数字 | `film.py render` |
| 9 交付 | 发上传版和封面；说清没验证的；按实测写帖子草稿 | `references/delivery.md`；`film.py stats` |

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

### 四个文件各管一件事

| 文件 | 管什么 |
|---|---|
| `poem.json` | 字：标题、作者、诗句、印文、落款、多音字、音色 |
| `film/timing.js` | 什么时候：这首诗每个动作的时刻。朗诵、题签、末句、总时长由引擎按配音实际长度推出来 |
| `film/scenes.js` | 画什么：场景和红点的表演 |
| `film/score.py` | 响什么：每件乐器在哪个时刻响 |

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

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

```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 分贝就是被盖住。交付时必须请用户听，并且如实说你没听过。

### 检查是流程的一部分

```bash
python3 tools/film.py qa
```

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

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

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

## 参考文档

| 文件 | 什么时候读 |
|---|---|
| `references/poem-json.md` | 填 `poem.json`、写 `film/timing.js` 之前：全部字段、时间规则 |
| `references/scenes.md` | 画场景之前：舞台接口、画法库清单、镜头和视差、晕开/淡出/转场、怎么画新东西 |
| `references/acting.md` | 排红点的戏之前：压扁拉伸、蓄力、眼神、表情、和朗诵对位的几种办法 |
| `references/audio.md` | 朗诵和配乐：语音插件、多音字、读频谱图、乐器清单、自检数字怎么看 |
| `references/qa.md` | 检查和调试：每条警告的意思、翻过的车、浏览器预览 |
| `references/delivery.md` | 出片后：文件清单、交付时说什么、实测帖怎么写、数字从哪来 |
| `references/kit-1.jpg` … `kit-4.jpg` | 画法库里每样东西的样子。开工前看一眼，库里有的不要重画 |
| `examples/qingzhou/` | 完整范例《早发白帝城》（绝句）：连续镜头、视差、晕开、物体转场、远景、对位。短诗照着它改最快 |
| `examples/chibi/` | 完整范例《念奴娇·赤壁怀古》（词，72 秒）：按停顿排时间、逐句配音、一个世界换三个时辰、人物和火、画中画。长篇照着它改 |

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

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

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

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