Skip to content
Back to search

html-to-video

SkillWorks with Claude CodeGitHub

把 HTML/Canvas 动画逐帧渲染成 MP4(可配乐、可卡点、可出 GIF、可出透明层)。当用户说「用代码做视频」「HTML 转视频」「导出 MP4/GIF」「做个动态图解/宣传片/数据动画」「逐帧渲染」「换个风格」「卡点」「音乐配画面」「加运镜」「成片检查」「响度归一」时使用。自带渲染器、14 个版式模板(多镜头讲解片、竖屏 9:16、前后对比、流程图、字幕卡、引言卡、章节卡、界面演示)、14 种视觉风格(孔版印刷 / 木刻 / 剪纸 / 粉笔 / 铅笔 / 黏土 / 水墨 / 水彩 / 蓝图 / 等距 / 瑞士 / 半调 / 霓虹 / 玻璃拟态,分五个家族,一条命令切换)、节拍分析与卡点(--beats / --snap)、**镜头语言(12 个命名运动 + 5 种缓动,一行自然语言一条镜头,自带防露边)**、分镜预演、浏览器预览、环境自检、图标/人物/运镜素材库、**文案自检(字数 / 条数 / 陈词滥调 / 转折)**、**成片质检(hook / 黑场 / 冻结 / 重复帧 / 响度 / 联系表)**、**EBU R128 响度母版(−14 LUFS / −2 dBTP)**,支持透明输出、外部字幕时间轴与 JSON 镜头表,装好依赖后一条命令出片。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wx4766--html-to-video/badge.svg)](/listings/wx4766--html-to-video)

HTML

<a href="/listings/wx4766--html-to-video"><img src="/api/listings/wx4766--html-to-video/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

需要 Node.js >= 18。

**当普通 Node 工具用**(clone 到哪都行,三条命令):

git clone https://github.com/wx4766/html-to-video.git
cd html-to-video
npm install
npx playwright install chromium   # 首次必做:下载截图用的浏览器内核

另外需要 **ffmpeg 在 PATH 上**(`brew install ffmpeg` / `apt install ffmpeg` / `winget install ffmpeg`)。 别用 Playwright 自带的那个:它是 `--disable-everything` 裁剪版,编不了 H.264。

**当 WorkBuddy / Claude 技能用**(放进技能目录,AI 能直接调用):

git clone https://github.com/wx4766/html-to-video.git ~/.workbuddy/skills/html-to-video
cd ~/.workbuddy/skills/html-to-video
bash scripts/install-deps.sh

`install-deps.sh` 会自动做完三件事:

1. 探测本机 Playwright 浏览器缓存,挑**匹配的** playwright 版本 2. 装完整版 ffmpeg(同上,避开裁剪版) 3. 把工作区路径写进 `~/.workbuddy/.html2video-env`

想自己指定工作区:`bash scripts/install-deps.sh /path/to/workspace`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 1,419 lines
  1. ---
  2. name: html-to-video
  3. description: 把 HTML/Canvas 动画逐帧渲染成 MP4(可配乐、可卡点、可出 GIF、可出透明层)。当用户说「用代码做视频」「HTML 转视频」「导出 MP4/GIF」「做个动态图解/宣传片/数据动画」「逐帧渲染」「换个风格」「卡点」「音乐配画面」「加运镜」「成片检查」「响度归一」时使用。自带渲染器、14 个版式模板(多镜头讲解片、竖屏 9:16、前后对比、流程图、字幕卡、引言卡、章节卡、界面演示)、14 种视觉风格(孔版印刷 / 木刻 / 剪纸 / 粉笔 / 铅笔 / 黏土 / 水墨 / 水彩 / 蓝图 / 等距 / 瑞士 / 半调 / 霓虹 / 玻璃拟态,分五个家族,一条命令切换)、节拍分析与卡点(--beats / --snap)、**镜头语言(12 个命名运动 + 5 种缓动,一行自然语言一条镜头,自带防露边)**、分镜预演、浏览器预览、环境自检、图标/人物/运镜素材库、**文案自检(字数 / 条数 / 陈词滥调 / 转折)**、**成片质检(hook / 黑场 / 冻结 / 重复帧 / 响度 / 联系表)**、**EBU R128 响度母版(−14 LUFS / −2 dBTP)**,支持透明输出、外部字幕时间轴与 JSON 镜头表,装好依赖后一条命令出片。
  4. agent_created: true
  5. ---
  6. # html-to-video · 代码逐帧做视频
  7. ## 这套东西是什么
  8. **不是 AI 生成视频**,是**用代码逐帧画视频**:
  9. ```
  10. 写 HTML/Canvas,把画面写成 frame(t) 纯函数
  11. → 无头浏览器逐帧 seek 到 t,截图
  12. → ffmpeg 编成 H.264 MP4
  13. 字幕 / 运镜 / 转场全在代码里,改代码重渲即可
  14. ```
  15. 优点:**确定性**(同输入同输出)、**可控到帧**、**中文文字完美**、**零费用**。
  16. 最适合做:讲解动画、动态图解、产品演示、数据可视化动画、宣传片片头。
  17. 不适合:实拍感/氛围镜头(那种走 VideoGen)。
  18. **交付前四道关**(分别管四个不同的东西,别只跑一个):
  19. | 命令 | 管什么 | 查不出会怎样 |
  20. |---|---|---|
  21. | `h2v check story.json` | 文案 | 字太多读者跳读、全片没有转折 |
  22. | `assets/qa.sh page.html` | 页面 | 画面混了随机数、文字出框/叠字、字体悄悄回退 |
  23. | `h2v qc out.mp4` | 成片 | 前 2 秒没动、黑场、冻结、音轨静音 |
  24. | `h2v master in.mp4` | 声音 | 手机外放听着比别人小一截 |
  25. **能拿它做什么**(`assets/templates/` 里 14 个模板直接改字就能出片):
  26. | 模板 | 用途 | 出片 |
  27. |---|---|---|
  28. | `explainer.html` | **多镜头讲解片**:片头 / 人物+气泡 / 要点 / 条形对比 / 片尾,镜头带转场,可喂 JSON 镜头表;横屏恰好三条要点时自动并排成三栏,竖屏(1080×1920)另有上下版式 | `--duration=17.6` |
  29. | `title-card.html` | 视频片头:主标题逐字弹入 + 副标题 | `--duration=6` |
  30. | `bar-chart.html` | 条形图/排名:条形依次生长,数值同步滚动 | `--duration=6` |
  31. | `line-chart.html` | 折线趋势:折线生长 + 数据点亮起 + 末点浮标 | `--duration=8` |
  32. | `number-counter.html` | 大数字/KPI:从 0 滚到目标值 + 涨跌标签 | `--duration=7` |
  33. | `timeline.html` | 时间线/流程:中轴生长,节点逐个点亮 | `--duration=7` |
  34. | `vertical-card.html` | **竖屏 9:16 卡片**:大字标题 + 大数字,抖音/视频号/Reels 用 | `--duration=6 --width=1080 --height=1920` |
  35. | `compare.html` | **前后对比**:左右两栏对照,结论条收口 | `--duration=7` |
  36. | `flow-steps.html` | **流程图动画**:步骤依次点亮,当前步高亮 | `--duration=7` |
  37. | `subtitle-card.html` | **逐句解说卡**:一句话一句地出,底部带进度条 | `--duration=8` + `--srt` |
  38. | `vertical-subtitle.html` | **竖屏字幕卡**:关键词高亮,9:16 原生版式 | `--duration=8 --width=1080 --height=1920` + `--srt` |
  39. | `quote-card.html` | **引言卡**:大引号 + 引文逐行推进 + 出处短线 | `--duration=7` |
  40. | `chapter-card.html` | **章节卡**:序号水印 + 标题 + 章节进度点,切分长片 | `--duration=4` |
  41. | `ui-showcase.html` | **界面演示**:窗口推入 + 缓推 + 两处聚光标注,可换真实截图(`CFG.shot`) | `--duration=8` |
  42. 每个模板**单文件自包含**,顶部有一个显眼的 `CFG` 配置块,改文案/数据即可 ——
  43. 不用懂 canvas 也能出片。**14 个模板全部支持换主题与 14 种视觉风格**(见「换配色」一节)。
  44. 想做别的,再看 `assets/animation-skeleton.html` 从零写。
  45. **上面 14 个是「版式」。想要不同的「观感」,加一个 `--theme` 就有 14 种视觉语言**:
  46. ```bash
  47. bash assets/render.sh assets/style-film.html --duration=13 --theme=ink # 水墨
  48. bash assets/render.sh assets/style-film.html --duration=13 --theme=clay # 黏土立体
  49. bash assets/render.sh assets/style-film.html --duration=13 --theme=watercolor # 水彩
  50. ```
  51. 版式 × 风格 = 14 × 14 种组合。想先挑风格,跑一次十四宫格即可(见「风格」一节)。
  52. **做「一支片子」而不是「一段动画」**:用 `assets/lib/scenes.js` 写多镜头 + 转场,
  53. 镜头表还能用 `--story=shots.json` 外置 —— LLM 写 JSON 比写几百行 canvas 代码可靠得多。
  54. 详见下面「多镜头与转场」一节。
  55. ### 尺寸:模板跟视口走,不用手改
  56. 14 个模板都按 `window.innerWidth/innerHeight` 设画布,所以**换任何尺寸都不裁切**:
  57. ```bash
  58. # 横屏 1080p(默认)
  59. bash assets/render.sh title-card.html --duration=6 --fps=60
  60. # 竖屏 9:16
  61. bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1080 --height=1920
  62. # 720p / 4K 同理
  63. bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1280 --height=720
  64. ```
  65. 模板内部用三档缩放把设计稿落到实际画布:
  66. | 变量 | 含义 | 1920×1080 | 1080×1920 |
  67. |---|---|---|---|
  68. | `SX = W/1920` | 横向尺寸、左右边距 | 1 | 0.5625 |
  69. | `SY = H/1080` | 纵向尺寸、行距 | 1 | 1.7778 |
  70. | `SF = √(SX·SY)` | 字号、线宽、圆角、模糊 | 1 | 1 |
  71. 字号用面积等比(`SF`)而不是跟宽度走 —— 换成竖屏时字**不会变小**,只是版式铺开。
  72. `1920×1080` 下三者都等于 1,所以**默认输出与旧版逐像素一致**(实测 PSNR = inf)。
  73. **自己写的动画也照这个来**,否则改 `--width/--height` 会静默裁掉右下角:
  74. ```js
  75. const cv = document.getElementById('stage');
  76. cv.width = window.innerWidth; // ← 不要写死 1920
  77. cv.height = window.innerHeight; // ← 不要写死 1080
  78. ```
  79. 渲染器现在会主动量一次画布尺寸,比视口小就明确告警(不再静默出半张图)。
  80. ## 先装依赖(只需一次)
  81. 渲染器需要 **Node 工作区**(内含 playwright + 完整版 ffmpeg)。一条命令搞定:
  82. ```bash
  83. bash scripts/install-deps.sh # 工作区默认 ~/.workbuddy/binaries/node/workspace
  84. bash scripts/install-deps.sh /path/to/workspace # 或自己指定
  85. ```
  86. 它会自动探测本机浏览器缓存、挑匹配的 playwright 版本、装完整版 ffmpeg,
  87. 并把工作区路径写进 `~/.workbuddy/.html2video-env`,之后 render.sh / smoke.sh / qa.sh 开箱即用。
  88. 手动装也行(工作区需含 `playwright` + `@ffmpeg-installer/ffmpeg`),然后自己写配置:
  89. ```bash
  90. # ~/.workbuddy/.html2video-env
  91. WB_NODE_WORKSPACE="<你的 node 工作区绝对路径>"
  92. ```
  93. > 也可以用环境变量临时指定:`export WB_NODE_WORKSPACE="<路径>"`。
  94. > **不要**把路径写进 `${VAR:-默认值}`——用户名若含撇号(如 `O'Brien`),
  95. > bash 会把撇号当引号开始,报 `bad substitution`。
  96. ### 四条硬约束(踩过,别重犯)
  97. 1. **Playwright 版本必须和浏览器缓存匹配。**
  98. `playwright-core@X` 只认自己在 `browsers.json` 里声明的 chromium build 号,
  99. 不匹配就报 "Executable doesn't exist"。
  100. → **别猜版本,用 `scripts/install-deps.sh`**,它会跑 `scripts/detect-env.js` 探测缓存后自动挑版本。
  101. 单独探测:`node scripts/detect-env.js`(输出 `RECOMMEND_PW=...`)。
  102. 已知映射:build 1148→1.49.1、1155→1.50.1、1169→1.52.0、1187→1.55.0、1208→1.58.0。
  103. **注意**:某些网络环境下 chromium 下载会反复中断(表现为缓存目录里躺着半截的残缺目录)。
  104. 此时优先复用已有缓存而非升级——这正是探测脚本存在的理由。
  105. 2. **Playwright 自带的那个 ffmpeg 没用。**
  106. `ms-playwright/ffmpeg-*/ffmpeg-win64.exe` 是 `--disable-everything` 编译的,
  107. 只有 VP8 编码 + webm 封装,**没有 H.264、没有 GIF、连 PNG 解码都没开**。
  108. 必须用 `@ffmpeg-installer/ffmpeg` 的完整版。
  109. 3. **ESM 不认 `NODE_PATH`。** `.mjs` 里 `import 'playwright'` 必然 `ERR_MODULE_NOT_FOUND`。
  110. → 辅助脚本一律写 **CJS(`.cjs` / `require`)**。
  111. 4. **PATH 不可靠。** 尤其在 Git Bash / Windows 上,塞进 PATH 的 Windows 风格路径会被转换搞坏。
  112. → **别靠 PATH 传 ffmpeg,用 `FFMPEG` 环境变量**(渲染器已支持)。
  113. ## 三种入口:CLI / 预览 / 自检
  114. **统一命令**(`bin/h2v.js`,只是子命令到脚本的映射,不改任何默认行为):
  115. ```bash
  116. npx html-to-video doctor # 环境自检:缺什么、怎么修(只读)
  117. npx html-to-video templates # 14 个模板
  118. npx html-to-video styles # 14 种风格(按家族分组)
  119. npx html-to-video camera # 12 个镜头运动 + 一行字怎么写
  120. npx html-to-video new my-video --template=chapter-card
  121. npx html-to-video preview my-video.html --duration=6 --open
  122. npx html-to-video render my-video.html --duration=6 --fps=60
  123. npx html-to-video check story.json # 文案自检(字数 / 条数 / 陈词滥调 / 转折)
  124. npx html-to-video qc out/film.mp4 # 成片质检(hook / 黑场 / 冻结 / 响度 / 联系表)
  125. npx html-to-video master in.mp4 --video=in.mp4 --out=final.mp4 # 响度母版 −14 LUFS
  126. ```
  127. **一句话分工**:`check` 管文案,`qa` 管页面,`qc` 管成片,`master` 管声音。
  128. 四个都能 `--json`,Agent 直接读。
  129. **预览**:`scripts/preview.js` 起本地 http(ESM/fetch 都能跑),把页面放进 iframe,
  130. 注入 `__seekRender` 冻结它自己的时钟,然后用滑块/空格/←→ 直接推 `__seek(t)`。
  131. 竖屏项目记得 `--size=1080x1920`,否则预览框是横的、模板按 16:9 排版,会误判成版式崩了。
  132. **自检**:`scripts/doctor.js` 检查 Node / Playwright(含版本与浏览器缓存是否匹配)/
  133. ffmpeg(是否含 libx264 与 ProRes)/ 中文字体 / 临时盘余量 / 工作区配置,
  134. 阻塞项给可执行修法;`--json` 给 CI 与 Agent 用。
  135. ## 出片流程
  136. ### 第 0 步(最省事的路):挑一个模板改字
  137. ```bash
  138. npx html-to-video new my-video --template=bar-chart # 推荐:依赖一起搬好
  139. # 或者,如果就在仓库目录里工作:
  140. cp assets/templates/bar-chart.html my-video.html
  141. # 打开 my-video.html,只改顶部 CFG 里的 title / data / note
  142. bash assets/render.sh my-video.html --duration=6 --fps=60
  143. ```
  144. ⚠️ **模板不是单文件**:`./themes.js`(配色)和 `../lib/*.js`(动效 / 镜头 / 图形库)
  145. 必须跟着走。只 `cp` 一个 HTML 出去,页面会 404 —— 而渲染器把「页面报错」判为失败,
  146. 你看到的是「渲染失败」,很难联想到少文件。`h2v new` 会自动把依赖搬齐,
  147. 并把 `../lib/camera.js` 改写成 `./lib/camera.js`;手工搬的话记得这一步。
  148. 模板有**字幕安全区**意识:文字不会落在画面底部 15%(烧录字幕后会被盖住)。
  149. 自己做版式时也照这个来。
  150. ### 第 1 步:写动画 HTML(模板不够用时)
  151. 用 `assets/animation-skeleton.html` 当骨架。**核心契约**(渲染器靠它工作):
  152. ```js
  153. // 必须暴露这两个
  154. window.__seek = (t) => { /* 把 t 时刻的画面完整重绘一帧 */ };
  155. window.__ready = true; // 就绪信号
  156. // 渲染器会注入 window.__seekRender = true,
  157. // 此时必须【冻结自驱时钟】,完全由外部 __seek 推帧(保证确定性)
  158. if (window.__seekRender) { renderAt(0); window.__ready = true; }
  159. else { /* 浏览器预览:requestAnimationFrame 自驱循环 */ }
  160. ```
  161. **铁律:每一帧画面 = 时间 t 的纯函数。** 不要依赖「上一帧」的状态,
  162. 不要用 `Math.random()` / `Date.now()` / `performance.now()`——那会让同输入不同输出,
  163. QA 里的「确定性」会亮红灯,而且多 worker 并行渲染会各渲各的。
  164. **画布就是唯一输出**:`<canvas width=1920 height=1080>`,CSS 定位在 `left:0; top:0`,
  165. body `margin:0`。渲染器用 `clip:{x:0,y:0,width:W,height:H}` 截左上角,所以画布必须正好铺满视口、不能居中。
  166. (渲染器也支持 DOM/CSS/SVG 动画,同样只需暴露 `__seek`——但注意:DOM 动画每帧重排较慢,
  167. 纯 canvas 通常更稳更快。)
  168. **禁止使用的 class 名**(渲染器注入的 CSS 会无条件隐藏它们,元素会凭空消失):
  169. `.no-record .progress .progress-bar .counter .tCur .phases .phase-label .phase .replay .masthead .kicker .title .footer`
  170. 另外别给 `position:fixed/sticky` 的元素加 `<button>`,会被启发式规则当成播放控件隐藏。
  171. (想让某块**出现在成片里**,给它加 `data-record-keep="true"` 就能豁免启发式隐藏。)
  172. **中文字体**:`'"Microsoft YaHei", "PingFang SC", system-ui, sans-serif'`;等宽用 `'ui-monospace, Consolas, monospace'`。
  173. ### 第 2 步:冒烟测试(**别跳**)
  174. 先只截几帧,确认契约就绪、没控制台报错、画面没糊,再跑全量:
  175. ```bash
  176. bash assets/smoke.sh animation.html
  177. # SMOKE_T="0,1,2" SMOKE_W=1280 SMOKE_H=720 bash assets/smoke.sh animation.html
  178. ```
  179. 更快的迭代方式:**只渲一小段**,几秒就能看到动态效果。
  180. ```bash
  181. bash assets/render.sh animation.html --from=3 --to=5 --fps=30 # 只渲 3s–5s
  182. bash assets/render.sh animation.html --stills=1,3,5 # 只导出三张静帧
  183. ```
  184. ### 第 3 步:全量渲染
  185. ```bash
  186. bash assets/render.sh animation.html --duration=12 --fps=60 --width=1920 --height=1080 --concurrency=4
  187. ```
  188. 常用参数:
  189. | 参数 | 作用 |
  190. |---|---|
  191. | `--duration` / `--from` / `--to` | 时长 / 只渲某段(秒)。给了范围时输出名变成 `名.起-止s.mp4`,**不会覆盖成品** |
  192. | `--stills=0.5,2.0` | 只导出这些时刻的 PNG,不编码 |
  193. | `--fps` / `--width` / `--height` | 帧率与分辨率 |
  194. | `--preset=<名>` | 按平台预设定尺寸:`douyin` / `tiktok` / `vertical`(1080×1920)、`xiaohongshu`(1080×1440)、`instagram`(1080×1350)、`square`(1080×1080)、`bilibili` / `youtube` / `landscape`(1920×1080) |
  195. | `--presets=a,b,c` | **一条命令出全套比例**,每个比例一个成片(文件名自动加 `-比例名` 后缀)。跨平台发布用这个 |
  196. | `--theme=<名>` | 换主题(`midnight` / `paper` / `neon`),覆盖模板里的 `CFG.theme`,不用改文件。名字打错会明确告警并回退 midnight |
  197. | `--out=<文件>` | 指定成片路径(默认同目录同名)。一份 HTML 出多套配色时用它,否则后渲的会盖掉前一个;上级目录不存在会自动建 |
  198. | `--json` | stdout 只输出一行结果 JSON(`output` / `duration` / `frames` / `warnings` 等),人读日志全部走 stderr。给 Agent 解析用 |
  199. | `--concurrency` | 并行 worker 数(每个 worker 一个 Chromium 页面,注意内存)。给 `auto` 按 CPU 与内存自己挑 |
  200. | `--audio=<file>` | 编码后自动混音(视频流直接 copy,不重编码)。**没给 `--duration` 时自动按音频长度出片**(向上取整到整帧,尾音不被削) |
  201. | `--audio-fit=trim\|pad` | 音画长度不一致时怎么办:`trim` 按音轨收尾(默认)/`pad` 给音频补静音、保住视频长度 |
  202. | `--beats` / `--beats=<json>` | 分析 `--audio` 的拍点(或用预计算的网格),注入 `window.__beats` |
  203. | `--snap=beats` | 总时长吸到下一个拍点 |
  204. | `--snap-shots` | 镜头表里每个镜头的时长量化到整拍 |
  205. | `--bpm=<数>` / `--offset=<秒>` | 跳过估计,手工给 BPM / 首拍(纯配音硬卡点时用) |
  206. | `--gop=<秒>` | 关键帧间隔,如 `--gop=1` 每秒一个关键帧,方便后期按秒 seek |
  207. | `--keep-frames` | 成功也保留逐帧 PNG(换 CRF 重编码时不必重截) |
  208. | `--tmpdir=<目录>` | 逐帧 PNG 放哪块盘(默认挨着 HTML)。1080p 一分钟约 2.4 GB,系统盘没余量时指到别的盘 |
  209. | `--resume` | 上次渲到一半被打断?接着渲,已渲好的帧直接复用(参数和上次不一致会拒绝,见下) |
  210. | `--alpha` | 透明背景输出(ProRes 4444 `.mov`),叠到实拍 / AI 生成画面上用,见下 |
  211. | `--srt=<file>` | 外部字幕时间轴(SRT / VTT / JSON),注入 `window.__cues`,见下。同义参数 `--cues` |
  212. | `--cue-log=<file>` | 导出 `frame,t,cue_index,cue_start,cue_end` CSV,用来核对字幕到底对不对轴 |
  213. | `--story=<file>` | 镜头表 JSON,注入 `window.__story`,整份换掉剧本(见「多镜头与转场」) |
  214. | `--scene-log=<file>` | 导出镜头时间轴 CSV;镜头表总时长与 `--duration` 不一致会告警 |
  215. | `--gif[=fps,宽]` | 出片后顺手产 GIF(默认 15fps / 宽 960),两阶段 palette 优化,不重渲 |
  216. | `--poster=<秒>` | 出片后顺手抽一张封面静帧 `.jpg`,发站 / 社媒用 |
  217. | `--batch=<file.json>` | 一串任务按顺序渲,最后打汇总表;单个失败不连坐已渲好的,但整体非零退出 |
  218. | `--headed` | 开着浏览器窗口渲(调试用;并发自动降到 1,免得弹一排窗口) |
  219. | `--allow-errors` | 页面报错不判失败(默认:有报错 → 非零退出) |
  220. | `--keep-chrome` | 不隐藏播放控件(调试用) |
  221. | `--readytimeout=8` | 等 `__seek` 就绪的秒数(启动慢的大字体/大数据可调大) |
  222. | `--no-serve` | 用 `file://` 加载页面(默认走本地 http server,见下) |
  223. **ESM / fetch 项目直接能渲**。渲染器默认起一个只绑 `127.0.0.1` 的本地 http server 来加载页面 ——
  224. `file://` 下 `<script type="module">` 和 `fetch()` 会被 CORS 拦死,用 Vite/esbuild 组织的动画、
  225. 读本地 JSON 的项目根本起不来;走 http 就没这些事。渲染开头会打印这个地址,排障时直接粘到浏览器里看控制台最方便。
  226. 服务器起不来会自动退回 `file://` 并提示(只警告,不判失败)。
  227. - 输出与 HTML 同名的 `.mp4`
  228. - 帧数 = `fps × duration`。**12s@60fps = 720 帧,实测约 6~7 分钟**(concurrency=4)
  229. - 编码约 1 分钟(crf 18 / preset medium)
  230. **渲染结束有页面报错会非零退出**(但成片照样产出,方便你核对)。
  231. ### 渲到一半断了,别从零开始
  232. 长片子(60fps × 30s = 1800 帧)跑到 80% 崩了,从零重来最伤。加 `--resume` 就接着渲:
  233. ```bash
  234. bash assets/render.sh animation.html --fps=60 --duration=30 --resume
  235. # ▸ resume: 已复用 1432 帧,还需渲 368 帧
  236. ```
  237. 规则三条,都是为了「续出来的片子和一次渲完的片子一模一样」:
  238. - **帧先写 `.part` 再改名**。被 kill 的那一帧不会留下半个 PNG 冒充「已完成」,所以复用的帧都是真画完的。
  239. - **参数变了直接拒绝**。上次 30fps、这次 60fps 会把两批帧混着编码,片子前后节奏不一致还不报错 ——
  240. 所以 `fps / 尺寸 / 范围 / 渲染模式` 任一不同就退出并打印「上次 vs 这次」,让你自己决定删不删。
  241. - **帧号必须连续**。缺一张 ffmpeg 会静默提前收尾、成片莫名变短,所以编码前按 `[起,止)` 逐个核号,
  242. 有洞就报出来并提示加 `--resume` 补。
  243. 临时目录固定在 HTML 旁边的 `.seek-tmp-resume/`(不加 `--resume` 时仍是一次性目录,并发渲互不干扰)。
  244. 渲完自动清掉;中途想留着就配 `--keep-frames`。
  245. 这是故意的:页面报错常常意味着「整片黑屏 / 缺了半屏内容」,以前的版本会一路说成功,
  246. 直到你回抽帧才发现——现在它会在编码前就把报错打出来,并在最后判失败。
  247. ### 透明输出:把文字层叠到别人拍的画面上
  248. AI 生成的背景 + 代码生成的文字层,是现在最省钱的组合(模型画文字必糊,代码画文字精确到像素)。
  249. `--alpha` 就是为这条路准备的:
  250. ```bash
  251. bash assets/render.sh animation.html --duration=6 --fps=30 --alpha
  252. # → animation.mov(ProRes 4444 / yuva444p10le,背景透明)
  253. ```
  254. **模板侧要配合一件事**:读到 `window.__transparent` 为真时跳过背景层绘制。
  255. 目前 `title-card`、`compare`、`flow-steps`、`subtitle-card`、`vertical-subtitle`、
  256. `explainer` 这 6 个已经这样写,直接加 `--alpha` 就有透明效果;
  257. 其余 5 个是满版图表(条形 / 折线 / 大数字 / 时间线 / 竖屏卡),本来就要底色,加了也只会得到不透明的片子。
  258. 自己写的动画照这个来:
  259. ```js
  260. const TRANSPARENT = !!window.__transparent;
  261. function drawFrame(t) {
  262. g.clearRect(0, 0, W, H);
  263. if (!TRANSPARENT) {
  264. // 底色 / 全屏渐变 / 光斑 —— 这些都要跳过
  265. g.fillStyle = '#080A10';
  266. g.fillRect(0, 0, W, H);
  267. }
  268. // 文字、图形照常画
  269. }
  270. ```
  271. **全屏的半透明光晕也要一起跳过**。哪怕它只有 5% 不透明度,叠到实拍上会让整片区域泛白,
  272. 剪辑师第一反应是「这素材脏」。实测:只跳底色、留着光斑时,四角 alpha=12(不是 0);
  273. 全跳之后四角 alpha=0、只有 3.7% 的像素不透明(全是文字)。
  274. **体积代价**(960×540 / 2s / 20 帧实测):
  275. | 输出 | 体积 | 用途 |
  276. |---|---|---|
  277. | H.264 `.mp4` | 118 KB | 成片直接发 |
  278. | ProRes 4444 `.mov` | 760 KB(6.5×) | 拖进剪辑软件叠层 |
  279. **只有 ProRes,没有 VP9**。试过 `--pix_fmt yuva420p` + `-auto-alt-ref 0`,文件确实从 7.8KB
  280. 涨到 16.8KB(alpha 数据写进去了),但 Chromium 播出来整帧 alpha 全 0 —— 连文字都透明;
  281. 换 lossless、固定码率、`-lag-in-frames 0` 都一样。既然没法自证正确,就不把它作为选项发布。
  282. 要小体积透明素材,用 ProRes 导入剪辑软件后再导 webm,那是那边的活。
  283. ### 配音对齐:先有声音,再定画面长度
  284. 真实工作流是「写文案 → 配音 → 配画面」,而不是先定 6 秒再想办法把配音塞进去。
  285. 所以**给了 `--audio` 又没给 `--duration` 时,视频按音频长度出片**:
  286. ```bash
  287. bash assets/render.sh title-card.html --audio=voice.m4a --story=shots.json
  288. # ▸ audio: 音频 12.48s,未指定 --duration → 视频按音频定长(12.5s,向上取整到整帧)
  289. ```
  290. - **向上取整到整帧**,不是四舍五入:少半帧就会把最后一个字的尾音削掉。
  291. - 显式给了 `--duration` 且与音频差超过 0.35s 会**明确告警**,说清差多少、伤在哪边。
  292. 旧版本这里会静默出一支短片 —— 画面后半段整段消失,日志却只有一句 `✓ Done`。
  293. - `--audio-fit=pad`:音频比视频短时补静音,保住整段画面(默认 `trim` 按音轨收尾)。
  294. 注意:`trim` 下成片**不会精确等于音频秒数**。视频流是 `-c:v copy` 直接复制的,
  295. ffmpeg 只能按帧包边界收尾,实测会多留 0.3–0.5s。想要毫秒级对齐得重编码,
  296. 那是拿画质换精度,不值得 —— 片尾多留几帧通常看不出来。
  297. ### 卡点:让切点落在拍上
  298. 「切点落在拍上」是片子显得专业的最短路径。手工对齐是数秒表挪关键帧,
  299. 换一首 BGM 全部重来;这里把拍点量出来,镜头时长直接量化到整拍:
  300. ```bash
  301. bash assets/render.sh style-film.html --audio=bgm.mp3 --beats --snap=beats
  302. # ▸ 节拍: 120.14 BPM · 20 个拍点 · 首拍 0.49s · 置信度 0.85
  303. # ▸ 时长对齐拍点: 25.2s → 25.5s(+0.3s)
  304. bash assets/render.sh style-film.html --story=shots.json --beats=beats.json --snap-shots
  305. # ▸ 镜头对齐拍点(1 拍 = 0.499s):8 个镜头改了时长
  306. # · hook 2.80s → 3.00s
  307. # → 片长按镜头表定为 25.472s
  308. ```
  309. 规则(都是踩过才知道的):
  310. - **改镜头,不改 BGM。** 配乐是骨架;除非你明确要裁音乐,否则画面去迁就拍子。
  311. - **--snap-shots 会明说改了多少**,单镜变化 >25% 会警告 —— 节奏真的变了,导演得知道。
  312. - **没给 `--duration` 时,片长跟着镜头表走**;给了就以你为准,只告警不偷偷改。
  313. - **测不出稳定 BPM 就报警**,不硬卡。纯配音/环境音在物理上没有周期性重音,
  314. 这时候正确做法是按句子切(`--srt`),不是按拍切。
  315. - 模板侧:`window.__beats` = `{ bpm, offset, beats[], downbeats[], confidence }`;
  316. 风格库给 `SV.pulse(t)`(拍点处 1、按 `decay` 衰减)与 `SV.beatPhase(t)`。
  317. 没有 `--beats` 时 `pulse()` 恒为 0,所以同一份模板加不加卡点都能跑。
  318. 单独跑分析器(零依赖,纯 ffmpeg + 算术):
  319. ```bash
  320. node scripts/beats.js bgm.mp3 --json # {bpm, confidence, offset, beats:[...]}
  321. node scripts/beats.js bgm.mp3 --out=beats.json # 存下来复用(同一 BGM 出多条片子)
  322. ```
  323. 精度:120BPM 鼓点实测 BPM 误差 <2、相位误差 ~9ms;分析 10 秒音频约 25ms。
  324. ### 一稿多发:一条命令出全套平台比例
  325. 同一条片子要发抖音、小红书、B 站,剪辑软件里得一个比例一个序列、导一次盯一次。
  326. 这里版式本来就是参数化的,多渲一遍只是多一次循环:
  327. ```bash
  328. bash assets/render.sh bar-chart.html --duration=8 \
  329. --presets=douyin,xiaohongshu,square --out=dist/chart.mp4
  330. # → dist/chart-douyin.mp4 1080×1920
  331. # dist/chart-xiaohongshu.mp4 1080×1440
  332. # dist/chart-square.mp4 1080×1080
  333. ```
  334. | 预设 | 尺寸 | 给谁用 |
  335. |---|---|---|
  336. | `douyin` / `tiktok` / `vertical` | 1080×1920 | 抖音、快手、视频号、Reels、Shorts |
  337. | `xiaohongshu` / `xhs` | 1080×1440 | 小红书 3:4 |
  338. | `instagram` / `ig` | 1080×1350 | IG 信息流 4:5 |
  339. | `square` | 1080×1080 | 方版 1:1 |
  340. | `bilibili` / `youtube` / `landscape` | 1920×1080 | 横屏 16:9 |
  341. - 单个比例用 `--preset=xiaohongshu`;多个用 `--presets=a,b`(**至少两个**,只想要一个就用 `--preset`)。
  342. - 预设名拼错会直接失败并列出可用名字 —— 不会悄悄按 1920×1080 渲一版比例错误的片子。
  343. - **版式能不能撑住是另一回事**:模板跟视口自适应,但 9:16 与 16:9 的信息密度不同,
  344. 3:4 上字号偏大 / 内容偏挤要自己看一眼。`--presets` 只保证尺寸对,不保证构图好看。
  345. - **竖屏底部那块留白是故意的**,不是排版出错:平台进度条和按钮压在那儿,
  346. 模板统一给烧录字幕留了 15% 安全区。
  347. - 与 `--stills` 互斥(一个是出多片、一个是只截图);与 `--batch` 不能嵌套。
  348. ### 给 Agent 用:`--json`
  349. 这个工具的主力调用方是 AI Agent。人读 `✓ Done: xxx.mp4 (1.2 MB · 30fps · 12s)` 没问题,
  350. Agent 只能拿正则去猜 —— 路径里带空格、中文、括号就崩。`--json` 把结果结构化:
  351. ```bash
  352. bash assets/render.sh title-card.html --duration=6 --json
  353. ```
  354. ```json
  355. {"ok":true,"exitCode":0,"input":"…/title-card.html","output":"…/title-card.mp4",
  356. "width":1920,"height":1080,"fps":60,"duration":6,"frames":360,"bytes":2411724,
  357. "gif":null,"poster":null,"warnings":[],"mode":"video","theme":null,"preset":null}
  358. ```
  359. - **stdout 只有这一行**,进度与人读日志全部改道 stderr —— 直接 `JSON.parse(stdout)` 即可。
  360. - `warnings` 是数组:参数冲突、音画长度不符、主题名不认识都进这里。空数组 = 干净。
  361. - `duration` 是**成片实际时长**(ffmpeg 读回来的),不是计划值。
  362. - `--presets` 时 `output` 变成数组,另附 `presets: [{name,width,height,output,ok,bytes}]`。
  363. ### 字幕挂外部时间轴:配音改了,字幕跟着走
  364. 字幕文案写在模板的 `CFG.lines` 里最省事,但一旦要配音,时间点就得跟着音频走 ——
  365. 总不能每改一句都回去手数秒数。所以支持直接喂一坨字幕文件:
  366. ```bash
  367. bash assets/render.sh subtitle-card.html --duration=8 --srt=voice.srt --cue-log=cues.csv
  368. ```
  369. - 支持 **SRT**(`HH:MM:SS,mmm`)、**WebVTT**(`MM:SS.mmm` 也行)、**JSON**(`[{start,end,text}]`)。
  370. - 解析一次,注入 `window.__cues`,模板按当前帧的 `t` 自己去查该显示哪句。
  371. 模板里用 `--srt` 时**优先读 `__cues`,没有才回退 `CFG.lines`**,所以同一个模板两种用法都成立。
  372. - `--cue-log` 输出 `frame,t,cue_index,cue_start,cue_end` 的 CSV。把「字幕时间对不对」
  373. 变成一个能算的数:拿每句的首帧时间减 SRT 的起点,就是误差。
  374. 实测 4 句 / 80 帧,每句误差 **0 ms**,帧覆盖数与理论值完全一致。
  375. 模板侧只要两行就能支持:
  376. ```js
  377. const cues = (window.__cues && window.__cues.length) ? window.__cues : CFG.lines;
  378. const cur = cues.find(c => t >= c.start && t < c.end) || cues[cues.length - 1];
  379. ```
  380. **字幕别踩进底部 15%**。那是各平台的进度条 / 点赞按钮区,写进去等于白写。
  381. `qa.js` 会提示「进字幕带」,四个新模板的竖屏版式都留出了这条安全带。
  382. ### 换配色:改一个字段,不用碰画布代码
  383. `assets/templates/themes.js` 里有三套调色板,**14 个模板全部接入**;另有 12 套风格色板走 `lib/styles.js`。两种换法:
  384. ```bash
  385. # ① 命令行换(推荐):不改任何文件,一次渲染一个主题
  386. bash assets/render.sh bar-chart.html --duration=6 --theme=paper --out=bar-paper.mp4
  387. # ② 改文件:在模板顶部 CFG 里写死
  388. ```
  389. ```js
  390. const CFG = {
  391. theme: 'paper', // midnight(默认,暗色)| paper(浅色)| neon(黑紫霓虹)
  392. ...
  393. };
  394. ```
  395. 命令行优先于 `CFG.theme`(渲染器注入 `window.__h2vTheme`,模板读
  396. `h2vTheme(window.__h2vTheme || CFG.theme)`)。所以同一份 HTML 可以批量出三套配色:
  397. ```json
  398. [{ "html": "bar-chart.html", "duration": 6, "theme": "midnight", "out": "bar-dark.mp4" },
  399. { "html": "bar-chart.html", "duration": 6, "theme": "paper", "out": "bar-light.mp4" }]
  400. ```
  401. 批量里**必须配 `out`**:成片默认名是 `<HTML 名>.mp4`,同一个 HTML 渲两套配色
  402. 不换输出名的话,后一个会把前一个盖掉。
  403. | 主题 | 观感 | 适合 |
  404. |---|---|---|
  405. | `midnight` | 近黑底 + 暖橙强调 | 通用,默认 |
  406. | `paper` | 米白底 + 深墨文字 | 文档、教学、要打印或投影的场合 |
  407. | `neon` | 黑紫底 + 紫/青霓虹 | 科技、发布会、社区宣传 |
  408. 要微调就传对象,缺的字段自动从 `midnight` 补:
  409. ```js
  410. theme: { bg: '#0B1020', accent: '#22D3EE' }
  411. ```
  412. **加主题不背「默认画面偷偷变了」的债**,靠一条约定:`themes.js` 里
  413. `midnight` 只填 11 个基础字段,另外 5 个可选字段(`bgFar` / `accentDeep` /
  414. `accentSoft` / `sweep` / `onAccent`)只给 `paper` 和 `neon` 填;
  415. 模板一律写成 `TH.accentDeep || '<历史常量>'`。于是默认主题走的还是原来那些常量,
  416. 换主题时才用新色。测试会盯住这条约定(midnight 填了可选字段就报错)。
  417. **`themes.js` 是外部脚本,拷模板时连它一起拷**。只拷 HTML 会怎样:页面的兜底色板让画面
  418. 照常画出来,但 `<script src="./themes.js">` 会 404 —— 而渲染器把「页面报错」判为失败,
  419. 于是你会看到「Failed to load resource: 404」加一句渲染失败。**这不是画面坏了**,
  420. 把 `themes.js` 拷到同目录(或者加 `--allow-errors`)即可。
  421. `test/templates-contract.test.mjs` 会检查「登记了主题能力就必须真的引入
  422. themes.js,并且必须读 `window.__h2vTheme`」——后者保证命令行换主题不是空操作。
  423. ### 第 4 步:配乐 / 派生格式
  424. 渲染时加 `--audio=` 就能直接混音;需要更细的控制时用下面的命令:
  425. ```bash
  426. FF="<node工作区>/node_modules/@ffmpeg-installer/win32-x64/ffmpeg.exe" # Windows
  427. # 其它平台:FF="<node工作区>/node_modules/@ffmpeg-installer/ffmpeg"
  428. # 混 BGM(0.8s 淡入 / 1.4s 淡出,视频流不重编码)
  429. "$FF" -y -i animation.mp4 -i "$BGM" -filter_complex \
  430. "[1:a]atrim=0:DUR,afade=t=in:st=0:d=0.8,afade=t=out:st=DUR-1.4:d=1.4,volume=0.5[a]" \
  431. -map 0:v -map "[a]" -c:v copy -c:a aac -b:a 192k -shortest -movflags +faststart animation-bgm.mp4
  432. # GIF(两阶段 palette 优化,否则糊)
  433. "$FF" -y -i animation.mp4 -vf "fps=15,scale=960:-1:flags=lanczos,palettegen=stats_mode=diff" palette.png
  434. "$FF" -y -i animation.mp4 -i palette.png -lavfi "fps=15,scale=960:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" animation.gif
  435. # 竖屏:改 HTML 画布尺寸后重渲,别用裁剪
  436. ```
  437. ### 响度母版:`h2v master`(同一个片子,在不同平台一样响)
  438. 手机外放听着小、笔记本上听着大 —— 不是错觉,是没做响度归一。
  439. 平台之间的差异可以差 6–8 LU。母版的目标是 **−14 LUFS / −2 dBTP**(视频平台通行的落点)。
  440. ```bash
  441. node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4 # 带画面
  442. node scripts/audio-master.js voice.wav --out=voice-master.wav # 只要音频
  443. node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4 --no-limit # 不加限幅器
  444. ```
  445. **两遍 `loudnorm`,第二遍必须线性**:
  446. | 遍 | 干什么 | 为什么不能合成一遍 |
  447. |---|---|---|
  448. | pass 1 | 只**测量**(LUFS / LRA / true peak),丢弃输出 | 归一化要用到整片的统计量,必须先看完 |
  449. | pass 2 | 用测得的数值 `linear=true` 做**固定增益** | 一遍式是动态模式 = 边跑边压,会改变动态、抽气 |
  450. 两个坑,都踩过:
  451. - **LRA 超过目标时,`loudnorm` 会静默切回动态模式。** 报告里 `type` 字段不是 `linear`
  452. 就说明它偷偷加压限器了 —— 这时要放宽 `--lra` 或接受动态模式,别以为"归一成功了"。
  453. - **限幅之后要重新测量。** 限幅器改变峰值,pass 2 还用限幅前的数值会算错增益。
  454. 代码里是 `let m = measure('')`,限幅后 `m = r.m` 接回去 —— 用 `const` 就会静默错误。
  455. - **AAC 编码会把真峰值抬 0.5–0.7 dB。** 所以带视频时目标压到 −2 dBTP,留出编码余量。
  456. 限幅链固定为 `volume=${g}dB,alimiter=limit=…:attack=5:release=60:level=false`。
  457. `level=false` 是**必须**的:默认 `level=true` 会把输出自动抬到 0 dB,等于白限。
  458. (本机那版 ffmpeg 的 `alimiter` 没有 `latency` 参数,写上去整条 filter 会解析失败。)
  459. 实测一组:原始 −17.77 LUFS → 母版 −13.9 LUFS,真峰值 −1.8 dBTP,`type=linear`。
  460. ### 第 5 步:自动化验收(**交付前跑**)
  461. 渲染器只保证「帧渲出来了」,不保证「画面是对的」。这一步把肉眼最容易漏的问题量化:
  462. ```bash
  463. bash assets/qa.sh animation.html --duration=12 --fps=30
  464. ```
  465. 它做的事:
  466. | 维度 | 量什么 |
  467. |---|---|
  468. | 确定性 | 抽 首/中/末 3 个时刻,各做两轮逐像素比对:同页面 seek 回去(验累积状态)+ 全新页面重渲(验随机初始化)。不一致 = 画面里混了随机数/时钟/累积状态 |
  469. | 动感 | 相邻帧变化像素占比(运动%)、静止帧对比例、**最长连续静止秒数** |
  470. | 流畅 | 相邻帧差的峰值/中位数,报「跳变」时刻 |
  471. | 框景 | 从加载起 hook `fillText/strokeText` + DOM 文字行框 → 报**半截字 / 叠字 / 进字幕带 / 近空白** |
  472. | 字体 | 声明的字体是否可用、是否悄悄回退到兜底字体(缺字形是静默失败) |
  473. | 报错 | pageerror / console.error 清单(有则判失败,退出码非零) |
  474. 产物:`qa/qa.md`(表 + 线索清单)、`qa/qa.json`(原始数字)、`qa/<名>.heat.png`(运动热图)。
  475. 判据的脾气:**经验阈值,不是规则**。运动 0.5%–8% 多数好看;最长静止 ≥3s 会提示
  476. (有意定格可以忽略);跳变 >0 先去看那一帧;框景线索只是「去看一眼」的提示,不让 QA 失败。
  477. 关键参数:`--safe-bottom=0.15`(画面底部这个比例内出现文字就警告,烧录字幕会盖住;`0` 关掉)、
  478. `--skip=0.35`(跳过段首的镜头冲击)、`--samples=120`(采样帧数上限)。
  479. **采样间隔要 ≤0.1s**,否则一段快速位移在相邻两帧之间看着就像「跳」——那是采样假象不是穿帮。
  480. `qa.sh` 在间隔 >0.15s 时会提示该把 `--samples` 提到多少。(实测:同一段 title-card,
  481. `--fps=6` 报 2 处跳变,`--fps=30` 报 0 处。)
  482. > 已知盲区:画进离屏 canvas 再 `drawImage` 上来的文字追不到;被图形挡住的字查不到;
  483. > 采样从 `--skip` 之后开始,开场瞬间的问题看不到。这些都在报告里说明了。
  484. ### 成片质检:`h2v qc`(量的是**已编码的 mp4**,不是页面)
  485. `qa.js` 查的是页面(帧对不对),`qc.js` 查的是成片(片能不能用)。
  486. 两者不重复:编码参数、音轨、真实播放时的冻结与黑场,只有解码之后才看得见。
  487. ```bash
  488. node scripts/qc.js out/film.mp4 # 人看的报告
  489. node scripts/qc.js out/film.mp4 --json # Agent 读的 JSON
  490. node scripts/qc.js out/film.mp4 --hook-min=0.5 # 实拍片用严一点的 hook 门槛
  491. ```
  492. | 检查 | 判据 | 为什么值得单列一项 |
  493. |---|---|---|
  494. | `hook` | 前 2 秒相邻帧平均灰度差 ≥ 0.35 | 短视频前 2 秒没动 = 划走。用 `tblend=difference` + `signalstats` 量,不看"感觉" |
  495. | `black` | `blackdetect` 无 ≥0.3s 的黑段 | 模板淡入淡出常把首帧做成纯黑,人眼在播放器里看不出来 |
  496. | `freeze` | `freezedetect` 无 ≥1s 的定格 | 渲染卡住/时间轴算错会得到"看着像静帧"的片子 |
  497. | `dup` | 相邻帧完全相同的对数 | 与 freeze 互补:dup 抓"整段复制",freeze 抓"画到一半不动" |
  498. | `bright` | 平均亮度落在 16–240 | 全黑/全白通常是主题配错或图层顺序错了 |
  499. | `info` | 分辨率 / 帧率 / 时长 / 编码 / 采样率 | 一稿多发时确认没渲错比例 |
  500. | `cuts` | 场景切换点数量与位置 | 和镜头表对不上 = `--story` 没生效 |
  501. | `loud` | 有音轨时量响度,无音轨明确标 N/A | 见下面的响度母版 |
  502. | `sheet` | 抽 9 帧拼一张联系表 | 一眼扫完整片,比逐帧看快 |
  503. **hook 门槛的实测基线**(这是给阈值找依据,不是拍脑袋):
  504. | 画面 | 相邻帧平均灰度差 |
  505. |---|---|
  506. | 纯色静止 | 0.00 |
  507. | 极简标题卡(有文字入场) | 0.36 – 0.42 |
  508. | 同画面再加胶片颗粒 | 0.71 |
  509. | 正常有运动的片子 | 0.85 – 1.2 |
  510. 所以默认 `0.35`(数字/文字类刚好过线),实拍或强运动片建议 `--hook-min=0.5`。
  511. `hook` 失败会让进程 `exit 1` —— 这一条是硬规则,其余都是「提示去看一眼」。
  512. > 只用 ffmpeg,不依赖 ffprobe(很多精简环境没有)。元数据靠解析 `ffmpeg -i` 的 stderr。
  513. > 无音轨的片子走 `{ noAudio: true }` 分支,不会误报「有音轨但没声音」。
  514. ### 第 6 步:独立验证(别只看工具说成功)
  515. ```bash
  516. # 从成片回抽帧,亲眼确认画面
  517. "$FF" -y -ss 4.0 -i animation-bgm.mp4 -frames:v 1 -q:v 2 out/verify-4.0.jpg
  518. # 校验规格
  519. "$FF" -hide_banner -i animation-bgm.mp4 2>&1 | grep -E "Duration|Stream"
  520. # 解码完整性(无输出即无错误)
  521. "$FF" -v error -i animation-bgm.mp4 -f null -
  522. ```
  523. ⚠️ **验证渲染时务必换输出名或另建目录**。渲染器输出名固定为「HTML 同名 .mp4」,
  524. 拿真文件名跑一次短渲染验证,会把成品覆盖成短版。(踩过,只能重新编码。)
  525. 用 `--from/--to` 时输出名自带范围后缀,天然不会覆盖;也可以直接换目录。
  526. ## 文案:先写对,再写好看
  527. 技术再好,文案烂一样没人看完。这一段是**规则**,不是灵感建议 ——
  528. 完整版在 `references/writing.md`,下面是能立刻用的部分。
  529. ```bash
  530. node scripts/script-check.js story.json # 横屏:单行上限 14 字
  531. node scripts/script-check.js story.json --vertical # 竖屏:12 字
  532. ```
  533. 输出示例(真实跑出来的):
  534. ```
  535. 6 镜 / 20.5s / 193 字 / 9.4 字每秒
  536. 1. hook 3s 25 字
  537. ⚠ 2. points 4s 57 字 3 条
  538. 5. compare 3.5s 43 字
  539. ✗ 要改的:
  540. · 第 1 镜(hook)的 sub 有 17 个汉字 > 14:「渲染器自己量拍子,镜头时长量化到整拍」
  541. ```
  542. **四条最容易违反的**:
  543. | 规则 | 具体 | 为什么 |
  544. |---|---|---|
  545. | 一行不超过 14 字(竖屏 12) | 超了观众开始跳读,不是"信息量大" | 手机屏上一行塞 18 个字,字号必然缩到看不清 |
  546. | 每镜条目 ≤ 4 条(竖屏 ≤ 3) | 多了就不是"看",是"读" | 观众在一镜里能接住的信息有上限 |
  547. | 阅读速度 ≤ 12 字/秒 | 中文口播约 4.5 字/秒,屏幕文字可以快但要留出反应时间 | 快过这个数,字幕变成噪声 |
  548. | 一镜一个转折 | 6 种转法:对比 / 反转 / 代价 / 意外数字 / 时间跳 / 视角换 | 全片没有转折 = 没有"看到最后"的理由 |
  549. **字幕测试(caption test)**:把这句话当这一镜的图注读一遍 —— 如果它只是把画面又说了一遍,删掉。
  550. 旁白要加画面给不了的东西:潜台词、对照、过去、心里的声音、一条规则。
  551. **陈词滥调一出现就删**:「在这个时代」「随着……的发展」「赋能」「闭环」「未来已来」「重新定义」
  552. 「极致体验」。换成一个能拍出来的动作或一个具体数字 ——
  553. 「极致体验」→「按下到出片,4 秒」。
  554. **字数预算表**(要超之前先看这张):
  555. | 时长 | 旁白预算 | 单条屏幕文字 | 每镜最多几条 |
  556. |---|---|---|---|
  557. | 15 秒 | ≤ 65 字 | ≤ 12 字 | 2 |
  558. | 30 秒 | ≤ 130 字 | ≤ 14 字 | 3 |
  559. | 60 秒 | ≤ 260 字 | ≤ 16 字 | 4 |
  560. | 3 分钟 | ≤ 780 字 | ≤ 18 字 | 5 |
  561. `script-check.js` 只是机器能查的部分。剩下两条机器查不了,但必须做:
  562. **读出声**(打结的地方就是观众听不懂的地方)、**砍 30%**(第二遍不是润色,是删)。
  563. ## 动效库:assets/lib/motion.js
  564. 缓动、弹簧、步进、错开、拍号的纯函数库,和「冻结时钟 + `__seek(t)`」天然契合:
  565. ```html
  566. <script src="../lib/motion.js"></script>
  567. <script>
  568. const p = MO.expoOut(MO.seg(t, 0.3, 1.4)); // 0..1 进度
  569. const y = MO.lerp(80, 0, p); // 位移
  570. const s = 1 + MO.settle(t - 1.2, 0.06); // 到位后的余振
  571. </script>
  572. ```
  573. 选缓动的一句话:讲解类用 `MO.smooth` / `sineInOut`(两端都停稳);发布会用 `MO.appleOut` / `MO.snappy`;
  574. 动态大字用 `expoOut` + `MO.springHz`;纸片/拼贴按 `MO.step(t, 12)` 一拍二;逐项入场用 `MO.stagger`。
  575. **别让画面「死」掉**:一段动效做完后如果还要停留好几秒,加一点持续微动
  576. (慢速光扫、呼吸、漂浮 `MO.float`),否则观众会觉得视频卡住了。模板里都带了这一手。
  577. ## 多镜头与转场:assets/lib/scenes.js
  578. 一支能看的片子是「多镜头 + 转场」,不是几段动画硬拼。以前只能渲几段再拿 ffmpeg 拼
  579. (还要自己算 offset);现在**一个 HTML 里写镜头表**,渲染器照旧只管按 `t` 推帧,
  580. 转场在页面内合成 —— 一条命令照样出片。
  581. ```html
  582. <script src="../lib/scenes.js"></script>
  583. <script>
  584. const TL = SC.build([
  585. { id: 'hook', dur: 3.0, draw: (g, lt, c) => drawHook(g, lt, c) },
  586. { id: 'point', dur: 4.0, trans: { in: 'slide', dur: 0.5 }, draw: (g, lt, c) => drawPoint(g, lt, c) },
  587. ], { lead: 0.4, tail: 0.6 });
  588. function frame(t) { SC.paint(g, TL, clamp(t, 0, TL.dur - 1e-4), { W, H, bg: TH.bg }); }
  589. </script>
  590. ```
  591. | 转场 | 观感 | 什么时候用 |
  592. |---|---|---|
  593. | `fade` | 交叉溶解 | **文字类片子的默认**,讲理、讲解、数据 |
  594. | `dip` | 经底色过渡 | 两段情绪差得远;或两镜版式完全换掉 |
  595. | `slide` | 下一镜整块推入 | 满幅图形 / 照片 / 色块之间 |
  596. | `push` | 两镜贴着一起走 | 同上,更要方向感(流程往下走) |
  597. | `rise` | 下一镜从下方升起 | 竖屏、解说卡(两镜共用左边距时才稳) |
  598. | `zoom` | 变焦穿过 | 满幅画面之间,强调「一口气穿过去」 |
  599. | `wipe` | 竖边扫擦 + 扫描亮线 | 科技感、数据揭示(满幅图形) |
  600. | `cut` | 硬切 | 节奏紧、或转场时长给 0 |
  601. **选型铁律:画面里有文字,就只用 `fade` / `dip`。** 带位移的转场会把上一镜的文字
  602. 从中间切一半推走,两镜标题还会在同一位置叠成乱码 —— 观感是「画面坏了」,不是
  603. 「镜头动了」。位移类转场只留给边缘没有语义的画面(满幅图形、照片、色块)。
  604. 五条约定(踩过的):
  605. 1. **每个镜头的 `draw` 必须把背景画满**。转场是按 alpha 叠加两张画,
  606. 镜头自己留透明,交叉溶解时会透出底色,看着像闪一下。
  607. 2. **镜头动画一律用局部时间 `lt`**,不要用全局 `t`;转场窗口里上一镜的 `lt`
  608. 正好走到它自己的末尾(不会越界),所以镜头代码不用为转场写特例。
  609. 3. **带转场的镜头,别在 `draw` 里再叠一层整体淡入**。转场已经在做透明度了,
  610. 两层同时压 alpha,前 0.3 秒会糊成一团。`ctx.trans.dur > 0` 就跳过自己那层。
  611. 4. **退场侧要先把内容撤干净**:转场窗口里 `ctx.role = { side:'a'|'b', p }`,
  612. `side==='a'` 时把内容 alpha 按 `p` 收到 0(背景照画),`side==='b'` 的内容
  613. 晚 `0.22 × 转场时长` 起步。这样两镜内容永不同时在场 —— 这是文字类片子做溶解
  614. 不翻车的关键,标准写法见 `assets/templates/explainer.html` 的 `draw` 包装。
  615. 5. **转场是重叠的**:总时长 = Σ镜头时长 − Σ转场时长。加了转场,片子不会变长。
  616. 6. `SC.expose(TL)` 把镜头表挂到 `window.__sceneTable`,配渲染器 `--scene-log` 导出 CSV;
  617. **镜头表总时长与 `--duration` 不一致会告警**(否则结尾静默多一截静止画面)。
  618. 镜头表可以整份外置,LLM 写 JSON 最省事:
  619. ```bash
  620. bash assets/render.sh explainer.html --duration=17.6 --fps=30 --story=shots.json
  621. ```
  622. ```json
  623. [{ "kind": "title", "id": "hook", "dur": 3.0, "title": "..." },
  624. { "kind": "talk", "id": "why", "dur": 3.5, "say": "...", "trans": { "in": "fade", "dur": 0.45 } }]
  625. ```
  626. ## 先看分镜,再渲全片(省时间的关键一步)
  627. 一支 60 秒 1080p 的片子逐帧渲要 3~10 分钟。渲完才发现「第 4 镜字太小」「转场太赶」,
  628. 改一轮又要几分钟。**分镜板**只取每镜中点渲一张静帧,十几秒出,一页看完:
  629. ```bash
  630. node scripts/storyboard.js my.html # 4 列网格
  631. node scripts/storyboard.js my.html --cols=2 --theme=chalk
  632. node scripts/storyboard.js my.html --story=shots.json --width=1080 --height=1920
  633. ```
  634. 产出 `<名>.storyboard/`:每个镜头一张 PNG、一页带标注的 `storyboard.html`、一张整页截图
  635. `storyboard.png`(贴给别人问「这样行不行」最方便)。
  636. **什么时候必须先跑**:
  637. - 镜头 >= 3 个,或总时长 >= 10 秒
  638. - 改了版式/文案之后要重渲全片
  639. - 用户还没看过这支片长什么样
  640. **它靠什么知道镜头表**:页面里调过 `SC.expose(TL)` 就能读到 `window.__sceneTable`;
  641. 没调就按总时长均分(会提示)。所以写多镜头页面时,记得 expose 一句。
  642. 分镜板能看出的问题:镜头时长分配、层级(标题/正文/注释大小)、有没有哪一镜是空的、
  643. 风格与内容的匹配度。**看不出的**:动效手感、转场是否顺、音画是否对齐 —— 那些要出片或
  644. `--stills` 抽帧连看。
  645. ## 风格:8 种视觉语言,一条命令换
  646. 模板决定**画什么**(标题 / 要点 / 条形图),风格决定**长什么样**(什么纸、什么墨、线多粗、
  647. 字多紧、入场怎么动、签名元素是什么)。`assets/lib/styles.js` 把这两层拆开了。
  648. ```bash
  649. bash assets/render.sh assets/style-film.html --duration=13 --theme=chalk
  650. bash assets/render.sh assets/style-film.html --duration=13 --theme=水墨 --width=1080 --height=1920
  651. ```
  652. | id | 中文 | 一句话 | 适合 |
  653. |---|---|---|---|
  654. | `riso` | 孔版印刷 | 米白纸 + 三色网点(真实网角)+ 标题套印错位 | 观点、数据、独立杂志感(**默认**,辨识度最高) |
  655. | `cutpaper` | 剪纸拼贴 | 四边手撕的纸片 + 锐利硬投影 + 两张纸叠着 | 故事、人物、教育 |
  656. | `blueprint` | 工程蓝图 | 深蓝 + 双层格网 + 四角十字标记 + 等宽字 | 技术、架构、API |
  657. | `chalk` | 黑板粉笔 | 墨绿板 + 双线抖动笔触 + 粉尘 + 楷体 | 教学、科普 |
  658. | `isometric` | 等距线稿 | 白底 + 2:1 等距立体块 + 白面遮挡 | 机制、结构、流程 |
  659. | `synthwave` | 霓虹复古 | 条纹太阳 + 透视地面网格 + CRT 扫描线 | 音乐、游戏、复古科技 |
  660. | `swiss` | 瑞士网格 | 白底 + 超大字号 + 单一信号红 + 零圆角 | 品牌、观点、发布会 |
  661. | `ink` | 水墨宣纸 | 宣纸纤维 + 三层洇墨 + 朱红印章色 | 国风、文化、历史 |
  662. **中文名也认**(`--theme=水墨`、`--theme=剪纸`)。完整选择指南、每种风格的签名元素与禁忌
  663. 见 `assets/STYLES.md`。
  664. 两个现成入口:
  665. ```bash
  666. # 八宫格:一秒一个风格,出 8 张全屏静帧,一眼挑风格
  667. node scripts/render-video-seek.js assets/style-gallery.html --stills=0.5,1.5,2.5,3.5,4.5,5.5,6.5,7.5
  668. # 一支 13 秒的风格短片(片头 / 要点 / 数据 / 片尾),支持 --story 外置文案
  669. bash assets/render.sh assets/style-film.html --duration=13 --fps=60 --theme=riso
  670. ```
  671. **自己写页面时,四条硬约定**(踩过,都是"画出来是黑的"这种):
  672. 1. `SV.card()` **必须用返回值排版**。它返回 `{x, y, w, h, ink}` —— 内容安全框。
  673. 每种风格能放字的地方不同(等距只给顶面、水墨只给内圈、瑞士要反白),
  674. 拿原始 box 硬排,字一定压边或消失。
  675. 2. **每个镜头的 `draw` 自己画满背景**(`SV.bg(...)`)。`SC.paint` 里 `paintShot()`
  676. 会先 `clearRect`,漏了这步背景就是黑的。
  677. 3. **`SV.overlay` 放在最外层**,在所有镜头之上。放镜头里,转场时扫描线会跟着淡入淡出。
  678. 4. 纹理噪点用 `SV.rng(seed)`、手抖用 `SV.boil(st, t, i, amp)`,**不要 `Math.random()`** ——
  679. 它们是纯函数,换机器渲出来一模一样。
  680. **原来的 11 个模板已经全部接上风格**,不用改一行代码:
  681. ```bash
  682. bash assets/render.sh assets/templates/bar-chart.html --theme=blueprint --duration=6
  683. bash assets/render.sh assets/templates/explainer.html --theme=riso --duration=18
  684. bash assets/render.sh assets/templates/vertical-card.html --theme=synthwave --width=1080 --height=1920
  685. ```
  686. 换的不只是配色,背景整层被换成该风格的纸纹 / 网点 / 格网 / 透视地面,
  687. 气泡、图标底这些可选色也跟着明暗走。机制只有一句:模板背景层判断 `TH.__style`,
  688. 有就走 `SV.bgCached(...)`。**`styles.js` 不需要在模板里引** —— 渲染器启动时注入,
  689. 所以模板可以单独拷走、也可以在临时目录里跑测试,不会因为相对路径 404 被判失败。
  690. 哪种模板配哪种风格顺手,见 `assets/STYLES.md` 末尾的匹配表。
  691. ### 镜头类型:8 种,一条 JSON 排顺序
  692. `style-film.html` 内置 8 种镜头。给 `--story` 就是整份替换(给了 6 个镜头就渲 6 个,
  693. 不是只覆盖前 4 个):
  694. | id | 用途 | 关键字段 |
  695. |---|---|---|
  696. | `hook` | 片头 | `kicker` / `lines[]` / `sub` / `badgeNum` / `badge` |
  697. | `points` | 要点清单(2~4 条) | `head` / `items[{n,t,d}]` |
  698. | `quote` | 引用(左侧粗引线 + 大字) | `text` / `by` |
  699. | `steps` | 流程步骤(2~4 步,带箭头) | `head` / `items[{n,t}]` / `note` |
  700. | `metric` | 一个大数字 + 对比条 | `head` / `value` / `unit` / `note` / `bars[{label,p}]` |
  701. | `compare` | 前后对比 + 结论条 | `head` / `before{label,title,note}` / `after{...}` / `conclusion` |
  702. | `timeline` | 时间线(节点上下交错) | `head` / `items[{n,t}]` |
  703. | `outro` | 片尾 | `big` / `small` |
  704. 每个镜头都要 `dur`(秒)。8 个镜头 = 64 种组合(8 镜头 × 8 风格)。
  705. ```bash
  706. # 现成示例:8 个镜头串成一支 26 秒的片子
  707. node scripts/storyboard.js assets/style-film.html \
  708. --story=assets/examples/story-8shots.json --cols=4 # 先看分镜板
  709. bash assets/render.sh assets/style-film.html \
  710. --story=assets/examples/story-8shots.json --theme=chalk --duration=26
  711. ```
  712. **加新镜头类型**:写一个 `shotXxx(g2, lt, c)`,从 `SHOTS[c.index]` 取数据,
  713. 放进 `DRAW` 映射表。三条规矩:
  714. - 开头必须 `backdrop(g2, lt, c)` + `chrome(g2, 1)`
  715. - 所有卡片用 `SV.card()` 的返回值排版,字号用 `Math.min(理想值, cb.h * 比例)` 夹一道
  716. - 入场用 `SV.clamp((t - 延迟) / 时长)` + `SV.enter(ST, p)`,别自己写缓动
  717. ## 运镜与镜头语言:assets/lib/camera.js
  718. 分两层,互不干扰:**第一层是参数**(从哪到哪,像素级控制),
  719. **第二层是意图**(推、摇、环绕,一句话一条镜头)。老代码只用第一层,不受影响。
  720. ### 第一层:轻运镜(治「画面死了」)
  721. 画面元素都到位之后还剩几秒 —— 那几秒最容易「死」,`qa.js` 会报「最长连续静止」。
  722. 加一点持续运镜能活过来,而且比堆装饰元素更不抢戏。
  723. ```js
  724. const cam = CAM.breath(); // 呼吸:1.4% 的持续缩放,周期 4.2s
  725. CAM.withCam(g, CAM.at(cam, t, W, H), W, H, () => { /* 画内容 */ });
  726. ```
  727. | kind | 用途 |
  728. |---|---|
  729. | `breath()` | 极轻缩放,专门治「画面死了」 |
  730. | `kenburns({from,to})` | 缓慢推拉 / 平移(照片、大图镜头) |
  731. | `handheld` | 手持微抖:确定性伪噪声(**不是** `Math.random()`),多 worker 结果一致 |
  732. | `shake` | 撞击式震动,会衰减到 0(强调、转场落点) |
  733. | `stack([...])` | 多个运镜叠加:位移相加、缩放相乘 |
  734. 两条硬规矩:**运镜前先把底色铺满**(缩放/平移会露边);
  735. **缩放小于 1 一定露边**,要拉远就把内容画得比视口大。
  736. ### 第二层:镜头语言(一行字一条镜头)
  737. 专业分镜表里写的是「推镜,6 秒,缓入缓出」,不是 `from:[0,0,1] to:[0.02,0,1.06]`。
  738. 第二层让你直接把那句话喂进去 —— 这也是 [cinecode](https://github.com/sarpstar/cinecode)(MIT)的思路,
  739. 本项目按 Canvas 2D 重写了运动、缓动与手感,不是照抄。
  740. ```js
  741. const line = window.__h2vCamera !== undefined ? window.__h2vCamera : CFG.camera;
  742. const cam = (!TRANSPARENT && line && typeof CAM !== 'undefined') ? CAM.move(line, T, DUR) : null;
  743. if (!cam) { drawScene(T); return; } // 没镜头:一条像素都不变
  744. g.fillStyle = TH.bg; g.fillRect(0, 0, W, H); // 先铺底,否则露边
  745. CAM.begin(g, cam, W, H); // 内含 save()
  746. drawScene(T);
  747. CAM.end(g); // 内含 restore()
  748. ```
  749. `move()` 返回 `{ scale, tx, ty, rot, blur, bgScale, ... }`,**`tx/ty` 是比例不是像素**
  750. (`0.02` = 画宽的 2%),换分辨率不用改数值。
  751. **12 个运动**(`CAM.list()` 一次打印全部):写分镜先想「观众该感觉到什么」,再挑名字。
  752. | 名字 | 中文 | 感觉 | 默认 |
  753. |---|---|---|---|
  754. | `dolly in` | 推镜 | 亲近、紧张、"这件事重要" | 4s / inertia |
  755. | `dolly out` | 拉镜 | 孤立、释放、交代环境 | 5s / inOut |
  756. | `pan` | 横摇 | 扫视、跟随、把两件事连起来 | 4s / inertia |
  757. | `tilt` | 纵摇 | 仰视=敬畏,俯视=发现与重量 | 3.5s / inOut |
  758. | `orbit` | 环绕 | 审视、强调、英雄感 | 6s / inertia |
  759. | `crane` | 升降 | 希望、尺度、从上方揭示 | 5s / inOut |
  760. | `handheld` | 手持 | 在场、紧迫、纪实 | 跟镜头等长 |
  761. | `dolly zoom` | 变焦推拉 | 醒悟、不安、失真(**一片只用一次**) | 3.5s / inOut |
  762. | `rack focus` | 拉焦 | 注意力从一处移到另一处 | 1.2s / inOut |
  763. | `whip pan` | 甩镜 | 能量、跳切、喜剧 | 0.32s / inOut |
  764. | `push to` | 推近细节 | "看这里":线索、一个表情 | 3s / inOut |
  765. | `static` | 固定 | 让主体或光自己动 | 不动 |
  766. **一句话的语法**(容错优先,中英文混写都认):
  767. ```
  768. <运动名> [, <时长>] [, <缓动|速度>] [, <方向/锚点>]
  769. ```
  770. ```js
  771. 'dolly in, 6s, slow ease-in-out' // 推镜 · 6 秒 · 幅度调慢
  772. 'pan, 5s, medium, left' // 横摇 · 5 秒 · 往左
  773. 'handheld, 1' // 手持 · 幅度 1(时长跟镜头走)
  774. 'whip, 0.3s' '推镜,3s,慢' // 甩镜 / 中文写法
  775. ```
  776. - **时长**只认带单位的数字(`6s` / `6秒`);裸数字是**幅度**(`handheld, 1`),
  777. 只有该运动本身没有默认时长(`handheld` / `static`)时才当秒数。
  778. - **5 种缓动**:`linear` / `ease-in` / `ease-out` / `ease-in-out` / `inertia`。
  779. `inertia = 0.35·linear + 0.65·smoothstep` —— 两端都保留速度,所以镜头进、出都不"停死",
  780. 切点落在运动中间时不会看着像卡了一下。
  781. - 速度词(`slow` / `fast` / `慢` / `快`)**只改幅度不改时长**,时长仍由 `--snap-shots` 对齐拍点。
  782. **三条护栏,写代码时不用自己算**:
  783. 1. **防露边是默认的。** 所有运动都保证 `scale ≥ 1`,位移量按放大余量裁剪:
  784. `maxT = (scale - 1) / 2`,放多大就最多能平移多少画幅。想推 8% 就最多横移 4%,
  785. 写超了会被夹住 —— 宁可镜头少动,不露黑边。测试里 200+ 个时刻逐个验证过。
  786. 2. **同一帧永远长一样。** 手持抖动用正弦叠加 + 固定种子,不用 `Math.random()`;
  787. `move(line, t, dur)` 是 `t` 的纯函数,多 worker 并行渲染结果一致。
  788. 3. **`RETIME` 不重算镜头。** 换主题、改时长时用 `CAM.retime(line, newDur)` 只改速度,
  789. 不重新解析字符串。
  790. **CLI 上怎么用**:
  791. ```bash
  792. node scripts/render-video-seek.js page.html --camera='dolly in, 6s, slow' # 全片统一
  793. node scripts/render-video-seek.js page.html --camera=auto # 按镜头类型自动配
  794. node scripts/render-video-seek.js page.html --camera=off # 关掉,对比用
  795. ```
  796. `--camera=auto` 的导演逻辑在 `assets/style-film.html` 的 `AUTO_CAM` 表里,可按片子改:
  797. | 镜头 | 配什么 | 为什么 |
  798. |---|---|---|
  799. | `hook` | `dolly in` | 第一秒就要有"往前走"的感觉 |
  800. | `points` | `pan` | 扫过几条要点 = 一条视线把它们连起来 |
  801. | `metric` | `push to` | 数字是线索,推近 |
  802. | `quote` | `dolly in` | 让观众靠近那句话 |
  803. | `steps` / `compare` | `tilt` | 上下比较,眼睛自然会往下走 |
  804. | `timeline` | `crane` | 升降最能交代"一条时间线有多长" |
  805. | `outro` | `dolly out` | 拉远 = 收束、离开 |
  806. 优先级:代码里 `shot.camera`(字符串)> `window.__h2vCamera`(注入)> `CFG.camera`;
  807. `shot.camera: null` 和 `--camera=off` 都能把某个镜头/整片钉成不动。
  808. ## 素材库:图标 / 人物 / 图形
  809. 想画图标、箭头、卡片、人物,不用找图、也不用从零写 path —— `assets/lib/` 里有三个零依赖库:
  810. | 库 | 提供 |
  811. |---|---|
  812. | `shapes.js` | 40+ 线性图标(`SH.icon(g,'bolt',x,y,48,{color})`)、卡片 / 胶囊 / 箭头 / 正交连接线 / 虚线框 / 进度弧、网格 / 点阵 / 柔光 / 暗角 / 流动极光 / 胶片颗粒 |
  813. | `figures.js` | 参数化扁平小人:`FIG.draw(g, FIG.preset('dev', {x,y,h,t,pose:'wave',mood:'happy'}))`,发型 / 表情 / 姿势 / 配色全可调,自带对话气泡 `FIG.say()`;`FIG.shade(hex, -0.14)` 取同色系深浅一档 —— 袖子和上衣必须差一档,否则手会像浮在衣服上的色块 |
  814. | `camera.js` | 见上 |
  815. **为什么是代码画的元件,不是预置图片素材包**:版权干净(没有一张外部图)、
  816. 风格必然统一(同一套圆角线宽、跟着主题走)、任意分辨率都清晰、不占体积。
  817. **刻意不做**卡通人物位图包 / 标志性建筑照片包 —— 版权说不清、风格和用户自己的画面打架,
  818. 还会把仓库撑成几十 MB 的二进制库。要人物就用 `figures.js` 参数化生成。
  819. ```js
  820. SH.icon(g, 'bolt', x, y, 48, { color: TH.accent, width: 2.5 });
  821. SH.card(g, { x, y, w, h }, { fill: TH.panel, stroke: TH.faint, radius: 18 });
  822. FIG.draw(g, FIG.preset('host', { x: W * 0.22, y: H * 0.84, h: H * 0.42, t, pose: 'wave' }));
  823. ```
  824. ## 中文字体与跨机器一致
  825. 默认用系统字体(`Microsoft YaHei` / `PingFang SC`)。**这意味着"确定性"只在单机成立**:
  826. 同一个 HTML 换台没有这款字体的机器(比如 Mac),字形就会变。
  827. - 只是本机出片 → 不用管。
  828. - 要跨机器/跨人复现 → 自己内嵌一份子集字体:
  829. ```css
  830. @font-face { font-family: 'MyCJK'; src: url('fonts/subset.woff2') format('woff2'); font-display: block; }
  831. ```
  832. 子集化(只保留画面里真正用到的字,一个思源黑体 1.38MB → 约 300KB):
  833. 装 `fonttools` 后 `pyftsubset 源字体.ttf --text-file=<把文案导出成 txt> --flavor=woff2 --output-file=subset.woff2`。
  834. **只统计会画到画面上的字**——把注释里的中文也算进去,子集会胖很多倍。
  835. `qa.sh` 会检查字体可用性,并在「声明的字体其实没生效(悄悄回退了)」时给出警告。
  836. ## 程序化电影:一个世界,一条镜头轨迹(v2.0)
  837. 在这之前,所有模板都是「一镜一画」:每个镜头画到自己的离屏画布,再转场合成。
  838. 这套结构能出很干净的图表和卡片,但有三件事做不到:
  839. - 镜头**推过去看某个东西** —— 下一镜里那东西已经没了,因为每镜都是新画布;
  840. - 镜头**穿过**一个空间 —— 一条街、一列门、一层层结构,穿不过去;
  841. - **光随时间变** —— 窗外的天从黄昏暗到夜,只能靠叠一层半透明黑。
  842. v2.0 加了三层来补这三件事。三个库互相独立,可以只用其中一个。
  843. ### 空间:`assets/lib/space.js`
  844. 不是 3D 引擎(没有网格、没有光照模型、没有 z-buffer),只做一件事:
  845. **让镜头在一个连续空间里移动**。物体是贴在空间里的平面片,按深度排序、按距离缩放、加雾。
  846. ```js
  847. const cam = SP.cam({ pos: [0, -300, -1500], look: [0, -250, 400], fov: 46, w: W, h: H });
  848. const p = SP.project(cam, [120, 0, 600]); // → { x, y, z, s, vis }
  849. // x,y 屏幕像素 · z 相机深度 · s「1 世界单位 = 多少像素」
  850. ```
  851. | API | 用途 |
  852. |---|---|
  853. | `SP.cam({pos, look, fov, roll, w, h})` | 建相机。`roll` 做视角滚转(Pong 变通道那种) |
  854. | `SP.project(cam, [x,y,z])` | 投影。`vis=false` 表示在近裁剪面之后 |
  855. | `SP.sort(cam, items)` / `SP.draw(g, cam, items)` | 深度排序 / 排序后逐个回调 |
  856. | `SP.fog(cam, z, {near, far, max})` | 距离雾。伪造深度最便宜也最有效的一招 |
  857. | `SP.lerpCam(a, b, k)` / `SP.track(keys, t)` | 机位插值 / 关键帧相机 |
  858. | `SP.ring / grid / helix / rowZ / orbit` | 布局:摆物体最费事的是算坐标 |
  859. **坐标约定**:世界 x 右、y **下**、z 朝远离观众。相机在地面之上,所以 `y` 是负数。
  860. 这一条写错,楼会翻到天上去 —— 而且画面照画,不会报错。
  861. **手性别凭直觉改**:`basis()` 里那三行(`r = f × worldUp`、`u = f × r`)反了就是
  862. 左右颠倒 + 上下颠倒。`test/space.test.mjs` 里全是对方向的断言,改坏了会立刻红。
  863. ### 笔触:`assets/lib/brush.js`
  864. 版式模板一次画几十个元素,`fillRect` 量级够用。但「十万笔」「每帧百万笔」那种片子
  865. 不是靠更精细的代码,是靠数量级:单笔在十万笔里根本看不出来,能看出来的是整体的
  866. 疏密、方向、留白。这一层专门解决「量」。
  867. ```js
  868. const f = BR.field(120000, {
  869. seed: 7, area: { x: 0, y: 0, w: W, h: H },
  870. angle: BR.vortex(W / 2, H / 2, 1.0), // 方向场:漩涡
  871. len: [8, 44], wid: [1.1, 3.6], // 每笔长度 / 粗细
  872. color: BR.jitterColor([38, 58, 92], 0.10, 7, 6), // 同色系 6 档
  873. });
  874. BR.draw(g, f, { alpha: 0.9, reveal: k }); // reveal: 逐笔生长
  875. ```
  876. | API | 用途 |
  877. |---|---|
  878. | `BR.field(n, opts)` | 生成笔触场(TypedArray,确定性 rng) |
  879. | `BR.draw(g, f, {alpha, reveal, widMul})` | 按「颜色 × 粗细」分桶批量提交 |
  880. | `BR.drawDots(g, f, opts)` | 点画模式(星光、纸屑、雨) |
  881. | `BR.morph(a, b, k)` | 两个场插值 → 「纸张聚成鸟」 |
  882. | `BR.textPoints(text, opts)` + `BR.snap(f, pts, {k})` | 文字轮廓采样 + 笔触吸附 → 「笔触聚成字」 |
  883. | `BR.vortex / wind / dir / nz` | 方向场与噪声 |
  884. **为什么必须分桶**:10 万次 `fillRect` 每次过一遍状态检查,实测比批量 `stroke` 慢 15~20 倍。
  885. 分桶后 `stroke` 调用次数从 10 万降到十几个。
  886. **颜色必须量化**:桶数 = 色数 × 粗细档。颜色每笔都不同时桶数等于笔数,批量提交就白做了。
  887. `jitterColor` 走固定档位;`field` 的 `maxColors`(默认 32)兜底,超了就把通道量化合并。
  888. **实测**:12 万笔生成 61ms、morph 22ms、10 万笔吸附 310ms。
  889. ### 光照:`assets/lib/light.js`
  890. 「配色」和「光」不是一回事。同一组颜色,正午的硬光和黄昏的斜光完全是两支片。
  891. ```js
  892. const L = LT.timeline([[0, 'golden'], [0.2, 'dusk'], [0.6, 'night'], [1, 'night']], u);
  893. LT.grade(g, W, H, L, { alpha: 0.2 }); // 全屏统一色温
  894. LT.radial(g, { x, y, r, color: L.sun, i: 0.4 });
  895. LT.vignette(g, W, H, { amount: 0.45 });
  896. ```
  897. | API | 用途 |
  898. |---|---|
  899. | `LT.kelvin(K)` | 黑体辐射近似。1900K 烛光橙 / 5600K 日光 / 9500K 阴天冷蓝 |
  900. | `LT.sky(t)` | 昼夜循环(0=深夜 → 0.5 正午 → 1=深夜) |
  901. | `LT.timeline(keys, t)` | 任意关键帧。插值用 smoothstep,不是线性 |
  902. | `LT.grade / exposure / vignette / bloom / flash` | 全屏调色 / 曝光 / 暗角 / 泛光 / 闪白 |
  903. | `LT.radial / shaft` | 径向光 / 光束(体积光的 2D 近似) |
  904. **环境光与主光必须分开**:只调一个就是「加滤镜」,不是「换时间」。
  905. `SKY` 里每个预设都有 `ambient`(阴影里的颜色)和 `sun`(受光面的颜色)。
  906. **grade 用 overlay 而不是 multiply/screen**:它保留明暗只改色相。
  907. 用 multiply 会整体变暗,用 screen 会整体发白,都不像光。
  908. ### 承载体:`assets/templates/program-film.html`
  909. 这个模板把三层串起来:一条街、两排楼、一条推进的镜头轨迹、一段从日落到深夜的光。
  910. 默认出片 20 秒(`CFG.DUR`),改 `LINES` 换文案,改 `CFG.sky` 换光线时间轴。
  911. ```bash
  912. h2v new my-film --template=program-film
  913. # 改文件顶部的 CFG:DUR / sky / LINES
  914. h2v render my-film.html --duration=20 --fps=30
  915. ```
  916. `h2v new` 会把 `brush.js / space.js / light.js` 一起拷到 `./lib/` 并改好路径 ——
  917. v2.0 起不再写死 `camera.js`,模板引用哪个就拷哪个。
  918. ### 现在能做什么、做不了什么
  919. | 能做 | 例子 |
  920. |---|---|
  921. | 镜头在空间里推、摇、穿行 | 沿着一条街走、穿过一列门 |
  922. | 镜头「移过去讲某个东西」 | 3D 细胞课件那种「讲到核糖体,镜头转过去」 |
  923. | 十万级笔触的质感 | 油画、星空、灯海、纸张聚成鸟 |
  924. | 光随时间变 | 黄昏 → 夜 → 晨 |
  925. | 视角连续变换 | 平面游戏视角滚转成 3D 通道 |
  926. | 做不了 | 原因 |
  927. |---|---|
  928. | 阴影贴图 / 屏幕空间反射 / PBR | 画家算法没有 z-buffer,阴影只能靠「高度 AO + 方向光」暗示 |
  929. | 逐像素 shader(流体、火焰、折射) | Canvas 2D 没有可编程管线 |
  930. | 次表面散射、真实金属反射 | 用半球光 + Blinn 高光 + 逐面取色去「暗示」,不是物理模拟 |
  931. | 百万级粒子每帧现算 | 单帧 100 万次 draw 调用在浏览器里是秒级。要么预渲染,要么不到这个量 |
  932. > v2.1 起,**逐面着色**(Lambert + Blinn + 边缘光 + 半球光 + AO)已经有了,
  933. > 见下一节。上面「平面着色」的限制只适用于 `space.js` 的 billboard 路径。
  934. 需要真 3D 时:直接用 `three.js` + 我们这套渲染器(它只认 canvas,不关心你怎么画)。
  935. `--alpha` 透明输出也可以把 WebGL 图层叠到实拍上。
  936. ## 实体世界:能受光、能转身、有材质(v2.1)
  937. `space.js` 的 billboard 解决「空间连续」,但平面片没有法线 —— 不能着色、
  938. 不能转身、做不出曲面。要「像真的」,需要**面**。
  939. 三层,按依赖顺序加载:
  940. ```html
  941. <script src="../lib/space.js"></script>
  942. <script src="../lib/light.js"></script>
  943. <script src="../lib/solid.js"></script> <!-- 实体:几何 + 着色 -->
  944. <script src="../lib/atmos.js"></script> <!-- 大气:雾 / 光束 / 星芒 / 颗粒 -->
  945. <script src="../lib/lens.js"></script> <!-- 镜头:轨道 / 对数推拉 / 呼吸 -->
  946. ```
  947. ### `solid.js`:几何 + 着色
  948. ```js
  949. /* 几何:全部是纯数据,生成一次,每帧只投影 */
  950. const tower = SD.lathe([[24,0],[22,-50],[17,-150],[12.5,-224]], 24, { color:[230,226,216] });
  951. const ball = SD.sphere(50, { seg: 24, rings: 16, color:[200,120,90], mat:'matte' });
  952. const rock = SD.terrain(132, 132, 1700, 1700, (u,v)=>H(u,v), { color:[104,100,96], mat:'rock' });
  953. const pipe = SD.tube([[0,0,0],[0,-100,40]], r => 6 - 2*r, { seg: 10 });
  954. const crate = SD.box(40, 40, 40, { color:[120,90,60] });
  955. /* 逐面取色:岩石分层、金属污渍、地形渐变。不给就是整块单色 */
  956. rock.colorBy = (x, y, z) => y > 0 ? [40,36,36] : [96 + y*0.2, 98, 104];
  957. rock.bump = 0.24; // 表面粗糙度(扰动法线,不是加几何)
  958. /* 变换在生成时算好,不每帧算 */
  959. const placed = SD.xform(crate, { p:[200, -50, 300], ry: 0.7, s: 1.4 });
  960. /* 光照:自动布光(以机位为基准,永不逆光) */
  961. const L = SD.keyLight(LT.sky('dusk'), cam, { azimuth: -40, elev: 24, fill: 0.2 });
  962. SD.draw(ctx, cam, [tower, ball, rock, placed], L);
  963. ```
  964. **材质**:`matte` / `rock` / `metal` / `glass` / `emissive` / `water` / `skin`。
  965. **性能**:17,000 面 / 1080p 单帧 20–45ms。面数在生成侧控制(`seg` / `rings` / `terrain` 的网格数)。
  966. 三个必须知道的约定:
  967. 1. **`dir` 是「从物体指向光源」**。放在相机同侧才是正面受光;放反了正面全黑,
  968. 而灯还亮着,很难一眼看出是光的问题。用 `keyLight()` 就不会错。
  969. 2. **颜色要过色调映射**。线性乘出来的值直接当 sRGB 用会整体偏暗,
  970. 别以为是材质色选错了。`light()` 内置 1K 查找表做曝光 + 高光滚降 + gamma。
  971. 3. **绕序写反不会报错**,只会出现「太阳从地下照上来」。生成器内部有 `orient()`
  972. 自动校正;自己拼 `fromFaces()` 时要给对。
  973. ### `lens.js`:镜头语言
  974. ```js
  975. /* 球坐标机位:az 绕主体转、el 升降、dist 推拉 */
  976. const cam = LN.orbitCam([0,-200,0], { az: 0.6, el: 0.1, dist: 560, fov: 34, w, h });
  977. /* 轨道关键帧:在参数空间插值 —— 镜头绕主体转,不穿模 */
  978. const cam2 = LN.orbitTrack([[0,{az:0,dist:900}], [6,{az:2.4,dist:300}]], target, T);
  979. /* 对数推拉:16 倍推近,前快后慢 */
  980. const cam3 = LN.push(target, { from: 1500, to: 92, u, ease: LN.EASE.inOutCubic });
  981. /* 给半径 + 景别,自动算距离(大远景 / 远景 / 中景 / 近景 / 特写) */
  982. const d = LN.distFor(120, 'close');
  983. /* 手持呼吸:三个不同频率的正弦叠加,不是随机抖动 */
  984. LN.apply(cam, LN.handheld(T, { amp: 0.9, speed: 0.8, seed: 3 }));
  985. ```
  986. ### `atmos.js`:介质与后期
  987. ```js
  988. AT.sky(ctx, W, H, { horizon: 0.55, stops:[[0,'#0b1322'],[1,'#e6a05f']], band:'#ffb871', bandX: W*0.7 });
  989. AT.stars(ctx, W, H, { horizon: 0.55, n: 300, t: T, i: 0.8 });
  990. AT.haze(ctx, W, H, { y: 0.50, h: 0.16, color:'#6a4a44', i: 0.42 });
  991. AT.beam(ctx, { x, y, angle: -2.9, len: 1700, w0: 10, w1: 380, spread: 0.3, i: 0.4, rays: 58 });
  992. AT.glow(ctx, { x, y, r: 120, color:'#ffe3b4', i: 0.6 });
  993. AT.flare(ctx, { x, y, len: 160, color:'#fff6dc', i: 0.4 });
  994. AT.water(ctx, W, H, horizonY, { t: T, x: sunX, rows: 46 });
  995. AT.grain(ctx, W, H, { i: 0.05, t: T });
  996. ```
  997. 画这些的顺序就是「什么挡住什么」:**天空 → 星 → 水 → 远景 3D → 雾 → 近景 3D → 光 → 后期**。
  998. 雾插在两次 3D 绘制之间是有意的 —— 一张 z-buffer 做不到「只雾远景」,
  999. 分层反而能精确控制。
  1000. ### `scripts/foley.js`:程序化音效
  1001. ```bash
  1002. node scripts/foley.js --list
  1003. node scripts/foley.js --out=bed.wav --dur=41 --preset=lighthouse
  1004. node scripts/foley.js --out=bed.wav --dur=20 --events=foley.json
  1005. h2v render film.html --duration=41 --audio=bed.wav # 直接混进成片
  1006. ```
  1007. 八个音色:`wave`(海浪)/ `wind` / `hum`(灯丝)/ `foghorn`(雾笛)/ `paper` / `brush` /
  1008. `impact` / `chime`。全部是「噪声整形 + 双二阶滤波 + 包络」合成,带 Schroeder 混响。
  1009. **为什么要自己合成**:外部素材有版权、节奏对不上、装不上(本项目硬依赖只有 playwright + ffmpeg)。
  1010. 而「海浪」本质就是「低频噪声 + 周期 7 秒的慢包络 + 一层高频泡沫」,三十行代码就能做。
  1011. ### 完整例子:`assets/templates/lighthouse.html`
  1012. 41 秒 / 7 镜 —— 一条「一个人,一座塔,一整夜」。
  1013. ```bash
  1014. h2v new my-world --template=lighthouse
  1015. h2v render my-world.html --duration=41 --fps=30 --audio=bed.wav
  1016. ```
  1017. 它同时演示了:实体几何(礁石 / 塔身 / 灯室)、逐面取色(岩层 / 盐渍 / 苔)、
  1018. 球坐标环绕、对数推轨、昼夜插值(黄昏 3000K → 深夜 6800K)、射线束、星芒、
  1019. 水面波纹、胶片颗粒,以及声音与画面的**同一个时间码**(13.6s 灯亮 = 嗡鸣淡入)。
  1020. ## 渲染中途 ffmpeg 失败怎么办
  1021. **帧不会丢**:渲染器在编码失败时保留 `.seek-tmp-*/` 里的全部 PNG,并打印出可直接粘贴的编码命令。
  1022. 修好 ffmpeg 后手动编码即可,不必重截 720 帧:
  1023. ```bash
  1024. "$FF" -y -framerate 60 -start_number 0 -i .seek-tmp-*/frame-%06d.png -c:v libx264 -pix_fmt yuv420p \
  1025. -crf 18 -preset medium -r 60 -movflags +faststart animation.mp4
  1026. ```
  1027. 顺带:`.seek-tmp-*/` 有 720 张 PNG,**约 316 MB**。成功渲染后会自动删;加 `--keep-frames`
  1028. 可以主动留住(换画质重编码时省一次渲染)。
  1029. > 某些沙箱/托管环境给 `fs.rmSync` 套了「批量删除保护」,一次删几十个文件会被拦下。
  1030. > 这时渲染器会提示「逐帧目录没能自动删除」并给出路径,**成片不受影响**——手动删那个目录即可。
  1031. > 这也是为什么有时会看到残留的 `.seek-tmp-*` 目录。
  1032. ## 文件说明
  1033. | 文件 | 作用 |
  1034. |---|---|
  1035. | `scripts/render-video-seek.js` | 渲染器内核(冻结时钟 + 逐帧 seek 截图 + ffmpeg 编码 + 报错判定),自包含 |
  1036. | `scripts/qa.js` | 自动化验收(确定性/动感/流畅/框景/字体/报错),纯 Node 零新依赖 |
  1037. | `scripts/qc.js` | **成片质检**:hook / 黑场 / 冻结 / 重复帧 / 亮度 / 场景切换 / 响度 / 联系表,只依赖 ffmpeg |
  1038. | `scripts/audio-master.js` | **响度母版**:两遍 `loudnorm` 线性归一 → −14 LUFS / −2 dBTP,可选限幅 |
  1039. | `scripts/script-check.js` | **文案自检**:单行字数 / 每镜条数 / 阅读速度 / 陈词滥调 / 有没有转折 |
  1040. | `references/writing.md` | 文案规则全文:分叉收敛、六种转折、字数预算、陈词滥调清单、首次观看者检查 |
  1041. | `references/style-recipe.md` | **加新风格前必读**:十一章骨架(本质/材料/色彩/字体/运动/运镜/声音/招牌动作/介质陷阱/实现映射/可变空间)、每章写到什么颗粒度、查旧风格的五问、本项目固定陷阱清单、我们做不了的清单 |
  1042. | `scripts/lib/hide-chrome.cjs` | 「隐藏播放控件」的共享规则,渲染器与验收器用同一份,规则不会漂移 |
  1043. | `scripts/lib/local-server.cjs` | 本地 http 静态服务器(只绑 127.0.0.1),解锁 ESM / fetch;零新依赖 |
  1044. | `scripts/detect-env.js` | 探测本机浏览器缓存,输出该装哪个 playwright 版本 |
  1045. | `scripts/install-deps.sh` | 一键装依赖并写配置(探测 → 装 → 落地配置文件) |
  1046. | `scripts/bench.js` | 性能基线:量 `s/帧` 并估算长片耗时,产出 `bench/bench.md` |
  1047. | `assets/render.sh` | 全量渲染包装器,自动解析 node 工作区与 ffmpeg 路径 |
  1048. | `assets/smoke.sh` / `smoke.cjs` | 冒烟测试:验证 `__seek` 契约 + 试截关键帧 |
  1049. | `assets/qa.sh` | 验收包装器,环境解析同上 |
  1050. | `assets/animation-skeleton.html` | 动画骨架模板,已实现完整渲染契约 |
  1051. | `scripts/lib/cues.cjs` | 字幕时间轴解析(SRT / VTT / JSON),会自动排序并修掉时长非正、首尾重叠的 cue |
  1052. | `scripts/lib/qa-rules.cjs` | 验收判据的纯函数(框景 / 持续 / 分块 / 统计),可脱离浏览器单测 |
  1053. | `assets/templates/*.html` | 16 个开箱即用模板(多镜头讲解片/片头/条形图/折线/大数字/时间线/竖屏卡/前后对比/流程图/解说卡/竖屏字幕卡/**程序化电影**),改 CFG 即用 |
  1054. | `assets/templates/program-film.html` | **程序化电影**:一个世界 + 一条镜头轨迹 + 一段日光变化。笔触、2.5D 空间、光照三层串起来的最小完整例子 |
  1055. | `assets/templates/lighthouse.html` | **实体世界**:41 秒 / 7 镜,礁石+灯塔+灯室实模、岩层取色、对数推轨、环绕、昼夜、射线束、星空、颗粒。四层(solid/atmos/lens/foley)串起来的完整片 |
  1056. | `assets/templates/themes.js` | 三套内置主题(midnight / paper / neon),新模板用它换配色 |
  1057. | `assets/lib/motion.js` | 动效时间库(缓动/弹簧/步进/错开),纯函数、零依赖 |
  1058. | `assets/lib/scenes.js` | 多镜头时间轴 + 8 种转场(cut/fade/dip/slide/push/rise/zoom/wipe),纯函数、零依赖 |
  1059. | `assets/lib/camera.js` | **两层**:运镜(推拉 / 呼吸 / 手持微抖 / 撞击震动,确定性伪噪声)+ **镜头语言**(12 个命名运动 / 5 种缓动 / 一行字解析 / 防露边),确定性 |
  1060. | `assets/lib/space.js` | **2.5D 空间**:透视投影 / 深度排序 / 距离雾 / look-at 相机 / 关键帧轨迹 / 环形·网格·螺旋布局 |
  1061. | `assets/lib/brush.js` | **大规模笔触**:TypedArray 笔触场 / 颜色×粗细分桶批量提交 / 形态插值 / 文字吸附 / 方向场(十万笔量级) |
  1062. | `assets/lib/light.js` | **光照**:黑体色温 / 昼夜关键帧 / 径向光·光束 / 全屏调色·曝光·暗角·泛光 |
  1063. | `assets/lib/solid.js` | **实体与着色**:box / lathe / sphere / tube / terrain 几何 + Lambert·Blinn·边缘光·半球光·AO + 色调映射 + 逐面取色 + 法线自校正 |
  1064. | `assets/lib/atmos.js` | **大气与后期**:天空 / 星空 / 贴地雾 / 体积光束(射线束)/ 辉光 / 星芒 / 胶片颗粒 / 水面 / 浮尘 |
  1065. | `assets/lib/lens.js` | **镜头语言**:球坐标机位 / 轨道插值 / 对数推拉 / 景别距离 / 手持呼吸 / 切镜表 |
  1066. | `scripts/foley.js` | **程序化音效**:8 种音色 + 事件表 + Schroeder 混响 + 软限幅,输出 48kHz 立体声 WAV |
  1067. | `assets/lib/shapes.js` | 图形元件:40+ 线性图标 / 卡片 / 箭头 / 正交连接线 / 背景纹理 |
  1068. | `assets/lib/figures.js` | 参数化人物(发型 / 表情 / 姿势 / 配色)+ 对话气泡 |
  1069. | `assets/lib/styles.js` | **风格库**:14 种视觉语言,分五个家族(印刷 / 手作 / 绘画 / 信息图 / 数字界面),`SV.bg` / `SV.text` / `SV.card` / `SV.bar` / `SV.overlay` / `SV.boil` / `SV.BEAT` / `SV.pulse` / `SV.FAMILY` |
  1070. | `assets/STYLES.md` | 风格选择指南:每种风格的签名元素、适用场景、禁忌、加新风格的字段清单 |
  1071. | `assets/style-film.html` | **风格短片**:片头/要点/数据/片尾 4 镜,8 风格通用,支持 `--story` 与横竖屏 |
  1072. | `assets/style-gallery.html` | 八宫格风格样张,第 k 秒一个风格,配 `--stills` 一次出 8 张静帧 |
  1073. | `scripts/storyboard.js` | **分镜预演**:每镜中点一张静帧 → 一页分镜板 HTML + 整页截图,渲全片前先确认 |
  1074. ### 渲得有多慢:自己量一次,别信文档
  1075. 不同机器差 3–5 倍(CPU、内存、画面复杂度都影响),所以这里不写「约几分钟」:
  1076. ```bash
  1077. npm run bench # 两个页面 × 两档分辨率 × 两种并发 → bench/bench.md
  1078. node scripts/bench.js --frames=60 --html=assets/templates/explainer.html
  1079. ```
  1080. 表里给 `s/帧`(已把并发算进去)和「10s@60fps 预估」。**并发不是越大越好**:
  1081. 超过 CPU 核数之后页面之间抢 CPU,`s/帧` 不降反升,表上能直接看出来。
  1082. ## 设计品味另找专业分工
  1083. 本技能只负责「环境 + 出片链路 + 质量门」。分镜方法、镜头语言、视觉风格属于设计范畴,
  1084. 交给专门的设计类技能处理,别在这里重复造。
README.md · README · 1,067 lines
  1. # html-to-video · 用代码逐帧做视频
  2. [English](README.en.md) · **中文**
  3. [![CI](https://github.com/wx4766/html-to-video/actions/workflows/ci.yml/badge.svg)](https://github.com/wx4766/html-to-video/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
  6. [![10 秒演示:HTML in,MP4 out —— 这段片子本身就是一份 HTML 文件渲出来的](docs/demo-hero.gif)](docs/demo-hero.mp4)
  7. <sub>这段片子就是 [`docs/demo-hero.html`](docs/demo-hero.html)(447 行、零依赖)渲出来的。自己复现一遍:<br>
  8. `node scripts/render-video-seek.js docs/demo-hero.html --duration=10 --fps=60`</sub>
  9. 把 HTML / Canvas 动画**逐帧渲染成 MP4**(可配乐、可出 GIF)。
  10. 不是 AI 文生视频,而是:
  11. ```
  12. 写 HTML/Canvas,把画面写成 frame(t) 纯函数
  13. → 无头浏览器逐帧 seek 到时刻 t,截图
  14. → ffmpeg 编成 H.264 MP4
  15. ```
  16. 字幕、运镜、转场全在代码里,**改一行代码重渲即可**。
  17. ## 为什么用它
  18. | | |
  19. |---|---|
  20. | **确定性** | 同样的输入永远得到同样的输出,可复现、可版本管理 |
  21. | **可控到帧** | 任意帧率(真 60fps,不是插帧),任意时刻精确对齐 |
  22. | **文字完美** | 中文字体渲染正常,不会像文生视频那样糊成一团或错别字 |
  23. | **零费用** | 本地跑,不调任何 API |
  24. | **四道质量门** | 文案 `check` / 页面 `qa` / 成片 `qc` / 声音 `master` —— 四类问题分别量化,不靠眼睛 |
  25. | **一句话一条镜头** | 12 个命名运动 + 5 种缓动,`dolly in, 6s, slow` 直接喂进去,自带防露边 |
  26. | **开箱即用** | 14 个模板改个配置块就出片,不用从零学 canvas |
  27. | **横竖屏都行** | 模板跟视口自适应,16:9 / 9:16 换 `--width/--height` 即可,不裁切 |
  28. | **能出「一支片子」** | 多镜头 + 8 种转场 + 镜头运动,一个 HTML 出整支,不用渲几段再拼 |
  29. | **自带素材** | 40+ 图标 / 参数化人物 / 卡片箭头 / 背景纹理,纯代码零依赖零版权风险 |
  30. | **能叠能配** | `--alpha` 出透明层叠到实拍上;`--srt` 挂外部字幕时间轴 |
  31. | **渲一次发一堆** | `--gif` / `--poster` / `--batch` 一次渲染出成片、动图、封面、批量任务 |
  32. 适合:讲解动画、动态图解、产品演示、数据可视化动画、游戏宣传片。
  33. 不适合:实拍感 / 氛围镜头(那个应该走 VideoGen)。
  34. ### 和 Remotion / Motion Canvas 什么关系
  35. 同类工具里最常被拿来比的三个,说清楚各自适合什么,省得你上手才发现选错:
  36. | | html-to-video | Remotion | Motion Canvas |
  37. |---|---|---|---|
  38. | 心智模型 | 一个 HTML 文件 + `frame(t)` 纯函数 | React 组件 + `useCurrentFrame()` | TS 生成器 + 场景图 |
  39. | 起步成本 | 复制模板、改顶部 `CFG` | 建 React 工程、学组件与 API | 装编辑器、学场景 API |
  40. | 构建步骤 | 无,浏览器直接跑 | 要打包 | 要构建 |
  41. | 工程化 | 测试 / CI / 六维 QA | 成熟生态、Lambda 云端渲染、播放器组件 | 编辑器体验好,适合手工精修 |
  42. | 许可 | MIT | 个人与 ≤3 人团队免费,4 人以上需商业许可 | MIT |
  43. **一句话选择**:要在 React 应用里内嵌视频编辑器、或大规模云端渲染 → Remotion 更合适;
  44. 要手工一帧帧精修分镜 → Motion Canvas 更合适;
  45. **只想把一屏现成的 HTML 变成 mp4,不想为此建个工程 → 用这个**。
  46. 尤其是「AI 写出来的 HTML 动画想变成视频」这种场景:不需要它懂框架,
  47. 输出一个能跑的 HTML 就够了,剩下交给渲染器。
  48. ### 交给 AI / 脚本跑:最舒服的一条路
  49. 这个工具的三条性质凑在一起,正好是「无人值守出片」需要的:
  50. | 性质 | 带来的好处 |
  51. |---|---|
  52. | **镜头表是 JSON** | 让模型产出 `[{kind,dur,title}, ...]` 比让它写 500 行 canvas 代码可靠得多 —— 改片子就是改 JSON |
  53. | **同输入同输出** | 改一句文案重渲,其它帧**逐像素不变**,可以做自动回归,不用担心「顺手改坏了别处」 |
  54. | **四道质量门** | `check` 管文案、`qa` 管页面、`qc` 管成片、`master` 管声音,全部输出数字与 JSON,脚本能自己判断渲坏了没有 |
  55. 于是闭环是:LLM 写 JSON/HTML → 渲 → QA 自己判红绿 → 红了就照着报告改 → 再渲。
  56. 人只在最后看一眼成片。
  57. ## 16 个开箱即用模板
  58. 拷贝一个,改顶部 `CFG` 里的文案和数据,直接出片。
  59. | | 模板 | 用途 |
  60. |---|---|---|
  61. | [![](docs/demo-explainer.gif)](docs/demo-explainer.mp4) | `assets/templates/explainer.html` | **多镜头讲解片**:片头 → 人物+气泡 → 分条要点 → 条形对比 → 片尾,镜头带转场,可喂 JSON 镜头表;横屏三条要点自动并排成三栏,竖屏另有上下版式 |
  62. | [![](docs/demo-title-card.gif)](docs/demo-title-card.mp4) | `assets/templates/title-card.html` | **片头标题卡**:主标题逐字弹入 + 副标题 + 标签 |
  63. | [![](docs/demo-bar-chart.gif)](docs/demo-bar-chart.mp4) | `assets/templates/bar-chart.html` | **条形图 / 排名**:条形依次生长,数值同步滚动,第一条高亮 |
  64. | [![](docs/demo-line-chart.gif)](docs/demo-line-chart.mp4) | `assets/templates/line-chart.html` | **折线趋势**:折线生长 + 数据点亮起 + 末点数值浮标 |
  65. | [![](docs/demo-number-counter.gif)](docs/demo-number-counter.mp4) | `assets/templates/number-counter.html` | **大数字 / KPI**:从 0 滚到目标值 + 涨跌标签 + 进度条 |
  66. | [![](docs/demo-timeline.gif)](docs/demo-timeline.mp4) | `assets/templates/timeline.html` | **时间线 / 流程**:中轴生长,节点逐个点亮 |
  67. | [![](docs/demo-compare.gif)](docs/demo-compare.mp4) | `assets/templates/compare.html` | **前后对比**:左右两栏对照,底部结论条收口 |
  68. | [![](docs/demo-flow-steps.gif)](docs/demo-flow-steps.mp4) | `assets/templates/flow-steps.html` | **流程图动画**:步骤依次点亮,当前步高亮外扩 |
  69. | [![](docs/demo-subtitle-card.gif)](docs/demo-subtitle-card.mp4) | `assets/templates/subtitle-card.html` | **逐句解说卡**:一句话一句地出 + 分段进度条,可挂 SRT |
  70. | [<img src="docs/demo-vertical-card.gif" width="150" alt="竖屏卡">](docs/demo-vertical-card.mp4) | `assets/templates/vertical-card.html` | **竖屏 9:16 卡**:大字标题 + 大数字,抖音 / 视频号 / Reels 用 |
  71. | [<img src="docs/demo-vertical-subtitle.gif" width="150" alt="竖屏字幕卡">](docs/demo-vertical-subtitle.mp4) | `assets/templates/vertical-subtitle.html` | **竖屏字幕卡**:`**关键词**` 自动高亮,原生 9:16 版式 |
  72. | [<img src="docs/img/preview-quote-card.jpg" width="150" alt="引言卡">](docs/img/preview-quote-card.jpg) | `assets/templates/quote-card.html` | **引言卡 / 金句**:大引号压底 + 引文逐行推进 + 出处短线,访谈 / 书摘 / 播客切片用 |
  73. | [<img src="docs/img/preview-chapter-card.jpg" width="150" alt="章节卡">](docs/img/preview-chapter-card.jpg) | `assets/templates/chapter-card.html` | **章节卡 / 过渡页**:序号水印 + 标题 + 章节进度点,把长片切成几段 |
  74. | [<img src="docs/img/preview-ui-showcase.jpg" width="150" alt="界面演示">](docs/img/preview-ui-showcase.jpg) | `assets/templates/ui-showcase.html` | **界面演示**:窗口推入 + 缓推 + 两块聚光标注,产品发布 / 功能更新用;也可换成真实截图 |
  75. | [<img src="docs/preview-program-dusk.png" width="150" alt="程序化电影">](docs/preview-program-night.png) | `assets/templates/program-film.html` | **程序化电影**:一条街从黄昏到深夜,3D 盒子楼 + 7.8 万点灯海 + 镜头穿越 + 色温从 2200K 走到 9500K。v2.0 三层能力的最小完整例子 |
  76. | [<img src="docs/preview-solid-dusk.png" width="150" alt="实体渲染">](docs/preview-solid-beam.png) | `assets/templates/lighthouse.html` | **实体渲染 / 场景片**:礁石、海、灯塔全是带法线的实体面,逐面着色。41 秒 7 镜,岩层 / 盐渍 / 苔按高度取色,光束扫出二十四海里。v2.1 的能力样本 |
  77. > 动图只为让你看见「它在动」;**点动图打开原片**看真实画质(横屏 1080p,竖屏 1080×1920)。
  78. > 静帧大图在 `docs/preview-*.png`。
  79. ```bash
  80. cp assets/templates/bar-chart.html my-video.html
  81. # 改 my-video.html 顶部的 CFG:title / data / note
  82. bash assets/render.sh my-video.html --duration=6 --fps=60
  83. ```
  84. ### 横屏 / 竖屏:换两个参数就行
  85. 模板都按视口设画布,**不用改代码**:
  86. ```bash
  87. bash assets/render.sh title-card.html --duration=6 --fps=60 # 1920×1080
  88. bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1080 --height=1920 # 9:16
  89. bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1280 --height=720 # 720p
  90. ```
  91. 模板内部用三档缩放落版:`SX = W/1920`(横向)、`SY = H/1080`(纵向)、
  92. `SF = √(SX·SY)`(字号 / 线宽)。1920×1080 下三者都是 1,所以默认输出保持不变;
  93. 换竖屏时字号不缩、版式铺开。自己写的动画照这三行来,就不会出现「改了 --width 只截到左上角」。
  94. > 渲染器现在会主动量画布尺寸,比视口小会明确告警,不再静默出半张图。
  95. ### 一稿多发:一条命令出全套平台比例
  96. 同一条片子要发抖音、小红书、B 站,剪辑软件里得一个比例一个序列、导一次盯一次。
  97. 这里版式本来就是参数化的,多渲一遍只是多一次循环:
  98. ```bash
  99. bash assets/render.sh bar-chart.html --duration=8 \
  100. --presets=douyin,xiaohongshu,square --out=dist/chart.mp4
  101. ```
  102. ```text
  103. dist/chart-douyin.mp4 1080×1920 抖音 / 快手 / 视频号
  104. dist/chart-xiaohongshu.mp4 1080×1440 小红书 3:4
  105. dist/chart-square.mp4 1080×1080 方版 1:1
  106. ```
  107. | 预设 | 尺寸 | 给谁用 |
  108. |---|---|---|
  109. | `douyin` / `tiktok` / `vertical` | 1080×1920 | 抖音、快手、视频号、Reels、Shorts |
  110. | `xiaohongshu` / `xhs` | 1080×1440 | 小红书 3:4 |
  111. | `instagram` / `ig` | 1080×1350 | IG 信息流 4:5 |
  112. | `square` | 1080×1080 | 方版 1:1 |
  113. | `bilibili` / `youtube` / `landscape` | 1920×1080 | 横屏 16:9 |
  114. 只想要一个尺寸用 `--preset=xiaohongshu`。**预设名拼错直接报错并列出可用名字**,
  115. 不会悄悄按 1920×1080 渲一版比例错误的片子。
  116. 一句实话:`--presets` 只保证**尺寸**对,不保证**构图**好看。9:16 和 16:9 的信息密度不同,
  117. 同一条内容在 3:4 上可能偏挤 —— 出来自己看一眼,该调字号就调。
  118. 另外,竖屏底部那块留白**是故意的**:平台进度条和按钮压在那儿,模板给烧录字幕留了 15% 安全区。
  119. ### 配音:没给时长,就按音频长度出片
  120. 真实工作流是「写文案 → 配音 → 配画面」,不是先定 6 秒再想办法把配音塞进去:
  121. ```bash
  122. bash assets/render.sh title-card.html --audio=voice.m4a --story=shots.json
  123. # ▸ audio: 音频 12.48s,未指定 --duration → 视频按音频定长(12.5s,向上取整到整帧)
  124. ```
  125. - **向上取整到整帧**:少半帧就会把最后一个字的尾音削掉。
  126. - 显式给了 `--duration` 且和音频差超过 0.35s 会明确告警 —— 说清差多少、伤在哪边。
  127. 旧版本这里会静默出一支短片:画面后半段整段消失,日志却只有一句 `✓ Done`。
  128. - `--audio-fit=pad`:音频比视频短时补静音,保住整段画面(默认 `trim` 按音轨收尾)。
  129. 一个必须说清的边界:`trim` 下成片**不会精确等于音频秒数**。视频流是 `-c:v copy`
  130. 直接复制的,ffmpeg 只能按帧包边界收尾,实测会多留 0.3–0.5s。毫秒级对齐得重编码,
  131. 那是拿画质换精度,不值得。
  132. ### 卡点:让切点落在拍上
  133. 所有"看着专业"的片子都遵守同一条潜规则:**切点落在拍上**。
  134. 手工对齐是数着秒表挪关键帧,改一句文案又得重来。把拍点算出来交给程序,
  135. "卡点"就从手感变成了参数:
  136. ```bash
  137. bash assets/render.sh style-film.html --audio=bgm.mp3 --beats --snap=beats
  138. # ▸ 节拍: 120.14 BPM · 20 个拍点 · 首拍 0.49s · 置信度 0.85
  139. # ▸ 时长对齐拍点: 25.2s → 25.5s(+0.3s)
  140. ```
  141. - `--beats` 直接分析 `--audio` 那条音轨;`--beats=beats.json` 用预先算好的网格
  142. (同一个 BGM 出多条片子时别反复分析)。
  143. - `--snap=beats` 把总时长吸到下一个拍点 —— 成片不会"差 0.2 秒收在半个拍上"。
  144. - `--snap-shots` 把**每个镜头**的时长量化到整拍,这才是"切点真的落在拍上"。
  145. 改动会逐条打印(`3.60s → 3.50s`),幅度超过 25% 会警告 —— 节奏变了得让你知道。
  146. - 模板里也能吃到拍点:`window.__beats` 有 `bpm / beats / downbeats / offset`,
  147. 风格库提供 `SV.pulse(t)`(拍点处为 1、之后衰减)和 `SV.beatPhase(t)`。
  148. 分析器是零依赖的(`scripts/beats.js`):ffmpeg 解成 22.05kHz 单声道 →
  149. 对数能量通量 → 自相关估周期 → 扫相位。实测 120BPM 鼓点误差 < 2BPM、相位误差 ~9ms;
  150. 纯人声测不出稳定 BPM 时会明确报警(旁白本来就该按句子切,不该按拍切)。
  151. ```bash
  152. node scripts/beats.js bgm.mp3 --out=beats.json # 单独跑,看 BPM 与置信度
  153. ```
  154. ### 镜头:一行字一条镜头
  155. 切点解决了"什么时候换",镜头解决"换的时候画面怎么动"。
  156. 分镜表里写的是「推镜,6 秒,缓入缓出」,不是 `from:[0,0,1] → to:[0.02,0,1.06]` ——
  157. 现在可以直接把那句话喂给渲染器:
  158. ```bash
  159. bash assets/render.sh style-film.html --camera='dolly in, 6s, slow ease-in-out'
  160. bash assets/render.sh style-film.html --camera=auto # 按镜头类型自动配
  161. bash assets/render.sh style-film.html --camera=off # 关掉,做 A/B 对比
  162. ```
  163. ```js
  164. // 模板里就两行
  165. const cam = CAM.move(CFG.camera, t, DUR); // ← 解析这句话
  166. CAM.begin(g, cam, W, H); drawScene(t); CAM.end(g);
  167. ```
  168. **12 个运动**,每个对应一种"观众该感觉到什么":
  169. | 运动 | 感觉 | 运动 | 感觉 |
  170. |---|---|---|---|
  171. | `dolly in` 推镜 | 亲近、紧张、"这件事重要" | `handheld` 手持 | 在场、紧迫、纪实 |
  172. | `dolly out` 拉镜 | 孤立、释放、交代环境 | `dolly zoom` 变焦推拉 | 醒悟、不安(一片只用一次) |
  173. | `pan` 横摇 | 扫视、跟随、把两件事连起来 | `rack focus` 拉焦 | 注意力从一处移到另一处 |
  174. | `tilt` 纵摇 | 仰视=敬畏,俯视=发现与重量 | `whip pan` 甩镜 | 能量、跳切、喜剧 |
  175. | `orbit` 环绕 | 审视、强调、英雄感 | `push to` 推近细节 | "看这里":线索、一个表情 |
  176. | `crane` 升降 | 希望、尺度、从上方揭示 | `static` 固定 | 让主体或光自己动 |
  177. 三个不用操心的细节:
  178. - **不会露黑边**。所有运动都保证 `scale ≥ 1`,位移按放大余量裁到 `(scale-1)/2` ——
  179. 想推 8% 就最多横移 4%,写超了会被夹住。200+ 个时刻在测试里逐个验证过。
  180. - **不会抖得不一样**。手持用正弦叠加 + 固定种子,不是 `Math.random()`;
  181. `move()` 是 `t` 的纯函数,并行渲染的帧完全一致。
  182. - **换分辨率不用改数值**。`tx/ty` 是比例(`0.02` = 画宽 2%),不是像素。
  183. `npx html-to-video camera` 一次列全 12 个运动和写法;`--camera=auto` 的导演逻辑在
  184. `assets/style-film.html` 的 `AUTO_CAM` 表里,可以按片子改。
  185. ### 成片质检:`h2v qc`
  186. `qa.sh` 查页面,`qc` 查**已经编好的 mp4** —— 编码参数、音轨、真实播放时的冻结与黑场,
  187. 只有解码之后才看得见:
  188. ```bash
  189. node scripts/qc.js out/film.mp4
  190. ```
  191. ```
  192. qc · film.mp4
  193. info 1920×1080 · 30fps · 20.5s · h264 · aac 48k
  194. hook 0.482 ✓(前 2 秒在动)
  195. black none ✓ freeze none ✓ dup 0 ✓
  196. bright 34–212 ✓
  197. cuts 6(1.0 / 4.0 / 7.0 / 10.5 / 14.0 / 17.5)
  198. loud −17.8 LUFS · 真峰值 −3.2 dBTP ⚠ 偏轻,跑 h2v master
  199. sheet → qc/film.sheet.png
  200. ```
  201. | 检查 | 判据 |
  202. |---|---|
  203. | `hook` | 前 2 秒相邻帧平均灰度差 ≥ 0.35(**硬规则,不过就 exit 1**) |
  204. | `black` / `freeze` | `blackdetect` 无 ≥0.3s 黑段 / `freezedetect` 无 ≥1s 定格 |
  205. | `dup` | 相邻帧完全相同的对数(抓"整段复制") |
  206. | `bright` | 平均亮度在 16–240(全黑全白通常是主题配错) |
  207. | `cuts` | 场景切换点数量与位置(对不上镜头表 = `--story` 没生效) |
  208. | `sheet` | 抽 9 帧拼一张联系表,一眼扫完整片 |
  209. hook 门槛有实测基线,不是拍脑袋:纯色静止 0.00 / 极简标题卡 0.36–0.42 /
  210. 加胶片颗粒 0.71 / 正常运动片 0.85–1.2。实拍或强运动片用 `--hook-min=0.5`。
  211. ### 响度母版:`h2v master`
  212. 手机外放听着小、笔记本上听着大 —— 不是错觉,是没做响度归一,平台间能差 6–8 LU。
  213. 目标是 **−14 LUFS / −2 dBTP**:
  214. ```bash
  215. node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4
  216. # ▸ −17.77 LUFS → −13.90 LUFS(type=linear)· 真峰值 −1.8 dBTP
  217. ```
  218. 两遍 `loudnorm`:pass 1 只测量,pass 2 用测得值 `linear=true` 做固定增益。
  219. 一遍式是动态模式(边跑边压),会改变动态、抽气。三个坑已经在代码里填了:
  220. - **LRA 超目标时 `loudnorm` 会静默切回动态模式** —— 报告里 `type` 不是 `linear` 就明确告警。
  221. - **限幅后必须重新测量**,否则 pass 2 用限幅前的峰值算错增益。
  222. - **AAC 编码会把真峰值抬 0.5–0.7 dB**,所以带视频时目标压到 −2 dBTP。
  223. ### 文案自检:`h2v check`
  224. ```bash
  225. node scripts/script-check.js story.json
  226. ```
  227. ```
  228. 6 镜 / 20.5s / 193 字 / 9.4 字每秒
  229. ✗ 要改的:
  230. · 第 1 镜(hook)的 sub 有 17 个汉字 > 14:「渲染器自己量拍子,镜头时长量化到整拍」
  231. ```
  232. 查机器能查的:单行上限(横屏 14 字 / 竖屏 12 字)、每镜条目数(≤4)、
  233. 阅读速度(≤12 字/秒)、陈词滥调命中、有没有转折镜头。
  234. 机器查不了的(读出声打结、该砍的 30%)写在 `references/writing.md` 里 —— 那是规则,不是灵感。
  235. ### 给 Agent 用:`--json`
  236. 人读 `✓ Done: xxx.mp4 (1.2 MB · 30fps · 12s)` 没问题,Agent 只能拿正则去猜,
  237. 路径里带空格、中文、括号就崩。加 `--json`,stdout 只留一行结果:
  238. ```bash
  239. bash assets/render.sh title-card.html --duration=6 --json
  240. ```
  241. ```json
  242. {"ok":true,"exitCode":0,"output":"…/title-card.mp4","width":1920,"height":1080,
  243. "fps":60,"duration":6,"frames":360,"bytes":2411724,"warnings":[],"mode":"video"}
  244. ```
  245. - 进度与人读日志全部走 stderr,直接 `JSON.parse(stdout)` 即可。
  246. - `warnings` 是数组:参数冲突、音画长度不符、主题名不认识都进这里;空数组 = 干净。
  247. - `duration` 是成片**实际**时长(ffmpeg 读回来的),不是计划值。
  248. - `--presets` 时 `output` 变数组,另附 `presets: [{name,width,height,output,ok,bytes}]`。
  249. ### 换配色:改一个字段,或者一条命令
  250. **11 个模板全部接入** `assets/templates/themes.js`。两种换法,效果一样:
  251. ```bash
  252. # ① 命令行(推荐):不改文件,一次渲一个主题
  253. bash assets/render.sh bar-chart.html --duration=6 --theme=paper --out=bar-paper.mp4
  254. ```
  255. ```js
  256. // ② 写进模板:CFG.theme 一行
  257. const CFG = {
  258. theme: 'paper', // midnight(默认,暗色)| paper(浅色)| neon(黑紫霓虹)
  259. ...
  260. };
  261. ```
  262. 命令行优先于 `CFG.theme`。名字打错会明确告警并告诉你有哪些可选,不会静默变成默认色。
  263. 因为主题是注入的,`--batch` 里每个任务可以各用一套配色 —— 同一份片子出「暗色版 + 浅色版」不用复制文件:
  264. ```json
  265. [{ "html": "bar-chart.html", "duration": 6, "theme": "midnight", "out": "bar-dark.mp4" },
  266. { "html": "bar-chart.html", "duration": 6, "theme": "paper", "out": "bar-light.mp4" }]
  267. ```
  268. 上面每条命令都带 `--out`,不是可选项:成片默认叫 `<HTML 名>.mp4`,
  269. 同一个 HTML 渲两套配色不换名字,后一个会盖掉前一个。
  270. 也可以传对象只覆盖要改的字段:`theme: { bg: '#0B1020', accent: '#22D3EE' }`。
  271. 拷模板时记得把 `themes.js` 一起拷到同目录。只拷 HTML 时画面照常出来(模板里有兜底色板),
  272. 但 `themes.js` 会 404,而渲染器把「页面报错」判为失败 —— 这时补上文件或加 `--allow-errors`。
  273. ### 多镜头与转场:一份 HTML 出整支片子
  274. 一支能看的片子是「多镜头 + 转场」,不是几段动画硬拼。用 `assets/lib/scenes.js`
  275. 在**同一个 HTML** 里写镜头表,渲染器照旧按 `t` 推帧,转场在页面内合成 ——
  276. 不用渲几段再拿 ffmpeg 拼,也不用开剪辑软件:
  277. ```bash
  278. bash assets/render.sh explainer.html --duration=17.6 --fps=30 --gif --poster=6.0
  279. ```
  280. 镜头表也可以整份外置(`--story=shots.json`),**LLM 写 JSON 比写几百行 canvas 代码可靠得多**:
  281. ```bash
  282. bash assets/render.sh explainer.html --duration=17.6 --fps=30 --story=shots.json
  283. ```
  284. ```json
  285. [{ "kind": "title", "id": "hook", "dur": 3.0, "title": "为什么你的构建这么慢" },
  286. { "kind": "talk", "id": "why", "dur": 3.5, "say": "先别急着换工具",
  287. "who": "dev", "pose": "wave", "trans": { "in": "fade", "dur": 0.45 } }]
  288. ```
  289. | 转场 | 观感 | 什么时候用 |
  290. |---|---|---|
  291. | `fade` | 交叉溶解 | **文字类片子的默认** |
  292. | `dip` | 经底色过渡 | 两段情绪差得远,或两镜版式完全换掉 |
  293. | `slide` | 下一镜整块推入 | 满幅图形 / 照片 / 色块之间 |
  294. | `push` | 两镜贴着一起走 | 同上,更要方向感 |
  295. | `rise` | 下一镜从下方升起 | 竖屏、解说卡 |
  296. | `zoom` | 变焦穿过 | 满幅画面之间,「一口气穿过去」 |
  297. | `wipe` | 竖边扫擦 + 扫描亮线 | 科技感、数据揭示(满幅图形) |
  298. | `cut` | 硬切 | 节奏紧,或转场时长给 0 |
  299. > **选型铁律:画面里有文字,就只用 `fade` / `dip`。**
  300. > 带位移的转场会把上一镜的文字从中间切一半推走,两镜标题还会在同一位置叠成乱码 ——
  301. > 观感是「画面坏了」,不是「镜头动了」。位移类转场只留给边缘没有语义的画面。
  302. > `explainer.html` 的 `draw` 包装里有配套的两条纪律(退场先撤内容、进场晚 0.22×转场时长起步),
  303. > 自己写多镜头模板时照抄即可。
  304. 转场是**重叠**的:总时长 = Σ镜头时长 − Σ转场时长,加了转场片子不会变长。
  305. `--scene-log=shots.csv` 能导出镜头时间轴(含每镜起止与转场),
  306. **镜头表总时长和 `--duration` 不一致会告警**,免得结尾静默多一截静止画面。
  307. ### 自带素材:图标 / 人物 / 运镜
  308. 想画图标、箭头、卡片、人物,不用找图也不用从零写 path —— `assets/lib/` 三个零依赖库:
  309. ```js
  310. SH.icon(g, 'bolt', x, y, 48, { color: TH.accent, width: 2.5 }); // 40+ 线性图标
  311. SH.card(g, { x, y, w, h }, { fill: TH.panel, radius: 18 }); // 卡片 / 箭头 / 连接线 / 纹理
  312. FIG.draw(g, FIG.preset('dev', { x, y, h, t, pose: 'wave' })); // 参数化小人 + 对话气泡
  313. CAM.withCam(g, CAM.at(CAM.breath(), t, W, H), W, H, () => drawContent(g)); // 持续运镜,治「画面死了」
  314. ```
  315. | 库 | 提供 |
  316. |---|---|
  317. | `shapes.js` | 40+ 图标、卡片 / 胶囊 / 箭头 / 正交连接线 / 虚线框 / 进度弧、网格 / 点阵 / 柔光 / 暗角 / 流动极光 / 胶片颗粒 |
  318. | `figures.js` | 参数化扁平小人:发型 6 种 / 表情 6 种 / 姿势 6 种 / 配色任意,4 个开箱预设,自带 `FIG.say()` 气泡 |
  319. | `camera.js` | `breath` 呼吸、`kenburns` 推拉、`handheld` 确定性手持微抖、`shake` 衰减震动 |
  320. **为什么是代码画的元件而不是预置图片素材包**:版权干净(没有一张外部图)、风格必然统一、
  321. 任意分辨率清晰、不占体积。**刻意不做**卡通人物位图包 / 标志性建筑照片包 ——
  322. 版权说不清、风格和用户自己的画面打架,还会把仓库撑成几十 MB 的二进制库。
  323. ### 透明输出:叠到别人拍的画面上
  324. AI 生成的背景 + 代码生成的文字层,是现在最省钱的组合(模型画文字必糊,代码画文字精确到像素)。
  325. ```bash
  326. node scripts/render-video-seek.js animation.html --duration=6 --fps=30 --alpha
  327. # → animation.mov(ProRes 4444 / yuva444p10le,背景透明)
  328. ```
  329. 模板侧只要两行:读到 `window.__transparent` 为真时**把底色连同全屏光斑一起跳过**
  330. (只跳底色、留着光斑时四角 alpha=12 而不是 0,叠到实拍上整片泛白):
  331. ```js
  332. const TRANSPARENT = !!window.__transparent;
  333. if (!TRANSPARENT) { /* 底色 / 全屏渐变 / 光斑 / 光扫 */ }
  334. ```
  335. 体积代价(960×540 / 2s):H.264 约 118 KB,ProRes 4444 约 760 KB。
  336. **只有 ProRes,没有 VP9 alpha** —— 实测 `yuva420p` 能把 alpha 写进文件(7.8 KB → 16.8 KB),
  337. 但 Chromium 播出来整帧 alpha 全 0,既然没法自证正确就不作为选项发布。
  338. ### 字幕:挂外部时间轴,配音改了字幕跟着走
  339. ```bash
  340. node scripts/render-video-seek.js subtitle-card.html --duration=8 --srt=voice.srt --cue-log=cues.csv
  341. ```
  342. 支持 SRT / WebVTT / JSON。渲染器解析一次、注入 `window.__cues`,模板按当前 `t` 自己查句;
  343. 模板里 `--srt` 优先、没有就用自带的 `CFG.lines`。`--cue-log` 输出
  344. `frame,t,cue_index,cue_start,cue_end` CSV —— 每句首帧时间减 SRT 起点就是误差,
  345. 实测 4 句 / 80 帧,误差 0 ms。
  346. > 底部 15% 是各平台进度条 / 按钮区,字幕踩进去等于白写;`qa.js` 会提示「进字幕带」。
  347. ## 一个世界,一条镜头轨迹(v2.0)
  348. 1.x 的模板都是「一镜一画」:每镜画到自己的离屏画布再合成。干净,但做不了三件事——
  349. **镜头推过去看某个东西**(下一镜是全新画布,那东西已经不在了)、**镜头穿过一条街**、
  350. **光随时间变**(只能叠半透明黑,那是滤镜不是光)。
  351. 2.0 加了三层。三个库互相独立,可以只用其中一个:
  352. | 库 | 解决什么 | 关键能力 |
  353. |---|---|---|
  354. | `assets/lib/space.js` | 镜头在连续空间里移动 | 透视投影 / 深度排序 / 距离雾 / look-at 相机 / 关键帧轨迹 / 环形·网格·螺旋布局 |
  355. | `assets/lib/brush.js` | 「量」——十万笔的质感 | 按「颜色 × 粗细」分桶批量提交(`stroke` 从 10 万次降到十几个)/ 形态插值 / 文字轮廓吸附 / 方向场 |
  356. | `assets/lib/light.js` | 光随时间变 | 黑体色温(1900K→9500K)/ 昼夜关键帧 / 径向光·光束 / 调色·曝光·暗角·泛光 |
  357. ```bash
  358. node scripts/render-video-seek.js assets/templates/program-film.html --duration=20
  359. ```
  360. 出的是**一条街从黄昏到深夜的 20 秒**:两排 3D 盒子楼(真实 3D 顶点投影,正面背光、侧面受光)、
  361. 7.8 万点城市灯海分三层亮起、6 盏路灯与地面光斑、一条推进的镜头轨迹、色温 2200K → 9500K。
  362. **为什么是 2.0 而不是 1.10**:它换的是渲染结构(逐镜离屏 → 一个世界),不是加功能。
  363. | 实测 | 数字 |
  364. |---|---|
  365. | 12 万笔生成 | 61 ms |
  366. | 12 万笔形态插值 | 22 ms |
  367. | 10 万笔吸附到文字 | 310 ms |
  368. | 20s 成片(1920×1080 / 30fps) | 600 帧,`h2v qc` 全绿 |
  369. | 能做 | 做不了 |
  370. |---|---|
  371. | 镜头在空间里推、摇、穿行 | 阴影贴图 / PBR(没有 z-buffer,只有画家算法) |
  372. | 十万级笔触的质感 | 逐像素 shader(流体、火焰、玻璃折射) |
  373. | 光随时间变(黄昏→夜→晨) | 百万级粒子每帧现算(要那个量级得预渲染) |
  374. | 视角连续变换(平面→3D 通道) | 真实材质反射(用光照 + 笔触去「暗示」) |
  375. 需要真 3D 时直接上 `three.js` —— 渲染器只认 canvas,不关心你怎么画;`--alpha` 可以把 WebGL 图层叠到实拍上。
  376. ## 东西是真的:实体、着色、气氛(v2.1)
  377. 2.0 解决了「空间连续」,但空间里的东西还是**平面片**。平面片没有法线 ——
  378. 不能着色、不能转身、做不出曲面。镜头在动,画面还是平的。
  379. 2.1 补的是「面」:
  380. | 库 | 解决什么 | 关键能力 |
  381. |---|---|---|
  382. | `assets/lib/solid.js` | 东西是实体 | `box` / `lathe`(旋转体)/ `sphere` / `tube`(扫掠)/ `terrain`(高度场)+ Lambert·Blinn·边缘光·半球光·AO + 色调映射 + 逐面取色 + 表面粗糙度 |
  383. | `assets/lib/atmos.js` | 光在空气里走 | 多段天空 / 星空(按星等分布)/ 贴地雾 / 体积光束(54 条射线且相互重叠,不是几层梯形)/ 辉光 / 星芒 / 水面波纹 / 胶片颗粒 |
  384. | `assets/lib/lens.js` | 镜头有语言 | 球坐标轨道(绕主体转,不穿模)/ **对数**推拉 / 景别→距离 / 手持呼吸 / 切镜表 |
  385. | `scripts/foley.js` | 声音对得上画面 | 8 种程序化音色(海浪/风/雾笛/灯丝/纸/笔触/撞击/铃)+ 事件表 + Schroeder 混响 |
  386. ```bash
  387. h2v new my-world --template=lighthouse
  388. node scripts/foley.js --out=bed.wav --dur=41 --preset=lighthouse
  389. h2v render my-world.html --duration=41 --fps=30 --audio=bed.wav
  390. ```
  391. `lighthouse.html` 是 41 秒 / 7 镜的一条片:礁石与灯塔是建模的(岩层取色、盐渍、
  392. 苔、塔身污渍逐面算),镜头从 1500 推到 90(16 倍,对数),再拉到 3100(31 倍);
  393. 光从黄昏 3000K 推到深夜 6800K;灯在 13.6 秒点亮 —— 音轨里的嗡鸣也在 13.6 秒淡入。
  394. **为什么「着色」是分水岭**:同一组颜色,有没有法线,是「贴纸」和「石头」的区别。
  395. 一帧画面里,暗面偏冷、亮面偏暖、边缘有一道亮线 —— 这三件事占了立体感来源的绝大部分,
  396. 而它们全都需要面法线。
  397. | 实测 | 数字 |
  398. |---|---|
  399. | 17,000 面 / 1080p 单帧 | 20–45 ms(含大气与后期) |
  400. | 41s 成片 | 1230 帧,1920×1080 / 30fps |
  401. | 音效床合成 | 41s 立体声,1.5 s |
  402. ## 14 种风格:同样的内容,换个样子
  403. 模板解决「这段内容怎么排」,风格解决「这支片长什么样」。两者分开之后,
  404. 14 个版式 × 14 种视觉语言 = 196 种观感,而不用写 196 个模板。
  405. ```bash
  406. bash assets/render.sh assets/style-film.html --duration=13 --theme=chalk # 黑板粉笔
  407. bash assets/render.sh assets/style-film.html --duration=13 --theme=水墨 --width=1080 --height=1920
  408. ```
  409. | 风格 | 一句话 | 适合 |
  410. |---|---|---|
  411. | `riso` 孔版印刷 | 米白纸 + 荧光粉/蓝/绿三套网点(真实印刷网角)+ 标题套印错位 | 观点、数据、独立杂志感 |
  412. | `cutpaper` 剪纸拼贴 | 四边手撕的纸片 + 锐利硬投影 + 两层纸叠着 | 故事、人物、教育 |
  413. | `blueprint` 工程蓝图 | 深蓝 + 20/100px 双层格网 + 四角十字定位标记 + 等宽字 | 技术、架构、API |
  414. | `chalk` 黑板粉笔 | 墨绿板 + 双线抖动笔触 + 粉尘 + 楷体 | 教学、科普 |
  415. | `isometric` 等距线稿 | 白底 + 2:1 等距立体块(顶面/左面/右面)+ 白面遮挡 | 机制、结构、流程 |
  416. | `synthwave` 霓虹复古 | 条纹太阳 + 透视地面网格 + CRT 扫描线 + 色差 | 音乐、游戏、复古科技 |
  417. | `swiss` 瑞士网格 | 白底 + 超大字号 + 单一信号红 + 零圆角 | 品牌、观点、发布会 |
  418. | `ink` 水墨宣纸 | 宣纸纤维 + 三层洇墨 + 朱红印章色 + 大留白 | 国风、文化、历史 |
  419. | `watercolor` 水彩晕染 | 棉浆纸 + 湿画法色晕 + 颜料在边缘沉积的深圈 + 衬线标题 | 人文叙事、品牌故事、教育 |
  420. | `pencil` 铅笔素描 | 素描纸 + 45° 排线 + 双线手绘边框 + 石墨灰阶(几乎不用彩色) | 教程、拆解、草稿感 |
  421. | `vox` 半调解说 | 奶油底 + 大块饱和色 + 大号无衬线 + 半调网点 + 硬投影 | 知识解释、新闻拆解 |
  422. | `clay` 黏土立体 | 淡紫灰底 + 圆角厚块 + 上亮下暗渐变 + 内高光 + 落地投影 | 产品发布、SaaS、年轻品牌 |
  423. | `woodcut` 木刻版画 | 米黄纸 + 木纹 + 实墨块 + 断续白刻线(明暗=线密度)+ 朱红套色错位 | 观点、文化、有力量的海报片 |
  424. | `glass` 玻璃拟态 | 深色渐变 + 漂移光斑 + 磨砂玻璃面板(1px 亮边 / 内高光 / 透光 / 圆角发光条) | 科技发布、SaaS、硬件参数 |
  425. 14 种分五个家族,选的时候先定类:**印刷**(riso / woodcut)、**手作**(cutpaper / chalk /
  426. pencil / clay)、**绘画**(ink / watercolor)、**信息图**(blueprint / isometric / swiss / vox)、
  427. **数字界面**(synthwave / glass)。`npx html-to-video styles --cat=印刷` 只列一类。
  428. `--theme` 也吃中文名(`--theme=水墨` / `--theme=玻璃`)。**14 个模板已经全部接上** ——
  429. 换的不只是配色,背景整层会换成该风格的纸纹 / 网点 / 格网 / 透视地面:
  430. ```bash
  431. bash assets/render.sh assets/templates/bar-chart.html --theme=blueprint --duration=6
  432. bash assets/render.sh assets/templates/explainer.html --theme=riso --duration=18
  433. ```
  434. 每种风格的签名元素、禁忌、在代码里怎么调、哪个模板配哪种风格,见
  435. **[assets/STYLES.md](assets/STYLES.md)**。
  436. **先看效果,再决定**:
  437. ```bash
  438. # 十四宫格:第 k 秒一个风格,出 14 张全屏静帧
  439. node scripts/render-video-seek.js assets/style-gallery.html \
  440. --stills=0.5,1.5,2.5,3.5,4.5,5.5,6.5,7.5,8.5,9.5,10.5,11.5,12.5,13.5
  441. # 一支 13 秒的风格短片:片头 / 要点 / 数据 / 片尾
  442. bash assets/render.sh assets/style-film.html --duration=13 --fps=60
  443. ```
  444. **一支完整的多风格推广片**:`assets/examples/promo-zh.html` + `promo-zh.story.json`
  445. 是 12 镜 / 8 风格 / 85 秒的真实案例,镜头表由配音净时长反推,所以解说、字幕、
  446. 画面天然对轴,不用手工卡秒。它演示了两条很实用的做法:每个镜头单独指定
  447. `shot.style`(一镜一风格,蒙太奇一镜里还能连切四种),以及把字幕画在所有镜头
  448. 之上(转场时不闪、不随风格变色)。
  449. ```bash
  450. node scripts/storyboard.js assets/examples/promo-zh.html \
  451. --story=assets/examples/promo-zh.story.json --cols=3
  452. node scripts/render-video-seek.js assets/examples/promo-zh.html \
  453. --story=assets/examples/promo-zh.story.json --duration=85.34 --fps=30 \
  454. --audio=voice.wav --out=promo.mp4
  455. ```
  456. ## 先看分镜,再渲全片
  457. 60 秒 1080p 逐帧渲要 3~10 分钟。渲完才发现「第 4 镜字太小」,改一轮又是几分钟。
  458. 所以先出一页分镜板:
  459. ```bash
  460. node scripts/storyboard.js my.html --cols=3 --theme=riso
  461. ```
  462. ```
  463. my.storyboard/
  464. ├── shot-01.png … 每镜一张中点静帧(在转场窗口之外,画面稳定)
  465. ├── storyboard.html 带镜头名/时长/时间码/转场的一页板
  466. └── storyboard.png 整页截图,贴给别人问「这样行不行」
  467. ```
  468. 十几秒出,能看出:镜头时长分配、层级大小、有没有哪一镜是空的、风格跟内容搭不搭。
  469. 看不出动效手感与转场顺不顺 —— 那些要出片或 `--stills` 抽帧连看。
  470. ## 安装
  471. 需要 Node.js >= 18。
  472. **当普通 Node 工具用**(clone 到哪都行,三条命令):
  473. ```bash
  474. git clone https://github.com/wx4766/html-to-video.git
  475. cd html-to-video
  476. npm install
  477. npx playwright install chromium # 首次必做:下载截图用的浏览器内核
  478. ```
  479. 另外需要 **ffmpeg 在 PATH 上**(`brew install ffmpeg` / `apt install ffmpeg` / `winget install ffmpeg`)。
  480. 别用 Playwright 自带的那个:它是 `--disable-everything` 裁剪版,编不了 H.264。
  481. **当 WorkBuddy / Claude 技能用**(放进技能目录,AI 能直接调用):
  482. ```bash
  483. git clone https://github.com/wx4766/html-to-video.git ~/.workbuddy/skills/html-to-video
  484. cd ~/.workbuddy/skills/html-to-video
  485. bash scripts/install-deps.sh
  486. ```
  487. `install-deps.sh` 会自动做完三件事:
  488. 1. 探测本机 Playwright 浏览器缓存,挑**匹配的** playwright 版本
  489. 2. 装完整版 ffmpeg(同上,避开裁剪版)
  490. 3. 把工作区路径写进 `~/.workbuddy/.html2video-env`
  491. 想自己指定工作区:`bash scripts/install-deps.sh /path/to/workspace`
  492. ## 快速开始
  493. ```bash
  494. # 1. 拿骨架模板改自己的动画
  495. cp assets/animation-skeleton.html my-animation.html
  496. # 2. 冒烟:先截几帧确认画面(别跳过)
  497. bash assets/smoke.sh my-animation.html
  498. # 3. 只渲一小段,快速看效果(几秒出片)
  499. bash assets/render.sh my-animation.html --from=3 --to=5 --fps=30
  500. # 4. 全量渲染
  501. bash assets/render.sh my-animation.html --duration=12 --fps=60 --width=1920 --height=1080 --concurrency=4
  502. # → my-animation.mp4
  503. # 5. 交付前验收(确定性问题、卡顿、半截字、叠字、字幕带、字体回退,一次全查)
  504. bash assets/qa.sh my-animation.html --duration=12 --fps=30
  505. # 6. 成片再过一道(前 2 秒有没有动、黑场、冻结、响度)
  506. node scripts/qc.js my-animation.mp4
  507. ```
  508. 12 秒 60fps = 720 帧,实测约 6~7 分钟(concurrency=4)。
  509. ### 渲染参数
  510. | 参数 | 作用 |
  511. |---|---|
  512. | `--duration` / `--from` / `--to` | 时长 / 只渲某段(秒)。给了范围时输出 `名.起-止s.mp4`,不会覆盖成品 |
  513. | `--stills=0.5,2.0` | 只导出这些时刻的 PNG,不编码 |
  514. | `--fps` / `--width` / `--height` | 帧率与分辨率 |
  515. | `--preset=<名>` | 按平台预设定尺寸(`douyin` / `xiaohongshu` / `instagram` / `square` / `bilibili` …) |
  516. | `--presets=a,b,c` | 一条命令出全套比例,每个比例一个成片(自动加 `-比例名` 后缀) |
  517. | `--concurrency` | 并行 worker 数(每个 worker 一个 Chromium 页面);给 `auto` 按 CPU 与内存自己挑 |
  518. | `--audio=<file>` | 编码后自动混音;没给 `--duration` 时按音频长度出片 |
  519. | `--audio-fit=trim\|pad` | 音画长度不一致:`trim` 按音轨收尾(默认)/`pad` 补静音保住视频长度 |
  520. | `--beats` / `--beats=<json>` | 分析 `--audio` 的拍点(或用预计算文件),注入 `window.__beats` |
  521. | `--snap=beats` | 总时长吸到下一个拍点 |
  522. | `--snap-shots` | 镜头表里每个镜头的时长量化到整拍(真正让切点落在拍上) |
  523. | `--bpm=<数>` / `--offset=<秒>` | 跳过自动估计,手工给 BPM / 首拍(纯配音想硬卡点时用) |
  524. | `--gop=<秒>` | 关键帧间隔(`--gop=1` 便于后期按秒 seek) |
  525. | `--keep-frames` | 成功也保留逐帧 PNG(换 CRF 重编码不必重截) |
  526. | `--tmpdir=<目录>` | 逐帧 PNG 落到哪块盘(默认挨着 HTML)。1080p 一分钟约 2.4 GB,系统盘紧张时指到别的盘 |
  527. | `--resume` | 上次渲到一半断了?接着渲,已渲好的帧直接复用 |
  528. | `--alpha` | 透明背景输出(ProRes 4444 `.mov`),叠到实拍 / AI 生成画面上用 |
  529. | `--srt=<file>` / `--cues=<file>` | 外部字幕时间轴(SRT / VTT / JSON),注入 `window.__cues` |
  530. | `--cue-log=<file>` | 导出字幕对轴 CSV(`frame,t,cue_index,cue_start,cue_end`) |
  531. | `--story=<file>` | 镜头表 JSON,注入 `window.__story`,整份换掉剧本 |
  532. | `--scene-log=<file>` | 导出镜头时间轴 CSV;镜头表总时长与 `--duration` 不一致会告警 |
  533. | `--gif[=fps,宽]` | 出片后顺手产 GIF(默认 15fps / 宽 960),不重渲 |
  534. | `--poster=<秒>` | 出片后顺手抽一张封面静帧 `.jpg` |
  535. | `--batch=<file.json>` | 一串任务按顺序渲,最后打汇总表;单个失败不连坐已渲好的 |
  536. | `--theme=<名>` | 换主题(`midnight` / `paper` / `neon`),覆盖模板里的 `CFG.theme`;打错名字会告警并回退 |
  537. | `--camera=<行>` | 镜头:`'dolly in, 6s, slow'` / `auto`(按镜头类型) / `off`(关掉),覆盖 `CFG.camera` |
  538. | `--out=<文件>` | 指定成片路径(默认同目录同名);一份 HTML 出多套配色时用它,上级目录自动创建 |
  539. | `--json` | stdout 只输出一行结果 JSON(`output` / `duration` / `frames` / `warnings`),日志走 stderr |
  540. | `--headed` | 开着浏览器窗口渲(调试用;并发自动降到 1) |
  541. | `--allow-errors` | 页面报错不判失败(默认有报错就非零退出) |
  542. | `--readytimeout=8` | 等 `__seek` 就绪的秒数(大字体 / 大数据启动慢时调大) |
  543. | `--no-serve` | 用 `file://` 加载页面(默认走本地 http server,见下) |
  544. 渲一次发一堆:
  545. ```bash
  546. node scripts/render-video-seek.js explainer.html --duration=17.6 --fps=30 \
  547. --gif=15,960 --poster=6.0 # 成片 + 动图 + 封面,一次渲染全到位
  548. node scripts/render-video-seek.js --batch=jobs.json
  549. # jobs.json = [{ "html":"a.html","duration":6 }, { "html":"b.html","duration":8,"fps":60 }]
  550. ```
  551. **渲染结束时如果有页面控制台报错,会非零退出**(成片照样产出,方便核对)。
  552. 这是刻意的:报错通常意味着黑屏或缺内容,早年的版本会一路说成功,直到你回抽帧才发现。
  553. ### 断点续渲:渲到 80% 崩了,不用从零开始
  554. 1800 帧的片子跑到一半被掐掉,最伤的是重来一遍。加 `--resume` 接着渲:
  555. ```bash
  556. node scripts/render-video-seek.js animation.html --fps=60 --duration=30 --resume
  557. # ▸ resume: 已复用 1432 帧,还需渲 368 帧
  558. ```
  559. 三条规则都是为了保证**续出来的片子和一次渲完的片子逐像素一致**:
  560. - 帧先写 `.part` 再改名 —— 被 kill 的那一刻不会留下半张图冒充「已完成」,复用的都是真画完的帧
  561. - 参数变了直接拒绝(`fps` / 尺寸 / 范围任一项不同)—— 两批不同参数的帧混着编码,片子前后节奏会不一致,
  562. 而且**不报错**。报错里会打印「上次 vs 这次」,删不删由你决定
  563. - 编码前按帧号逐个核对连续覆盖 —— 缺一张 ffmpeg 会静默提前收尾,成片莫名变短
  564. 临时目录固定为 HTML 旁边的 `.seek-tmp-resume/`(不加 `--resume` 时仍是一次性目录,并发渲互不干扰),
  565. 渲完自动清掉;想留着配 `--keep-frames`。
  566. ### ESM / fetch 项目直接能渲
  567. 渲染器默认起一个**只绑 `127.0.0.1` 的本地 http server** 来加载页面(零新依赖,Node 内置 `http`)。
  568. `file://` 下 `<script type="module">` 和 `fetch()` 会被 CORS 拦死 —— 用 Vite/esbuild 组织的动画、
  569. 读本地 JSON 的项目根本起不来;走 http 就没这些事,而且是 `file://` 的严格超集。
  570. 渲染开头会打印这个地址,排障时直接粘到浏览器里看控制台最方便。
  571. 服务器起不来会自动退回 `file://` 并提示(只警告,不判失败)。
  572. ## 一条命令上手:`h2v`
  573. 脚本很多(渲染 / 分析 / 分镜 / 验收),记路径和参数很烦。装好依赖后有一个统一入口:
  574. ```bash
  575. npx html-to-video doctor # 环境自检:缺什么、怎么修(只读不改)
  576. npx html-to-video templates # 列出 14 个模板
  577. npx html-to-video styles # 列出 14 种风格
  578. npx html-to-video new my-video --template=quote-card
  579. npx html-to-video preview my-video.html --duration=6 --open
  580. npx html-to-video render my-video.html --duration=6 --fps=60
  581. ```
  582. 它只是把子命令映射到脚本、参数原样透传 —— 和直接 `node scripts/...` 完全等价。
  583. ### 改版式不用等渲染:拖时间轴预览
  584. 逐帧渲染最反直觉的是"改一句文案要等几分钟才看到效果",但页面本身暴露了
  585. `window.__seek(t)`。`preview` 就是把它当时间机器用:
  586. ```bash
  587. npx html-to-video preview my-video.html --duration=6 --fps=60
  588. # ▸ http://127.0.0.1:41234/tmp/h2v-preview-....html
  589. ```
  590. 空格播放 / ←→ 单帧步进 / 拖时间轴,看到的每一帧就是渲染器将要截到的画面。
  591. 竖屏项目加 `--size=1080x1920`,否则预览框是横的、排版按 16:9 算,容易误判。
  592. ### 跑不起来先跑 doctor
  593. ```
  594. ✓ Node.js 22.13.1
  595. ✓ Playwright 1.58.0 · ~/.cache/ms-playwright/chromium-1208/...
  596. ✓ Chromium 启动 无头模式可启动
  597. ✓ ffmpeg .../linux-x64/ffmpeg · 含 libx264 + ProRes
  598. ⚠ 中文字体 没检测到中文字体,成片里的汉字会变方块
  599. → apt-get install -y fonts-noto-cjk
  600. ```
  601. 三类最常见的失败(Playwright 版本与浏览器缓存不匹配、ffmpeg 缺 H.264、缺中文字体)
  602. 都能一次看出来,并给出可执行的修法。加 `--json` 给 CI / Agent 用。
  603. ## 动画要满足的契约
  604. 渲染器靠这两个全局钩子驱动,**必须有**:
  605. ```js
  606. window.__seek = (t) => { /* 把 t 时刻的画面完整重绘一帧 */ };
  607. window.__ready = true;
  608. // 渲染器会注入 window.__seekRender = true,
  609. // 此时必须冻结自驱时钟,完全由外部 __seek 推帧(保证确定性)
  610. if (window.__seekRender) { renderAt(0); window.__ready = true; }
  611. else { /* 浏览器预览:requestAnimationFrame 自驱循环 */ }
  612. ```
  613. `assets/animation-skeleton.html` 已实现完整契约,直接从它改。
  614. **铁律:每一帧 = 时间 t 的纯函数。** 不要用 `Math.random()` / `Date.now()`,
  615. 不要依赖上一帧的状态——否则同输入不同输出,多 worker 并行会各渲各的(验收里的「确定性」会亮红灯)。
  616. **画布就是唯一输出**:`<canvas>` 定位在 `left:0; top:0`,body `margin:0`。
  617. 渲染器截左上角,画布必须正好铺满视口、**不能居中**。
  618. **别用这些 class 名**(渲染器注入的 CSS 会无条件隐藏它们,元素会凭空消失):
  619. ```
  620. .no-record .progress .progress-bar .counter .tCur .phases .phase-label
  621. .phase .replay .masthead .kicker .title .footer
  622. ```
  623. 反过来,想让某块**出现在成片里**,给它加 `data-record-keep="true"` 就能豁免启发式隐藏。
  624. ## 动效库:assets/lib/motion.js
  625. 缓动、弹簧、步进、错开、拍号的纯函数库,和「冻结时钟 + `__seek(t)`」天然契合。
  626. ```html
  627. <script src="../lib/motion.js"></script>
  628. <script>
  629. const p = MO.expoOut(MO.seg(t, 0.3, 1.4)); // 0..1 进度,快出慢停
  630. const y = MO.lerp(80, 0, p);
  631. const s = 1 + MO.settle(t - 1.2, 0.06); // 到位后的余振
  632. const items = MO.stagger(t, 5, { t0: 0.4 }); // 5 项依次入场
  633. </script>
  634. ```
  635. 选缓动:讲解类 `MO.smooth` / `sineInOut`(两端都停稳);发布会 `MO.appleOut` / `MO.snappy`;
  636. 动态大字 `expoOut` + `MO.springHz`;纸片/拼贴 `MO.step(t, 12)` 一拍二。
  637. **别让画面「死」掉**:动效做完后若还要停留数秒,加一点持续微动(慢速光扫、呼吸),
  638. 否则观众会觉得视频卡住。模板里都带了这一手。
  639. ## 自动化验收:qa.sh
  640. ```bash
  641. bash assets/qa.sh my-animation.html --duration=12 --fps=30
  642. ```
  643. | 维度 | 量什么 |
  644. |---|---|
  645. | 确定性 | 抽 首/中/末 3 个时刻,各做「同页面 seek 回去」+「全新页面重渲」两轮逐像素比对 |
  646. | 动感 | 运动%、静止帧对比例、**最长连续静止秒数** |
  647. | 流畅 | 相邻帧差峰值/中位数,报「跳变」时刻 |
  648. | 框景 | hook `fillText` / `strokeText` / `drawImage`(离屏画布的文字会跟着贴图追到目标画布)+ DOM 文字按视觉行分块 → 半截字 / 叠字 / 进字幕带 / 近空白 |
  649. | 字体 | 字体是否可用、是否悄悄回退到兜底字体 |
  650. | 报错 | pageerror / console.error(有则判失败) |
  651. 产物:`qa/qa.md`、`qa/qa.json`、`qa/<名>.heat.png`(运动热图)。
  652. 纯 Node 实现,**零额外依赖**(像素运算借 Chromium 自己解码,不引 numpy / sharp)。
  653. 阈值是经验值不是规则:运动 0.5%–8% 多数好看;最长静止 ≥3s 会提示(有意定格可忽略);
  654. 跳变 >0 先去看那一帧;框景线索只是「去看一眼」的提示,不会让验收失败。
  655. **采样间隔要 ≤0.1s**,否则一段快速位移在相邻两帧之间看着就像「跳」——那是采样假象不是穿帮。
  656. 间隔 >0.15s 时会提示该把 `--samples` 提到多少。
  657. > 「最长连续静止」超标时,最省事的解法不是加装饰,而是加一点持续运镜
  658. > (`CAM.breath()`,见上)—— 画面在动,观众就不会觉得视频卡住。
  659. ## 渲得有多慢:自己量一次
  660. 不同机器差 3–5 倍,所以这里不写「约几分钟」这种拍脑袋的数字:
  661. ```bash
  662. npm run bench # 两个页面 × 两档分辨率 × 两种并发 → bench/bench.md
  663. ```
  664. 表里给 `s/帧`(已含并发)与「10s@60fps 预估」。**并发不是越大越好**:超过 CPU 核数之后
  665. 页面之间抢 CPU,`s/帧` 不降反升,表上能直接看出来。
  666. ## 配乐与派生格式
  667. ```bash
  668. FF="<工作区>/node_modules/@ffmpeg-installer/win32-x64/ffmpeg.exe" # Windows
  669. # 其它平台:FF="<工作区>/node_modules/@ffmpeg-installer/ffmpeg"
  670. # 混 BGM(0.8s 淡入 / 1.4s 淡出,视频流不重编码)
  671. "$FF" -y -i animation.mp4 -i "$BGM" -filter_complex \
  672. "[1:a]atrim=0:DUR,afade=t=in:st=0:d=0.8,afade=t=out:st=DUR-1.4:d=1.4,volume=0.5[a]" \
  673. -map 0:v -map "[a]" -c:v copy -c:a aac -b:a 192k -shortest -movflags +faststart animation-bgm.mp4
  674. # GIF(两阶段 palette 优化,否则糊)
  675. "$FF" -y -i animation.mp4 -vf "fps=15,scale=960:-1:flags=lanczos,palettegen=stats_mode=diff" palette.png
  676. "$FF" -y -i animation.mp4 -i palette.png -lavfi "fps=15,scale=960:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" animation.gif
  677. ```
  678. 也可以直接让渲染器混音:`--audio=bgm.mp3`。
  679. ## 中文字体与跨机器一致
  680. 默认用系统字体(`Microsoft YaHei` / `PingFang SC`)。这意味着「确定性」**只在单机成立**——
  681. 换台没有这款字体的机器,字形就变了。要跨机器复现就内嵌子集字体:
  682. ```css
  683. @font-face { font-family: 'MyCJK'; src: url('fonts/subset.woff2') format('woff2'); font-display: block; }
  684. ```
  685. 子集化(思源黑体 1.38MB → 约 300KB):装 `fonttools` 后
  686. ```bash
  687. pyftsubset 源字体.ttf --text-file=文案.txt --flavor=woff2 --output-file=subset.woff2
  688. ```
  689. 只统计会画到画面上的字——把注释里的中文也算进去,子集会胖很多倍。
  690. `qa.sh` 会检查字体可用性并提示「声明的字体其实没生效(悄悄回退了)」。
  691. ## 常见问题
  692. **报 `Executable doesn't exist`**
  693. Playwright 版本和浏览器缓存 build 号不匹配。跑 `node scripts/detect-env.js` 看该装哪个版本,
  694. 或干脆重跑 `bash scripts/install-deps.sh`。
  695. **Playwright 自带的 ffmpeg 不能用**
  696. `ms-playwright/ffmpeg-*/ffmpeg-win64.exe` 是 `--disable-everything` 编译的,
  697. 只有 VP8 + webm,**没有 H.264、没有 GIF、连 PNG 解码都没开**。必须用 `@ffmpeg-installer/ffmpeg` 的完整版。
  698. **chromium 下不下来**
  699. 某些网络环境会反复中断。此时正确做法是**复用已有缓存**而不是升级——
  700. `install-deps.sh` 就是为此设计的:它会迁就缓存挑版本。
  701. **Windows 上路径含撇号(如 `C:\Users\O'Brien\...`)**
  702. - bash 里别把路径写进 `${VAR:-默认值}`,撇号会被当引号开始 → `bad substitution`。本项目的配置文件机制就是绕这个的。
  703. - 传给 Node 的路径别用 Git Bash 的 `pwd`(返回 `/c/Users/...`,Node 会解析成 `C:\c\Users\...`)。
  704. **编码中途失败,帧会丢吗**
  705. 不会。渲染器会保留 `.seek-tmp-*/` 里的全部 PNG 并打印可直接粘贴的编码命令,不必重截:
  706. ```bash
  707. "$FF" -y -framerate 60 -start_number 0 -i .seek-tmp-*/frame-%06d.png -c:v libx264 \
  708. -pix_fmt yuv420p -crf 18 -preset medium -r 60 -movflags +faststart animation.mp4
  709. ```
  710. (`--from` 渲染时把 `-start_number 0` 换成对应的起始帧号。)
  711. **渲染成功但提示「逐帧目录没能自动删除」**
  712. 某些沙箱/托管环境给 `fs.rmSync` 套了「批量删除保护」,一次删几十个文件会被拦下。
  713. 渲染器会提示并给出目录路径,**成片不受影响**,手动删那个目录即可。
  714. ## 目录结构
  715. ```
  716. html-to-video/
  717. ├── SKILL.md 技能说明(WorkBuddy 读取)
  718. ├── CHANGELOG.md 更新日志与版本号规则
  719. ├── package.json 可 npm install;engines: node >= 18
  720. ├── CONTRIBUTING.md 贡献指南(加模板的四条硬约定在这里)
  721. ├── bin/h2v.js 统一命令入口(render / preview / beats / doctor / styles …)
  722. ├── scripts/
  723. │ ├── render-video-seek.js 渲染器内核:冻结时钟 + 逐帧 seek + ffmpeg 编码 + 报错判定
  724. │ ├── beats.js 节拍分析:ffmpeg 解码 → 能量通量 → 自相关 → 相位对齐
  725. │ ├── preview.js 浏览器预览服务器(拖时间轴,调 iframe 的 __seek)
  726. │ ├── doctor.js 环境自检:Node / Playwright / ffmpeg / 字体 / 磁盘
  727. │ ├── qa.js 自动化验收:确定性/动感/流畅/框景/字体/报错
  728. │ ├── bench.js 性能基线:量 s/帧,产出 bench/bench.md
  729. │ ├── lib/hide-chrome.cjs 隐藏播放控件的共享规则(渲染器与验收器同一份)
  730. │ ├── lib/local-server.cjs 本地 http 静态服务器(解锁 ESM / fetch,零新依赖)
  731. │ ├── lib/cues.cjs 字幕时间轴解析(SRT / VTT / JSON)
  732. │ ├── lib/qa-rules.cjs 验收判据的纯函数(可单测,也可注入页面)
  733. │ ├── lib/testing.mjs 测试公用件(依赖路径解析 / 子进程 / PSNR 探针)
  734. │ ├── detect-env.js 探测浏览器缓存,输出该装哪个 playwright 版本
  735. │ └── install-deps.sh 一键装依赖并写配置
  736. ├── test/
  737. │ ├── render-smoke.test.mjs 真渲两段(16:9 / 9:16),验分辨率与尺寸告警
  738. │ ├── multi-shot.test.mjs 多镜头:镜头表导出一致 / --story 换剧本 / 时长不符告警
  739. │ ├── output-features.test.mjs --gif / --poster / --batch / --concurrency=auto
  740. │ ├── scenes.test.mjs 镜头时间轴算术(重叠、局部时间、越界、未知转场报错)
  741. │ ├── camera.test.mjs 运镜:确定性、幅度上限、衰减、save/restore 成对
  742. │ ├── lib-draw.test.mjs 素材库:所有图标 / 人物组合不得产生 NaN
  743. │ ├── resume.test.mjs 断点续渲:复用、参数变脸、帧号断档
  744. │ ├── qa-clean.test.mjs 正常模板必须 PASS
  745. │ ├── qa-detects.test.mjs 对照组必须 FAIL(六类缺陷)
  746. │ ├── qa-offscreen.test.mjs 离屏画布的文字必须被追上
  747. │ ├── qa-dom-text.test.mjs DOM 文字按行分块,多行段落不误报
  748. │ ├── qa-rules.test.mjs 判据纯函数的单测
  749. │ ├── templates-contract.test.mjs 模板契约 + 能力登记表双向校验
  750. │ ├── beats.test.mjs 节拍:BPM / 拍距 / 相位 / 无节拍音频 / 静音
  751. │ ├── render-beats.test.mjs --beats 注入时机、--snap 吸附、错误参数明确失败
  752. │ ├── cli.test.mjs h2v 子命令 / new 拷贝依赖 / doctor --json
  753. │ ├── preview.test.mjs 预览服务器可访问、注入 __seekRender、清理临时副本
  754. │ └── fixtures/ 对照组页面(broken / offscreen-text / dom-text / beats-probe)
  755. ├── .github/workflows/ci.yml PR 自动跑 npm test
  756. ├── docs/ README 里用的演示动图 / 原片 / 静帧
  757. │ ├── demo-hero.html 首页那支 10 秒演示片的源文件(447 行,零依赖)
  758. │ ├── demo-*.gif / demo-*.mp4 模板的演示动图与原片
  759. │ ├── explainer-shots.csv 讲解片那支的镜头时间轴(--scene-log 导出)
  760. │ └── preview-*.png 静帧大图
  761. └── assets/
  762. ├── render.sh 全量渲染包装器
  763. ├── qa.sh 验收包装器
  764. ├── smoke.sh / smoke.cjs 冒烟测试:验证契约 + 试截关键帧
  765. ├── animation-skeleton.html 动画骨架模板(已实现完整渲染契约)
  766. ├── lib/motion.js 动效时间库(缓动/弹簧/步进/错开)
  767. ├── lib/scenes.js 多镜头时间轴 + 8 种转场
  768. ├── lib/camera.js 运镜(推拉/呼吸/手持/震动)
  769. ├── lib/shapes.js 40+ 图标 + 卡片/箭头/连接线/背景纹理
  770. ├── lib/figures.js 参数化人物 + 对话气泡
  771. └── templates/ 14 个开箱即用模板
  772. ├── themes.js 三套内置主题(midnight / paper / neon)
  773. ├── explainer.html 多镜头讲解片(人物 / 图标 / 转场 / 字幕)
  774. ├── title-card.html 片头标题卡
  775. ├── bar-chart.html 条形图 / 排名
  776. ├── line-chart.html 折线趋势
  777. ├── number-counter.html 大数字 / KPI
  778. ├── timeline.html 时间线 / 流程
  779. ├── vertical-card.html 竖屏 9:16 卡片
  780. ├── compare.html 前后对比
  781. ├── quote-card.html 引言卡 / 金句
  782. ├── chapter-card.html 章节卡 / 过渡页
  783. ├── ui-showcase.html 界面演示(聚光 + 标注)
  784. ├── flow-steps.html 流程图动画
  785. ├── subtitle-card.html 逐句解说卡
  786. └── vertical-subtitle.html 竖屏字幕卡(关键词高亮)
  787. ```
  788. ## 开发与测试
  789. ```bash
  790. npm install # 装 playwright(ffmpeg 见上面「安装」,必须是完整版)
  791. npm test # 99 个用例,约 2 分钟
  792. npm run bench # 量本机渲染速度 → bench/bench.md
  793. ```
  794. 测试里有一对**对照组**,这是整个项目最该守住的东西:
  795. | 用例 | 断言 | 防的是什么 |
  796. |---|---|---|
  797. | `qa-clean` | 正常模板必须 PASS | 判据过严 → 天天误报,人就不看了 |
  798. | `qa-detects` | `test/fixtures/broken.html` 必须 FAIL | 判据过松 → 质量门变成装饰 |
  799. | `qa-offscreen` | 离屏画布的文字必须被报出来 | 「看不见 = 查不出」的静默漏洞 |
  800. | `qa-dom-text` | 出界文字要报 / 多行段落不许报 | 修误报时顺手把检查关掉 |
  801. | `templates-contract` | 模板能力表与源码双向对齐 | 能力被悄悄删掉没人发现 |
  802. | `scenes` | 转场重叠与局部时间的算术 | 「某个镜头少了半秒」这种肉眼看不见的错 |
  803. | `camera` | 运镜确定性、幅度上限、save/restore 成对 | NaN 进 transform(画面整帧消失但不报错)、变换逐帧叠加 |
  804. | `lib-draw` | 所有图标 / 人物组合不得产生 NaN | 同上:素材库的静默失败 |
  805. 只调松不放对照组,等于把质量门拆了。改 `scripts/qa.js` 时全部跑一遍。
  806. ## 贡献
  807. 欢迎 PR。**最需要的是新模板**——尤其是需要和声音 / 数据联动的(波形动画、地图轨迹、真实数据接进来的图表)。
  808. 加模板的四条硬约定(渲染契约 / 画布跟随视口 / 字幕安全区 / 别定格太久)写在
  809. [CONTRIBUTING.md](CONTRIBUTING.md),照 `assets/templates/title-card.html` 抄骨架最快。
  810. 加了模板记得在 `test/templates-contract.test.mjs` 的 `CAPS` 里登记它的能力(主题 / 字幕 / 透明),
  811. CI 会检查源码和能力表是否对得上。
  812. 提 Bug 请带上**复现命令**和 `qa/qa.md` —— 比贴截图有用得多。
  813. ## License
  814. MIT
  815. `assets/lib/motion.js`(动效时间库)移植自 [huashu-art-motion](https://github.com/huashu-art-motion) 的
  816. `scripts/engine/lib/motion.js`(MIT),去掉了对原作者引擎的依赖,改成自包含。感谢原作者。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.