Skip to content
Back to search

html-explainer

把任意主题做成讲解/科普视频并渲染成 MP4(HTML/CSS/GSAP 画面 + 确定性逐帧渲染 + 配音 + 词级硬字幕)。触发场景:要做科普/讲解/教学/知识/产品类视频、「讲一下 X 做成视频」、要挑某种视觉风格(极简/数据/赛博/电影感/品牌)出片、要出抖音封面/竖版封面/9:16 封面、要用 html-video 那种模板化画面但更稳的音画同步、anything2explainer 换 HTML 渲染,或提到 html-explainer / HTML 讲解视频 / explainer video / MG 视频。内置 23 个模板风格(8 类)与 40+ 动作词汇的动效库,主题驱动模板编排;支持 4K60、快门运动模糊、多进程提速、断点续渲;流程含六个用户确认点(渲染通道是硬闸门)。独立可移植,不依赖 html-video / anything2explainer。

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/onemoh-html-explainer/badge.svg)](/listings/onemoh-html-explainer)

HTML

<a href="/listings/onemoh-html-explainer"><img src="/api/listings/onemoh-html-explainer/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.

一句话安装(推荐)

把下面这句发给你的智能体:

给当前本地环境安装该 Skill:https://github.com/OneMoh/html-explainer.git
安装到你的技能目录,并检测安装必要的运行环境(Python 3.9+ / Node 18+ / Chrome 或 Edge / ffmpeg)

它会自己 clone 到对应目录、跑环境自检、把缺的东西装上。装完**新开一个会话**,让智能体重新 扫描技能目录。

手动安装

仓库根目录**就是**技能目录(`SKILL.md` 在根),直接 clone 进技能目录即可,不用再拷子目录:

git clone https://github.com/OneMoh/html-explainer.git ~/.workbuddy/skills/html-explainer
bash ~/.workbuddy/skills/html-explainer/setup_env.sh --install

Windows 上 `~` 就是 `C:\Users\<你的用户名>`。

> **Windows 注意**:上面的 `bash` 指 **Git Bash**(装了 Git for Windows 就有),PowerShell / cmd > 里直接跑 `bash setup_env.sh --install` 会找不到命令 —— 用 `& "C:\Program Files\Git\bin\bash.exe" setup_env.sh --install`, > 或先开一个 Git Bash 窗口。 > 另外,不少宿主会在技能目录名后加命名空间后缀(例如 WorkBuddy 装出来的是 > `~/.workbuddy/skills/html-explainer__skillhub`),照实际目录改路径即可,技能本身不认名字。 > 项目路径请保持**全 ASCII** —— Windows 的 ffmpeg 把 UTF-8 当 ANSI 读,中文路径会在渲染阶段炸。

环境要求

| 项 | 最低 | 说明 | |---|---|---| | Python | 3.9+ | `edge-tts==7.3.1`(刻意钉死;7.2.8 握手已被微软 403)、`numpy`、`pillow`、`imageio-ffmpeg`;火山引擎**零额外依赖**(只用标准库 `urllib`) | | Node.js | 18+ | 渲染器与封面器用 | | 浏览器 | Chrome 或 Edge | 自动探测;都没有才下载 playwright chromium(约 115MB,只需一次) | | ffmpeg | 任意版本 | 先在 `PATH` 找;没有则用 `imageio-ffmpeg` 自带的静态二进制 | | 磁盘 | 每条成片约 2GB | 帧 PNG 体积大,合成后可删 |

`bash setup_env.sh` 只检查并报告缺什么,`--install` 才会装。全程不需要管理员权限。 **没有 GPU 要求,没有模型权重要下载** —— 依赖就是上面这几样。

---

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 · 647 lines
  1. ---
  2. name: html-explainer
  3. version: 2.0.10
  4. description: 把任意主题做成讲解/科普视频并渲染成 MP4(HTML/CSS/GSAP 画面 + 确定性逐帧渲染 + 配音 + 词级硬字幕)。触发场景:要做科普/讲解/教学/知识/产品类视频、「讲一下 X 做成视频」、要挑某种视觉风格(极简/数据/赛博/电影感/品牌)出片、要出抖音封面/竖版封面/9:16 封面、要用 html-video 那种模板化画面但更稳的音画同步、anything2explainer 换 HTML 渲染,或提到 html-explainer / HTML 讲解视频 / explainer video / MG 视频。内置 23 个模板风格(8 类)与 40+ 动作词汇的动效库,主题驱动模板编排;支持 4K60、快门运动模糊、多进程提速、断点续渲;流程含六个用户确认点(渲染通道是硬闸门)。独立可移植,不依赖 html-video / anything2explainer。
  5. agent_created: true
  6. ---
  7. # html-explainer
  8. > **定位**:`anything2explainer` 的流程与音画同步 + `html-video` 的 **23 个模板风格库**,
  9. > 渲染层独立实现。作者 **Moh**,MIT 许可(第三方声明见 `THIRD_PARTY_NOTICES.md`)。
  10. >
  11. > **零外部依赖**:不需要 Remotion/npm 工程,不需要 html-video 仓库/Studio/pnpm/agent 后端。
  12. > 技能自带:GSAP(离线)、playwright-core、渲染器、TTS/字幕/时间轴/主题/QC/封面全套脚本。
  13. > 对两个来源项目的引用**只存在于注释署名里**,运行时不读它们的任何文件。
  14. > 风格库是**抄下来的设计规范文本**(`references/style-catalog.md`),来源 `html-video`(Apache-2.0),
  15. > 类比:把菜谱抄回家,之后做菜不需要原餐厅营业。
  16. **v2.0 新增能力(全部可选、向下兼容;不用就是 v1.4 行为)**
  17. | 能力 | 入口 | 文档 |
  18. |---|---|---|
  19. | **动效库**(40+ 动作词汇) | `assets/motion.js` → `window.HXM` | `references/motion-library.md` |
  20. | **主题驱动模板编排**(挑风格 / 混用 / 动态开头) | `scripts/style_director.py` | `references/style-director.md` |
  21. | **画质帧率档位 + 快门运动模糊 + 提速** | `scripts/render_video.mjs --profile/--quality/--fps/--shutter-only/--motion-hold` | `references/render-profiles.md` |
  22. | **渲染基准测试**(优化前后对比) | `scripts/bench_render.py` | `references/render-profiles.md` |
  23. | **宣传片范式**(去模板化:模板只吸纳配色/字体/时序三层) | 设计方法 | `references/showcase-mode.md` |
  24. | **库全量演示编排**(统一舞台 + 节拍网格 + 标签常驻) | 设计方法 | `references/library-showcase.md` |
  25. | **确认闸门**(六个确认点由用户拍板才放行) | `scripts/gate_check.py` | `SKILL.md` 流程第 3 步 |
  26. | **★ 渲染通道确认**(渲染前必问:`png-fast` / `jpeg q95` / `png` / `jpeg q82`,**默认推荐 `png-fast`**,附速度与描述) | `consent.json` 的 `render_channel` + `gate_check.py --phase render` | `SKILL.md` 确认点 5 · `references/render-profiles.md` §0 |
  27. 把一个主题做成**原创**讲解视频:任意风格的 MG 画面(HTML/CSS/GSAP,1920×1080 或竖版)、
  28. 配音(edge-tts)、词级对齐硬字幕、全局进度条。一句话一个场景,画面节拍直接锚在
  29. 吐字时刻上(`B('块文本')` 节拍器)。
  30. ## ★ 画面风格库(23 个模板 / 8 个类别)
  31. **不要自己从零想画面 —— 先从风格库里挑;多个风格要混用时用编排器自动挑(见下)。**
  32. 挑出候选后交用户拍板(见**确认点 0**),不许静默自选。
  33. 完整目录(含每种的画布/字体/时间轴/配色纪律)
  34. 见 **`references/style-catalog.md`**;怎么改编成合规帧见 **`references/template-guide.md`**。
  35. **两种用法的深度不同,先分清在做哪一种**:
  36. | 你在做 | 怎么用风格库 | 读这篇 |
  37. |---|---|---|
  38. | **讲解片**(默认) | 从 23 个模板里**挑一个**,按 `template-guide.md` 改编成帧 | `references/template-guide.md` |
  39. | **宣传片 / 发布片**(去模板化) | 只从模板**吸纳配色 / 字体 / 时序骨架三层**,画面语言用 `assets/motion.js` 重写 —— **不搬模板画面** | **`references/showcase-mode.md`** |
  40. | **要全量展示某个库**(40+ 动效 / 23 个模板) | 统一舞台 + 节拍网格 + 标签常驻,把「N 个动作」演成「一个动作语言的 N 拍」 | **`references/library-showcase.md`** |
  41. > 判据:成片能被认出「这是 bold-signal 模板」= 吸纳过头;只能说「颜色像 xx、节奏像 yy」= 深度对了。
  42. > **★ v2.0:不要一片只用一个模板。** 用 `scripts/style_director.py` 读解说词,
  43. > 自动给每场挑主风格(按角色/时长/关键词打分)、按需搭次风格做**局部替换**、
  44. > 决定**动态开头变体**与**场间转场**、并算出每场的**动效强度**。
  45. > 详见 `references/style-director.md`。核心价值:**让模板服务于主题,而不是让主题被模板限制**。
  46. | 类别 | 可用风格 |
  47. |---|---|
  48. | 演示 / 标题卡 | 大胆海报帧、大胆信号卡帧、奢华极简留白帧、创意电压分屏帧、电光工作室分屏帧、故障艺术标题帧、Kinetic Type、Swiss Grid、Warm Grain |
  49. | 数据可视化 | NYT 风数据图表帧、数据滚动帧、NYT Graph、瑞士网格数据帧 |
  50. | 图解 / 流程 | 东方柔和有机帧、Decision Tree |
  51. | 氛围 / 空镜 | 胶片漏光电影帧 |
  52. | 营销 / Hero | 流体背景 Hero 帧 |
  53. | 片头片尾 | 品牌 Logo 收尾帧 |
  54. | 社媒竖版 | Play Mode、Vignelli(9:16)|
  55. | 产品演示 | Product Promo、Product Promo · 30s |
  56. | 特效 | VFX 文字光标 |
  57. **两类模板、两种改编成本**(速查表「类型」列):
  58. | 类型 | 数量 | 处理 |
  59. |---|---|---|
  60. | **★ rich** | 12 | 单文件 + 纯 CSS `@keyframes`。**零改动可渲染** —— 只需①换系统字体栈(删 Google Fonts)②让出底部字幕带③填真实内容 |
  61. | **gsap** | 11 | 多 composition + CDN GSAP(或 Remotion)。**不要搬代码**,只取视觉 DNA 用 CSS keyframes 重写(搬进来会得到静止首帧且零报错,见 `lessons.md` #9)|
  62. > 时长档要匹配内容:`frame-bold-signal` 是 3–6s 的短片花,拉长到 20s 会空。
  63. > 长段(>10s)优先选 3–30s 档的(Swiss Grid / Kinetic Type / NYT Graph / Warm Grain)。
  64. ## 何时用 / 不用
  65. - 用:给主题/文章/文档做讲解视频;要挑某种视觉风格出片;要 html-video 那种模板化画面但要求音画稳;要 anything2explainer 流程但不想装 Remotion。
  66. - 不用:复刻现有视频、真人口播、实拍为主;要 Remotion/React 代码动画本体(那是 anything2explainer 的领域)。
  67. ## 环境(首台机器跑一次)
  68. ```bash
  69. bash <skill>/setup_env.sh # 自检;--install 联网补装
  70. ```
  71. 依赖:Python≥3.9(edge-tts==7.3.1 钉死 / numpy / pillow / imageio-ffmpeg)、Node≥18、
  72. **火山引擎零额外依赖**(`tts_volcano.py` 只用标准库 `urllib`,不需要装任何 SDK)。
  73. Chrome 或 Edge(几乎必有;都没有才下载 playwright chromium ~115MB)、ffmpeg(PATH 或
  74. imageio-ffmpeg 静态二进制自动回退)。Windows 注意:项目路径全 ASCII;给 Node/Python
  75. 传 `C:/...` 正斜杠路径;别用 heredoc 给 Python 传正则。
  76. ## 命令流水线(项目目录内,顺序不能乱)
  77. ```bash
  78. PY=<venv python 绝对路径> # 派子 agent 时必须展开成绝对路径写进 prompt
  79. "$PY" <skill>/scripts/new_project.py <dir> <slug> --topic "主题" # 阶段 0 建项目
  80. "$PY" <skill>/scripts/tts_setup.py --project . # ★ 先定配音方案 + 音色(问用户:edge / 火山)
  81. "$PY" <skill>/scripts/tts_build.py --project . # 配音:audio/*.mp3 + manifest
  82. "$PY" <skill>/scripts/timeline_build.py --project . # 全局时间轴:layout.json + narration-full.mp3
  83. "$PY" <skill>/scripts/subs.py --project . # 字幕:subs.json + beats.js + srt/vtt
  84. "$PY" <skill>/scripts/check_beats_refs.py --project . # ★ 节拍引用校验:B()/Be() 是否都能解析(前缀匹配,失配秒级报出可用块)
  85. "$PY" <skill>/scripts/style_director.py --project . # ★ v2.0 风格编排:读解说词给每场挑主/次风格 + 开场变体 + 转场 + 动效强度 → style-plan.json
  86. "$PY" <skill>/scripts/gate_check.py --project . # ★★ 确认闸门:六个确认点未由用户拍板 → 拒绝放行(缺 consent.json 用 --init 生成)
  87. "$PY" <skill>/scripts/gate_check.py --project . --phase render # ★★ 渲染前必过:render_channel(渲染通道)未拍板 → 拒绝渲染
  88. "$PY" <skill>/scripts/lint_frames.py --project . # 静态体检:八条契约违规(渲染前一秒出结果,比渲完再发现便宜得多)
  89. node <skill>/scripts/check_layout.mjs . # ★ 几何体检:越界 / 侵入字幕带 / 元素互相遮挡(lint 看不见几何)
  90. node <skill>/scripts/render_video.mjs . [--audio audio/narration-full.mp3] [--profile draft|balanced|final|master] [--quality 1080p|2k|4k] [--fps 30|60] [--shutter 180] [--shutter-flush 4] [--shutter-only <场景id,场景id>] [--motion-hold 1] [--preview 30] [--keep-frames] [--only <场景id>] [--mux-only] [--png-fast|--jpeg --jpeg-quality 95] [--workers N] [--concurrency N] [--resume] # 渲染:out/<slug>.mp4(★ 通道/档位先按确认点 5 问过用户;★ 通道与档位必须一起报——`--jpeg` 与默认快门同时用,中间帧扩展名要一路贯穿到积分器;★ 快门覆盖面也要问:全片开还是 `--shutter-only` 点名几场)
  91. "$PY" <skill>/scripts/qc_check.py --project . # 体检 + 抽帧速览图
  92. node <skill>/scripts/cover_build.mjs . # 封面:out/cover_169.png + cover_34.png(竖版再加 cover_916.png)
  93. node <skill>/scripts/check_cover.mjs . # 封面终态几何实测:边距/钩子字号/行宽/孤字/文字重叠/9:16 禁两栏(FAIL 清零再交)
  94. ```
  95. 配音引擎(**跑之前必须先问用户**,见确认点 3):`edge`(默认,免费免密钥)或
  96. `volcano`(火山引擎语音合成 2.0,音质更好,需 API Key)。两者产出的 manifest 结构一致,
  97. 下游零改动。切换:`--provider edge|volcano` 或 `TTS_PROVIDER` 环境变量。
  98. **火山密钥只存 `tts.env`(已 gitignore)—— agent 只调 `tts_volcano.py`,不读该文件。**
  99. 详见 `references/volcano-tts.md`。
  100. ### ★ 确认点 5 —— 渲染通道:**动手渲染前必须问用户选哪条,不许默认开工**
  101. **硬规则:任何一次真正的渲染(打样 / 全片 / 局部补渲)之前,先把下表摆给用户让他挑通道。
  102. 不许凭「上次用的 png-fast」或「PNG 是默认」就静默开工。** 用户在打样阶段选定后,
  103. 同一轮的重复渲染可沿用;**换通道或换档位要重新确认一次**。
  104. | 通道 | 参数 | 相对速度(纯 CSS 图形帧并行 / 满幅照片帧) | 画质(客观口径) | 中间帧体积(1080p · 纯图形帧实测) | 定位 |
  105. |---|---|---|---|---|---|
  106. | **PNG-fast** ★**默认推荐** | `--png-fast` | **×1.02 / ×4.4** | 逐像素无损(PSNR 99 dB、最大差 0) | **0.10 MB/帧**(8525 帧 ≈ **0.85 GB**) | 纯 CSS/MG 图形帧上**与 JPEG q95 同速、体积更小、还是无损** → 默认就用它 |
  107. | **JPEG q95** | `--jpeg --jpeg-quality 95` | ×1.00 / **×13** | PSNR **41.65 dB**,低于 x264 crf18 成片自身失真 | 0.12 MB/帧 | **含满幅照片 / 重合成帧、或 4K 终稿**时的首选(照片帧上 PNG 是 582ms/帧的黑洞) |
  108. | **PNG**(1.4.x 默认) | 不带开关 | ×1.16 / ×1.0(基准) | 逐像素无损 | 0.08 MB/帧 | 仅 `--profile legacy` 逐位复现旧成片、或 `master` 极限档 |
  109. | **JPEG q82** | `--jpeg --jpeg-quality 82` | 最快 | 略低于 q95,仍高于多数成片编码失真 | ~0.08 MB/帧 | 只做打样/迭代预览,不用于交付 |
  110. > **体积口径提醒**:上表体积是**纯 CSS/MG 图形帧**(大面积平色 + 文字)实测。同一批通道在
  111. > **满幅照片 / 重合成帧**上会整体抬高一到两个数量级(精细 PNG 单帧可达 1.6–2.0 MB),
  112. > 表格里的相对关系不变,但绝对量级不可直接套用。
  113. **为什么默认改成 PNG-fast(2026-10-05 口径修订)**:原表把 JPEG q95 列为默认推荐,
  114. 依据是「×13 编码速度」—— 但那组倍率测的是**满幅照片帧**。本技能绝大多数片子是
  115. **纯 CSS/MG 图形帧**,PNG 的 deflate 对平色块极其高效,本机 6 进程并行实测:
  116. | 通道 | 吞吐 | 相对 | 体积 |
  117. |---|---|---|---|
  118. | JPEG q95 | 27.14 帧/秒 | ×1.00 | 0.12 MB/帧 |
  119. | **PNG-fast** | **26.65 帧/秒** | **×1.02** | **0.10 MB/帧** |
  120. | PNG 精细 | 23.41 帧/秒 | ×1.16 | 0.08 MB/帧 |
  121. → **纯图形帧上 PNG-fast 与 JPEG q95 基本同速、体积更小、且逐像素无损**,默认场景下全面占优。
  122. 而「**JPEG q95 不是降质**」这句依然成立:中间帧还要再被 x264 压一次,q95 的 PSNR 41.65 dB
  123. 低于 crf18 成片自身失真,所以它在**照片帧 / 4K 终稿**里依旧是对的默认。
  124. **怎么问(照抄这句,四条都要列全 —— 这是硬要求)**:
  125. > 渲染通道你要哪条?
  126. > **① PNG-fast(推荐 —— 纯 CSS/MG 图形帧上实测与 JPEG q95 同速、体积更小,且逐像素无损)**
  127. > ② JPEG q95(**含满幅照片/重合成帧、或 4K 终稿**时首选;照片帧上 PNG 是 582ms/帧的黑洞。不失质:失真低于成片自身编码失真)
  128. > ③ PNG(最慢,只有要逐位复现 1.4.x 老成片时才选)
  129. > ④ JPEG q82(最快,只适合打样)
  130. **自动推荐口径**(给建议时按这个判,但仍要用户点头):
  131. - **默认(绝大多数片子,纯 CSS/MG 图形帧)** → **`--png-fast`**(同速 + 体积更小 + 逐像素无损)。
  132. - 帧里有**满幅照片 / 重合成**、或 **4K 终稿** → **`--jpeg --jpeg-quality 95`**
  133. (照片帧上 PNG 是 582ms/帧,是最大的时间与磁盘黑洞;4K 精细 PNG 单帧 2–6 MB)。
  134. - **中间帧必须逐像素无损**(合规 / 归档 / 要拿去二次调色)→ `--png-fast`。
  135. - 只是**看节奏的打样** → `--profile draft`(档位内已含 `png-fast`)+ `--preview`。
  136. - **精细 PNG** → 只在 `--profile legacy` 逐位复现旧成片时才用。
  137. > 档位表里的 `shot` 字段(`draft`/`balanced`/`final` = `png-fast`)**保持原样不动** ——
  138. > 它现在与推荐口径**是同一个值**:不传通道参数时就走 PNG-fast,两者已不再冲突。
  139. > 只有照片 / 4K 场景才**显式**加 `--jpeg --jpeg-quality 95`。
  140. **关键事实:中间帧编码在浏览器进程内是串行的,`--concurrency` 对 PNG 完全无效**
  141. (实测并发 1/3/6 路的总吞吐 1.80 / 1.86 / 1.87 帧/秒)。想加速只有两条路:**换通道**或
  142. **加 `--workers`(真·多进程)**。照片类片子的历史教训见 `lessons.md` 第 69 条。
  143. 选定的通道写进 `consent.json` 的 `render_channel` 字段,由 `gate_check.py` 挡在渲染之前。
  144. ### 快门(运动模糊)开 / 关,到底影响什么
  145. 用户几乎一定会问这句,照下表答(**不是**"开了更好看"这么含糊):
  146. | | **开**(`balanced` 默认,180°) | **关**(`--shutter 0`;`draft` 档即无快门) |
  147. |---|---|---|
  148. | 观感 | 运动中的元素带真实拖影,**快速横移 / 推镜不闪、不跳帧**,更像摄影机拍的 | 运动元素是清晰硬边;快速横移在 30fps 下会有轻微顿挫感(judder) |
  149. | 画质 | 线性光 8 样本积分,比"后处理 blur 滤镜"干净得多(不会糊成一坨) | 无损失(就是清晰帧) |
  150. | 速度 | **慢 ≈6.4×**(每个动帧 = 8 次完整页面渲染 + 一次 numpy 积分) | 快 —— 本机实测 **18.4 帧/秒**(8525 帧 9 分钟) |
  151. | 磁盘 | 高:样本会堆积,必须靠 `--shutter-flush` 护栏压峰值(见 `render-profiles.md` §6) | 低(只剩最终帧) |
  152. | 值得开 | 有**真实位移运镜**(推拉摇移)、大片幅元素横穿、要电影感 | 画面以**静态排版 + 出场动画**为主(绝大多数 MG 科普 / 数据讲解片) |
  153. **判据:画面里有没有「大幅位移的连续运动」。** 只有淡入淡出、逐行出现、数字跳动的话,
  154. 快门基本是白付 8× 的账;有横移 / 推镜时它才换来肉眼可辨的顺滑。
  155. #### ★ 只在需要的那几场开 —— 别让全片为几处运镜买单(v2.0.3)
  156. 上面那张表是「全片开 / 全片关」的二选一。但真实片子里**需要拖影的往往只有几场**。
  157. 三级闸门(粗 → 细)把成本只花在该花的帧上:
  158. ```bash
  159. # ① 场景级白名单:只有这两场开快门,其余场走零成本单张(不采样 / 不落盘 / 不积分)
  160. node <skill>/scripts/render_video.mjs . --shutter-only hook,cta --jpeg --jpeg-quality 95
  161. # ② 帧级(可靠):帧里导出 window.__motion(t0,t1),位移 < 1 设备像素的帧自动单张落盘
  162. node <skill>/scripts/render_video.mjs . --motion-hold 1
  163. ```
  164. | 级别 | 开关 | 粒度 | 判据 | 8525 帧实测 |
  165. |---|---|---|---|---|
  166. | ① | `--shutter-only <id,id>` | 场景 | 白名单 | 快门钉在点名的那几场,其余零成本 |
  167. | ② | `--motion-hold <px>`(默认 1) | 帧 | 页面导出的 `__motion` | **可靠**:位移不到 1px 直接单张,不截图 |
  168. | ③ | 自动,无开关 | 帧 | `first.equals(last)` | **只判掉 ~20%**,剩下 80% 全额付费 |
  169. > **为什么 ③ 不可靠**:阈值等于 0 —— 快门窗口只有 16.7 ms,任何亚像素抗锯齿差异都让两张
  170. > PNG 不等。实测 8525 帧里只有 **~20%** 被 ③ 判成 hold,截图吞吐 **18.4 → 2.9 帧/秒(≈6.4×)**。
  171. >
  172. > **想省快门成本,就让帧诚实导出 `window.__motion(t0,t1)`**(写法见 `motion-library.md`;
  173. > `assets/motion.js` 的 `screenTravel(c0,c1)` 直接给这段运镜走了多少 px)。
  174. >
  175. > ⚠ 反直觉坑:给整场加的**全时长缓慢推镜**每帧只走不到 1px(肉眼无拖影),却让 `__motion`
  176. > 全非零 → ②变成无操作、③必然不等 → **整场全额付费**。要么导出 `__motion` 让 ②摘掉它,
  177. > 要么别加这种「防静止」的整场推镜。
  178. >
  179. > 截图结束会打印 `快门覆盖面:X/Y 帧走快门采样`;日志里 `位移闸门 0` 就是
  180. > 「② 完全没起作用」的告警信号。
  181. **v2.0 画质×帧率档位**(`--profile`,显式开关永远覆盖档位默认值):
  182. ```bash
  183. node <skill>/scripts/render_video.mjs . --list-profiles # 看全部档位与实测量级
  184. node <skill>/scripts/render_video.mjs . --profile draft # 打样:1080p30,无运动模糊,最快
  185. node <skill>/scripts/render_video.mjs . --profile balanced # ★ 默认推荐:1080p30 + 快门运动模糊
  186. node <skill>/scripts/render_video.mjs . --profile final # 终稿:4K60 + 运动模糊
  187. node <skill>/scripts/render_video.mjs . --quality 2k --fps 60 --shutter 180 # 自由组合
  188. ```
  189. | 档位 | 画质 | 帧率 | 快门 | 说明 |
  190. |---|---|---|---|---|
  191. | `draft` | 1080p | 30 | 关 | 打样/迭代,最快 |
  192. | `balanced` | 1080p | 30 | 180° | **默认推荐**(质量/速度平衡) |
  193. | `final` | 4K | 60 | 180° | 终稿(**原始工作量**约 1080p30 的 8–12×;并行后墙钟差距远小于此,见 render-profiles.md) |
  194. | `master` | 4K | 60 | 180° | 极限画质(PNG 精细 + 最慢编码) |
  195. | `legacy` | 1080p | — | 关 | 逐位复现 v1.4.x 旧成片 |
  196. - **快门运动模糊**是**线性光下多样本积分**(不是 blur 滤镜);`hold` 静帧直接沿用单张,
  197. 不落样本、不进积分。**判 hold 有三级闸门(见上)—— 只有导出 `window.__motion` 的那级才可靠。**
  198. 快动作 > 80px/帧 不开快门会重影成串。
  199. - **多浏览器进程级并行**(`--workers`)+ `--resume` 断点续渲 + `--recycle` 定期重启浏览器(4K 长片防 OOM)。
  200. - 画质只改 `deviceScaleFactor`(1× / 1.333× / 2×),**布局逐像素不变**,只是采样更密。
  201. - 完整权衡(速度/质量/体积)、基准数据与硬件要求见 **`references/render-profiles.md`**。
  202. 辅助工具(随时可用,不进主流水线):
  203. ```bash
  204. "$PY" <skill>/scripts/make_theme.py --topic "医疗" --use # 主题换色(只重写 theme.css,帧零改动)
  205. node <skill>/scripts/peek_frame.mjs . <帧id> --at 40,80 # 单帧速览:秒级出图,先看设计对不对
  206. node <skill>/scripts/peek_frame.mjs . <帧id> --at-sec 3.5,12,16.2 # ★ 更推荐:按「绝对秒」定位
  207. # ★ --at 是**百分比**(相对 GSAP 时间轴全长);轴长常被尾段防冻层拉长 10–60s,
  208. # 所以「帧尾终态」对应的百分比因帧而异、极易算错 —— 优先用 --at-sec。
  209. # 看终态取 speech_end−1.5s,看中段取 speech_end/2(值都在 frames/<id>.beats.js 的 __SEG__ 里)。
  210. # 没有 --at-sec 时才退回 --at(查冷开场空屏传 1,3,6 这种小百分数)。
  211. node <skill>/scripts/peek_frame.mjs . <帧id> --at 100 --guides # 叠十字中线 + 字幕禁区线(判对齐必开)
  212. "$PY" <skill>/scripts/frame_at.py --project . --at 1:23 # 时间点 → 场景/帧号/源文件/终态帧图
  213. "$PY" <skill>/scripts/frame_at.py --project . --list # 全片场景时间表
  214. ```
  215. 画面排障(用户报「几分几秒」→ 定位到帧 → 视觉模型看图 → 改 → 局部重渲)的完整四步见
  216. 上文「★ 画面出错怎么定位」。
  217. 顺序不能乱:tts → timeline → subs(beats 依赖前两者)→ lint → 渲染 → QC → 封面。改解说词 → 重跑前三条,
  218. `frames/<id>.beats.js` 自动刷新,**场景 HTML 一行不用改**(这是对 anything2explainer
  219. 「帧号硬编码、改一个字全片重对位」的结构性改进)。
  220. > **`--preview` 会删掉渲出来的帧**(设计上是「预览模式顺手清草稿」)。凡是要拿 PNG 做
  221. > 拼接 / 复核 / 只重渲单场,一律加 `--keep-frames`,否则帧目录会在合成后被清空(lessons #32)。
  222. > 只改了一两个场景的画面时,**不要全片重渲**:用「临时项目法」按全局帧号补渲再贴回,
  223. > 本片 3802 帧全重渲 924s,补渲 hook+outro 两段只花 220s(lessons #33)。
  224. ## ★ 封面(成片后必做,不是可选项)
  225. 封面决定点击率,成片决定完播率 —— 一张被切掉半个钩子的封面会让整片白做。
  226. **默认出两张(16:9 + 3:4),竖版投放再加第三张 9:16。** 用户点名某画幅就按用户说的出。
  227. | 规格 | 画布 | 输出 | 用途 |
  228. |---|---|---|---|
  229. | **A. 抖音主封面** | 1920×1080 | `out/cover_169.png` | 信息流 / 播放页 |
  230. | **B. 兼容 3:4** | 1440×1080 | `out/cover_34.png` | 主页栅格(防切字) |
  231. | **C. 竖版 9:16** | 1080×1920 | `out/cover_916.png` | 竖版全屏信息流 / 小红书 / 视频号 |
  232. **核心纪律:每张都是独立排版,不是裁切关系。**
  233. 从 16:9 居中裁 3:4 只剩 810px 宽,丢掉 **57.8%** 画面;裁 9:16 只剩 608px 高,丢掉 **43.7%**。
  234. 大字钩子必被切。所以各张共享同一套视觉基因(配色/幕底/主视觉/钩子文案),**各自重排一次版**:
  235. | 元素 | 16:9 版 | 3:4 版 | 9:16 版 |
  236. |---|---|---|---|
  237. | 悖论视觉 | 右侧,左右并置 | 上方,竖排堆叠 | 上段(10–45%),竖排堆叠 |
  238. | 钩子 | 左下,两行 132px | 下方,三行 118px | 中下段(50–88%),三行 150px |
  239. | 角标 | 左上 | 顶部居中 | 顶部居中(留 ≥180px 上边距) |
  240. | 每行字数 | ≤8 字(防孤字断行) | ≤8 字 | ≤6 字 |
  241. | 分裂线 | 右栏内横线 | 横贯(留边距) | 横贯(留边距),**不要竖线** |
  242. **9:16 专属纪律**:上边距 ≥180px、下边距 ≥160px(让开平台顶/底 UI 层,这是**不可裁区**);
  243. **禁止左右两栏**(1080 宽里两栏必然放不下字)。
  244. **封面三要素**(缺一返工):① 大字钩子(≥96px / ≥120px / ≥130px,含反差悬念)
  245. ② 核心悖论视觉(两数对照 / 一升一降 / 分裂线 / 一明一暗,不是装饰图形)
  246. ③ 信息余量(四边 ≥96px / ≥110px / 左右 ≥90px,无贴边文字)。
  247. 做法:复制 `assets/cover-template.html` 为 `frames/cover_169.html`、`frames/cover_34.html`、
  248. `frames/cover_916.html`(竖版才要第三份),各自排版 → `node scripts/cover_build.mjs .`
  249. (默认 seek 到时间轴末尾取完整态,`--at 0.8` 可取入场中间态;缺哪张就跳哪张)。
  250. **出图后必跑几何实测** —— 肉眼只能看出明显问题,差 20px 的贴边、多出一字的孤行全靠它抓:
  251. ```bash
  252. node <skill>/scripts/check_cover.mjs . # 量三张:边距 / 钩子字号 / 行宽 / 孤字 / 文字重叠 / 9:16 禁两栏
  253. node <skill>/scripts/check_cover.mjs . --only 916 # 只量一张
  254. node <skill>/scripts/check_cover.mjs . --shot # 顺手把 1x 预览图丢到 out/
  255. ```
  256. 它按 `tl.pause(tl.duration(), false)` 把页内时间轴 seek 到轴末再量(**必须量终态**,lessons #30),
  257. FAIL 清零才算封面过。退出码 0/1,可直接挂流水线。
  258. 详规见 **`references/cover-guide.md`**。
  259. ## 核心机制(为什么音画稳)
  260. | 机制 | 口径 |
  261. |---|---|
  262. | 帧时长 | MP3 **容器时长**(tts_build 裁首尾静音后回填)。词边界时长每段少 ~0.86s,用它必错位 |
  263. | 末块字幕收尾 | 语音**真实结束**(speech_end_sec)—— 两级时钟,混用则「字幕过了语音还没过」 |
  264. | 字幕节拍 | 词级时间戳首字对帧号,绝不按字数插值(中文同字数时长差 3 倍)。edge 取 `WordBoundary`,火山取 `sentence.words[]`(**需显式开 `audio_params.enable_subtitle`,本包默认开**;不开会静默退回插值) |
  265. | 画面节拍 | 场景 HTML 里 `B('块文本')` 取该词起播秒排 GSAP —— 画面与吐字同源 |
  266. | 渲染 | **确定性 seek**:`tl.pause(t, false)` + CSS 动画 `currentTime=t×1000` → 截图 → ffmpeg 合成。无实时录制,html-video 的引导期/起播/字体坑整类不存在。**第二参必须传 `false`**,少了它 `onUpdate` 类回调被静默抑制(数字滚动恒为初值,见 lessons #27) |
  267. | 字幕层/进度条 | 渲染器注入并逐帧驱动(`#mg-subs` 44px 白字黑边 bottom 96px;`#mg-progress` accent 填充),帧作者零负担 |
  268. ## 流程(六个确认点必须停下等用户回话)
  269. 完整版见 `references/workflow-guide.md`(含研究员/构建/QC agent 的 prompt 模板与时长档位表)。
  270. 0. **建项目**(5 分钟):`new_project.py` + 定主题(`make_theme.py --topic/--preset … --use`,颜色全在 theme.css 的 CSS 变量里,画面代码禁止色值字面量)
  271. ### ★ 确认点 0 —— 配色 / 风格一律先问,禁止凭记忆替用户拍板
  272. **这是硬规则,每一期都要走一遍,不得沿用上一期的选择。**
  273. - 开工(乃至挑风格)之前,先给用户 **2–4 个候选**,每条写清三件事:
  274. **① 色号(hex)② 一句气质描述 ③ 适合什么内容**。让用户挑,而不是替他挑。
  275. - **风格模板同样要问**:从 `references/style-catalog.md` 选出 2–4 个候选列出来,
  276. 不要静默从「上次挺好用」的记忆里定 2–4 种。
  277. - 用户**自带色号**时:照他的色号落地,但仍要回报
  278. 「我打算用哪个色做哪个语义(重点 / 指标 / 警示)」,请他确认。
  279. - 用户明确说「你决定」「按你上一次的来」时才可以自行选择 —— 且要说明选了什么、为什么。
  280. - ⚠️ 反面教材:看到暖色题就默认 `--preset amber`、看到数据题就默认瑞士网格。
  281. 记忆里"好用"的东西不构成用户的选择。
  282. - **设计思维要一次问全**(宣传片 / 发布片尤其)—— 除配色外,还要问清三件事:
  283. ① **影片形态**(纯视觉宣言 / 主视觉+章节讲解 / 双版本);
  284. ② **库演示方式**(全量逐条罗列 / 分组深挖 / 精选高光);
  285. ③ **时长与画幅**(多少秒;是否出竖版成片与 9:16 封面)。
  286. 这四问的答复**全部写进 `consent.json`**,然后由 `gate_check.py` 挡在场景构建之前。
  287. 1. **调研**(20 分钟,1 agent):research/调研.md,每个数字带 URL;**确认点 1**(时长/语言 + **投放画幅与封面张数**)并行问
  288. **确认点 1 顺带问一件事:封面要哪几张。** 默认 16:9 + 3:4 两张(横版投抖音/视频号)。
  289. 若用户会投**竖版**(竖版成片、全屏竖版信息流、小红书、朋友圈),要**再加 9:16 那张** ——
  290. 9:16 不是把 3:4 拉长,是另一种构图(左右并置必须改上下堆叠、上下边距让开平台 UI 层)。
  291. 现在问清,后面就不用返工;用户说「按默认」就只做两张。
  292. 2. **解说词**(30 分钟):narration.json(`|` 切字幕块,中文 ≤16 字/块)→ 填 order → **确认点 2**(文案定稿)→ **确认点 3**(配音方案 + 音色)→ tts/timeline/subs 三连 → 核对时长区间(差 >15% 改句子,别改语速硬凑)→ **定稿后不改词**
  293. **确认点 3 必须问两件事**(用 `tts_setup.py` 落实):
  294. ① **方案** —— 「配音用 edge-tts(免费、免密钥、开箱可用)还是火山引擎语音合成 2.0
  295. (音质更好,需要 API Key,约 1 分钟配置)」;
  296. ② **音色** —— 选定方案后列候选让用户挑,也可自定义 ID。
  297. 选火山时:缺 `tts.env` → `tts_setup.py` 生成空模板并**停下来**,让用户手工填密钥
  298. (**agent 不读该文件、不参与填值**);用户说填好了 → `--check` 测连接 → 再选音色。
  299. ★ 提醒用户用 `cp tts.env.example tts.env` **复制**,别把 `tts.env.example` **改名**成
  300. `tts.env` —— 那是要留在仓库里的模板(改名会让 `check_integrity.py` 报错)。
  301. 详见 `references/volcano-tts.md`。
  302. 3. **分镜(含选风格,20 分钟)**:script/storyboard.md,每场景一行 ——
  303. **先从风格库挑出 2–4 个候选交用户选(受确认点 0 约束,不可静默自选)**,
  304. 再照 `references/style-catalog.md` 的「挑风格的实用建议」表核对内容类型与时长档,
  305. 最后写画面/主角·尺寸/光/B() 锚点;末尾全局约束
  306. (贯穿示例、事实清单、每章 1–2 高光时刻、每章 ≥3 运镜)。
  307. 全片建议 2–4 种风格轮换,避免 8 个场景全用同一个模板。
  308. ### ★ 确认闸门 —— 进阶段 4 之前必须过(把纸面规则变成硬闸门)
  309. ```bash
  310. "$PY" <skill>/scripts/gate_check.py --project . # 缺一项确认就拒绝放行
  311. "$PY" <skill>/scripts/gate_check.py --project . --phase render # ★ 渲染前再跑:只查渲染通道拍板没有
  312. ```
  313. 为什么要有这一步:**纸面规则会被静默跳过** —— 确认点写得再清楚,
  314. agent 也可能直接跑 `style_director.py` 把风格自选了,用户事后才发现「你没问过我」;
  315. 渲染同理:默认 PNG 一路渲完,用户才发现「你没问过我用哪条通道」。
  316. 本闸门要求 `consent.json` 里**七项**(配色 / 风格 / 形态 / 配音 / 时长 / 封面 / **渲染通道**)
  317. 全部由用户拍板(`decided_by == "user"`),任一缺失即退出码 1。
  318. 缺文件时用 `--init` 生成模板,脚本**不替用户选任何一项**。
  319. 其中 `render_channel` 由 **`--phase render`** 在每次渲染前单独复检(确认点 5)。
  320. 4. **场景构建(并行)**:每组 4–8 场景一个 agent(一波 ≤3–4 个)。
  321. - 挑中的 **rich** 模板:从它的 `source/index.html` 改写 —— ①删 Google Fonts 换系统栈
  322. ②底部元素抬到 ≥176px ③填真实内容(照 `example.md` 的字段)
  323. - 挑中的 **gsap** 模板:**别搬代码**,只照风格规范用 CSS keyframes 重写
  324. - 全新画面:从 `frames/_template.html` 复制,契约见 `references/frame-contract.md`
  325. - 改编细则见 `references/template-guide.md`;边做边写盘
  326. - 想「照镜子」不必渲全片:`node scripts/peek_frame.mjs <项目> <id> --at 40,80` 秒级出图
  327. 5. **静态体检**:三条命令,全是秒级,**都在渲染之前**:
  328. ```bash
  329. "$PY" scripts/check_beats_refs.py --project . # ① B()/Be() 是否都能解析(前缀匹配)
  330. "$PY" scripts/lint_frames.py --project . # ② 八条契约违规
  331. node scripts/check_layout.mjs . # ③ 几何(遮挡/越界/侵入字幕带)
  332. ```
  333. ① 管**节拍引用**:`B()` 抛错只在渲到那一帧时才发生,前面几百帧白渲 —— 必须提前抓;
  334. ② 管**文本规则**(外链字体、色值字面量、墙钟逻辑、`B()||N` 兜底、字幕带压内容、缺中文字体族…);
  335. ③ 管**几何** —— lint 看不见几何,元素互相遮挡 / 侵入字幕带 / 出画只有它管。
  336. **三条全绿再进渲染**(比渲完几千帧再回来看便宜得多)。
  337. 6. **打样**:`render_video.mjs . --preview 30` → **确认点 4**(风格/字号/语速/节奏一次定稿)
  338. → **★ 确认点 5 —— 渲染通道**:把 `png` / `png-fast` / `jpeg q95` / `jpeg q82` 四条摆给用户挑
  339. (每条带一句描述、逐帧耗时、相对速度与推荐口径,见上文「确认点 5」与 `references/render-profiles.md` §0),
  340. 拍板后写进 `consent.json` 的 `render_channel`,跑 `gate_check.py --phase render` 放行
  341. → **顺带问一句快门覆盖面**:全片开,还是只点名那几场(`--shutter-only`)?
  342. (全片开 = 慢 ≈6.4×;片子只有几处运镜要拖影时**必须主动问**,别默认全片开)
  343. → 全片渲染 + qc_check
  344. 7. **QC**:qc_report.md 的 FAIL 清零 + qc_sheet.jpg 肉眼过(字幕带 80–170px 无内容、一焦点、光跟主角)→ 按组修复 → 重渲
  345. 8. **封面**:做 `frames/cover_169.html` + `cover_34.html`(独立排版;竖版投放再加 `cover_916.html`)
  346. → `node scripts/cover_build.mjs .` → **`node scripts/check_cover.mjs .`**(量终态几何,FAIL 清零)
  347. → 核对 `out/cover_report.md` + `references/cover-guide.md` 的自检清单
  348. 9. **交付**:mp4 + 封面(默认两张,竖版三张)+ srt/vtt(上传平台=可检索文本)+ 发布说明(硬字幕→关平台自动字幕;
  349. AI 配音→勾 AIGC;封面文字须与视频首帧钩子同义;受监管题材过合规)
  350. ## ★ 画面出错怎么定位(用户报「几分几秒」,agent 直接落到那一帧)
  351. 成片里发现画面问题(元素错位、被压住、少了东西、动效没走完)时,**不要重新描述场景内容、
  352. 不要从头翻 5000 帧**。流程固定成四步:
  353. 1. **用户只需要给「几分几秒」+ 一句现象。** 例:`1:23 右下角示意图里小黑点没在射线汇聚点上,偏左上`。
  354. `.github/ISSUE_TEMPLATE/bug_report.yml` 里有一栏专门收这个时间点。
  355. 2. **`frame_at.py` 把时间点翻译成定位信息**(一条命令,秒级):
  356. ```bash
  357. "$PY" <skill>/scripts/frame_at.py --project . --at 1:23
  358. "$PY" <skill>/scripts/frame_at.py --project . --at 1:23 --box 1400,200,1920,900 # 再裁一块可疑区
  359. "$PY" <skill>/scripts/frame_at.py --project . --list # 全片场景时间表
  360. ```
  361. 产出 `out/probe/`:**场景 id / 帧号 / 场景源文件 `frames/<id>.html` / 节拍文件 / 当刻字幕块
  362. (反查代码里的哪一句 `B('…')`)**,以及三张给视觉模型看的图 —— 整帧(1280 宽)、
  363. 底部 260px 禁区带(1:1)、**场景终态帧**。
  364. 3. **带视觉的模型看那几张图**(这是关键:只用文本描述「蓝点没在中间」定位不到,看图能直接
  365. 读出偏了多少、偏哪个方向、被谁压住)。先看**终态帧**,再看当刻帧。
  366. 4. **改 `frames/<id>.html` → 重跑 `check_layout.mjs`(几何)→ `lint_frames.py`(契约)→
  367. `render_video.mjs . --only <场景id>` 局部重渲** → 回到第 2 步复核同一时间点。
  368. ### 两条判据(省掉大量返工)
  369. - **先看终态,再看中途。** 中途帧的入场动画可能还没走完,元素位置**本来就该**和终态不同 ——
  370. 单看它分不清「代码错」还是「动画错」。**终态也错 = 布局本身错了;只有中途错 = 动画时序问题。**
  371. - **`--only <id>` 只对末场安全**(见 `lessons.md` #15):改短了必须删尾部过期帧,
  372. 且**渲染日志的 ✓ 不算证据** —— 用 `frame_at.py` 回到那个时间点看图确认。
  373. ## 场景契约速查(完整版 references/frame-contract.md)
  374. 八条:1920×1080 系统字体(禁外部字体)→ 颜色只取 theme.css 变量 → 动画只用 GSAP
  375. (`window.__tl` 注册,禁 CSS transition 入场;@keyframes 循环装饰可用,渲染器会 seek)→
  376. 节拍用 B() → 字幕带(80–170px)与进度条带(0–12px)不放内容 → 一场景一焦点
  377. (主角 ≥170px 或大字 ≥96px 带 accent 柔光,配角不发光,文字 ≥22px)→
  378. GSAP 用 `../assets/gsap.min.js`(本地内置)→ 主体动画压在 speech_end 前。
  379. ## 质量标尺
  380. - 画面:每帧一个焦点,主角带光;accent 只给当前重点;背景只有幕底+网格,无碎屑
  381. - **几何:`check_layout.mjs` ERROR 清零** —— 遮挡/越界是唯一一类「lint 全绿但仍然错」的问题
  382. (lint 只看文本规则)。**一个几何体只准有一个坐标系**:SVG 图元与 HTML 部件不得混用两套基准
  383. (issue #1「蓝点没落在射线汇聚点上」的根因,见 `references/frame-contract.md`)
  384. - 节拍:元素出现落在对应字幕块起始 ±0.2s 内(B() 天然保证);每句至少一处可察觉变化。
  385. **`check_beats_refs.py` 必须全绿** —— `B()` 是**前缀匹配**(text 必须是块文本的开头),
  386. 且抛错只在渲到那一帧时才发生(见 `references/lessons.md` #90)
  387. - 字幕:中文 ≤16 字/块、无标点、单帧硬切、每块 ≥0.6s;末块跟着语音消失。
  388. **小数点不算标点**(`2.4%` 上屏幕必须是 `2.4%`,削成 `24%` 是差一个数量级的假数字);
  389. `,` / `:` 照删。这条规则有五个出口,改动要一起动(见 `references/lessons.md` #88)
  390. - 底色:**用了亮底(浅色背景)就必须先给字幕层换肤** —— 渲染器注入的字幕/进度条默认是
  391. 「白字 + 黑描边」,白字落在米白纸面上等于看不见。主题文件里给亮底作用域补
  392. `--mg-sub-fg` / `--mg-sub-stroke` / `--mg-track` / `--mg-tick` 即可(见 `references/lessons.md` #75)。
  393. **它是渲染期产物 —— 改它 = 整片重渲,所以第一次全片渲染前先用 `--preview` 拿到
  394. 跨明暗切换的那几十秒。**
  395. **★ 亮底帧的 HTML 必须带 `<body class="paper">`**(`body.paper` 才会切字幕/进度条皮肤)。
  396. 派子 agent 写亮底帧时要把这条写进硬规矩并点名"同组的暗底帧不能加",交付后 `grep -n '<body' frames/*.html` 自查
  397. (见 `references/lessons.md` #94)
  398. - 事实:画面数字/术语/年份逐个对调研 URL;示例数据标「示意」。
  399. **★ 画面文字写的「口径名」必须与来源报告的口径名逐字一致** —— 二手转述会偷换统计主体
  400. (「网络视听 201 分钟」被写成「短视频 201 分钟」是造数)。**拿不到一手口径的数字,宁缺勿用**
  401. (见 `references/lessons.md` #95)
  402. - 时长:落在确认点 1 区间内;成片与音轨差 <0.5s(qc_check 把关)。
  403. **★ 解说词一次定稿**:数据/文案一改就要重跑 tts→timeline→subs,**全部 beats 的秒数一起位移**
  404. ——「时效刷新」是流水线的正式步骤,位置在 `tts_build` 之前(见 `references/lessons.md` #96)
  405. ## 关键文件
  406. **流水线脚本**(按执行顺序)
  407. | 路径 | 作用 |
  408. |---|---|
  409. | `scripts/new_project.py` | 阶段 0 脚手架:建目录树 + `project.json` + `narration.json` 占位 + `theme.css` + 两份封面 HTML(16:9 + 3:4;9:16 按投放需要自己加,注释里给了做法) |
  410. | `scripts/tts_setup.py` | **配音方案向导**:选 edge/火山 → 缺密钥则生成 `tts.env` 模板并停下 → 测连接 → 选音色 → 写回 project.json。输出 `NEXT_ACTION=…` 供 agent 判断下一步 |
  411. | `scripts/tts_volcano.py` | **火山引擎语音合成 2.0 接口包**:唯一读 `tts.env` 的地方;`--check` / `--voices` / `--synth`。密钥不回显、异常脱敏(`_redact`) |
  412. | `scripts/tts_build.py` | 配音合成:edge-tts **或** 火山引擎(`--provider`);缓存/硬超时/退避重试/裁静音,manifest 写两级时长。两引擎 manifest 结构一致 |
  413. | `scripts/timeline_build.py` | layout.json 全局轴 + narration-full.mp3(gap 显式插入) |
  414. | `scripts/subs.py` | 字幕三出口(subs.json / srt+vtt / 画面内层由渲染器注入)+ beats.js 节拍器 |
  415. | `scripts/check_beats_refs.py` | **节拍引用构建期校验**:把每帧的 `B()`/`Be()` 全抓出来和自己的 beats 表对一遍。**`B()` 是前缀匹配**(`bt===t ‖ bt.startsWith(t) ‖ t.startsWith(bt)`,归一化不去 `《》「」`),取中间一段会抛错 —— 而那个错**只在渲到那一帧时才炸**(前面几百帧白渲)。本脚本把它提前到构建期:失配打印**该帧可用块列表**,退出码 1,秒级 |
  416. | `scripts/style_director.py` | ★ **v2.0 主题驱动风格编排**:读 `narration.json` 推断每场角色(开场/陈述/数据/原理/例证/反差/收束/落版),按角色×子类别×时长×内容词打分挑**主风格**,按能量预算给部分场搭**次风格**(局部替换),决定**开场变体**、**场间转场**、**动效强度**,并施加多样性约束(风格数上限/连续同风格上限/开场≠第二场)。产物 `style-plan.json` 的 `why` 字段逐条可解释 |
  417. | `scripts/lint_frames.py` | **渲染前静态体检**:八条契约违规逐条报(外链字体/色值字面量/墙钟/`B()\|\|N`/字幕带压内容/缺中文字体族…)—— 只看**文本规则**,看不见几何 |
  418. | `scripts/check_layout.mjs` | **渲染前几何体检**(终态):侵入字幕禁区 / 出画 / 文字被遮挡 / 文字重叠 = ERROR;越安全边 / 文字压色块 / 色块重叠 = WARN;疑似未对齐 = INFO。量的是**字墨范围**(Range 逐行)而非元素框。`--only` / `--json` / `--safe-bottom`;有 ERROR 退出码 1 |
  419. | `scripts/render_video.mjs` | 渲染器:浏览器探测 → 逐场景 seek 截图 →(可选快门运动模糊积分)→ ffmpeg 合成;`--preview N` 快样片,`--only <场景id>` 只重渲指定场景(**仅末场安全**,变短后须清尾部过期帧,见 lessons 45),`--mux-only` 用现有帧重新合成;**帧里有满幅照片就必须换截图模式**(默认 PNG 编码占 96% 帧时间且与并发无关):`--png-fast` 无损 4.4×,`--jpeg --jpeg-quality 95` 13×;`--crf N` / `--preset <名>` 单独控制成片码率。**v2.0 新增**:`--profile` 成套档位、`--quality`×`--fps` 自由组合、`--shutter` 快门运动模糊、`--workers` 多浏览器进程级并行、`--resume` 断点续渲、`--recycle` 定期重启浏览器。**v2.0.2/.3 新增**:`--shutter-flush` 快门样本磁盘护栏(防峰值堆到数十 GB)、`--shutter-only <id,id>` 场景级快门白名单、`--motion-hold <px>` 位移闸门(配合帧导出的 `window.__motion`)。**v2.0.6 修复**:路径 A(精细 PNG 单浏览器)的看门狗改为**逐帧打点**(此前量的是「单场耗时」,>105s 的场必被误杀);`--resume` 在路径 A 真正生效(此前加了不报错也不跳帧 = 静默 no-op,而看门狗挂死提示恰恰叫人用它) |
  420. | `scripts/blur_integrate.py` | **快门运动模糊积分器**(渲染管线第 2 段):把 Node 侧抓到的 K 张快门样本在**线性光**下逐像素平均 —— 真的积分,不是 blur 滤镜。多进程并行、天然支持断点续渲 |
  421. | `scripts/bench_render.py` | **渲染管线基准工装**:合成复杂度可控的项目 → 同机多档位各渲一遍 → 拉出「截图耗时/fps/体积」对比表(优化前后同表对比) |
  422. | `scripts/qc_check.py` | 流/时长/音量/抽帧体检 + contact sheet |
  423. | `scripts/cover_build.mjs` | 封面渲染器:`169`(1920×1080) / `34`(1440×1080) / `916`(1080×1920) 各一份独立排版 → 2 倍图;`--at` / `--only` / `--jpg`;**缺哪张就跳哪张** |
  424. | `scripts/check_cover.mjs` | **封面终态几何实测器**:边距 / 钩子字号 / 钩子是否最大文字 / 行宽 / 孤字断行 / **文字重叠(量字墨,不量行框)** / 9:16 禁左右两栏 / 越界;`--only` / `--json` / `--shot`;退出码 0/1 |
  425. **辅助工具**
  426. | 路径 | 作用 |
  427. |---|---|
  428. | `scripts/peek_frame.mjs` | 单帧速览:不渲全片,秒级截某场景的几个时点看图。**`--at-sec 3.5,12` 按绝对秒定位(推荐,自动读轴长换算)**;`--at` 是相对整条时间轴的百分比(轴长会被尾段防冻层拉长,容易算错);`--guides` 叠十字中线 + 字幕禁区线(**判「元素有没有对齐」必须开**,没有基准线肉眼判不了) |
  429. | `scripts/frame_at.py` | **时间点 → 定位**:报「几分几秒」就能拿到场景 id / 帧号 / 源文件 / 当刻字幕块 / 整帧图 / 底部禁区带裁图 / **场景终态帧**(`--at 1:23` / `--list` / `--box x0,y0,x1,y1` / `--final`)。画面排障的入口工具 |
  430. | `scripts/check_integrity.py` | 仓库自洽性:版本号/风格目录/计数一致性 + 模板外链扫描(CI 与本地都跑) |
  431. | `scripts/make_theme.py` | 4 预设 + 主题词推色 → theme.css(CSS 变量单源) |
  432. | `scripts/import_styles.py` | (移植期一次性工具)把已装 html-video 的设计规范抄成纯文本风格目录;**跑视频永不需要它** |
  433. | `tests/geometry-fixture/` | **几何体检的证伪样本**:故意坏掉的帧(越界 + 遮挡 + 错位),期望 ERROR 2 / WARN 0 / INFO 1。改 `check_layout.mjs` 后先拿它验「还抓得到错」,再拿真实项目验「误报没变多」 |
  434. | `setup_env.sh` | 环境自检 / `--install` 联网装缺项 |
  435. | `package_skill.py` | 打成可移植 zip(`--with-deps` 含 node_modules) |
  436. **参考文档与资源**
  437. | 路径 | 作用 |
  438. |---|---|
  439. | `references/style-catalog.md` | **23 个画面风格目录**(画布/字体/时间轴/配色纪律 + rich/gsap 分类)——纯知识,非代码依赖 |
  440. | `references/style-catalog.json` | 同上的机器可读版(`kf`/`multi`/`engine` 字段用于自动判类型) |
  441. | `references/template-guide.md` | 模板改编指南(rich 三步法 / gsap 重写法 / 挑风格建议) |
  442. | `references/frame-contract.md` | 契约细则 + 版式基因 + 反例 |
  443. | `references/cover-guide.md` | **封面详规**:一张还是几张 / 各画幅排版纪律 / 重排对照表 / 三要素 / 尺寸倍率 / 上传策略 / 自检清单 |
  444. | `references/workflow-guide.md` | 阶段详解 + agent prompt 模板 + 时长档位表 |
  445. | `references/motion-library.md` | ★ **v2.0 动效库文档**:40+ 动作词汇(enter/carry/contact/camera/ambience 五组)、曲线表、场景契约、完整示例、六条纪律 |
  446. | `references/style-director.md` | ★ **v2.0 模板编排文档**:八种角色、打分维度、混用与局部替换、多样性约束、`style-plan.json` 结构、命令行 |
  447. | `references/render-profiles.md` | ★ **v2.0 画质/帧率档位与性能文档**:档位表、质量-速度-体积权衡、快门与并行原理、基准数据、4K60 硬件要求 |
  448. | `references/lessons.md` | 踩坑台账(继承 14 条 + 本技能记录,持续追加) |
  449. | `assets/frame-template.html` | 场景模板(契约注释在文件头,B() 用法示例) |
  450. | `assets/cover-template.html` | **封面模板**(封面三要素注释在文件头,可改尺寸复用为 16:9 / 3:4 / 9:16 各一份) |
  451. | `assets/gsap.min.js` | GSAP 3.13 本地内置(离线渲染;License 见同目录 `gsap-README.md`) |
  452. | `assets/motion.js` | ★ **v2.0 动效库**(40+ 动作词汇)。浏览器挂 `window.HXM`,Node 可 `require` 跑自测。无依赖、无构建、纯函数(可逐帧 seek) |
  453. | `README.md` / `README.en.md` | 对外项目说明(**README.md 中文为默认**,`README.en.md` 英文;含跨 Agent 安装指引) |
  454. | `CONTRIBUTING.md` | 贡献指南:硬性规则、端到端自检、PR 清单 |
  455. | `CHANGELOG.md` | 版本变更史 |
  456. | `THIRD_PARTY_NOTICES.md` | 第三方组件与衍生内容的授权声明(**发布前必读**) |
  457. ## 跨 Agent 安装
  458. 本技能遵循 [Agent Skills](https://code.claude.com/docs/en/skills) 约定(`SKILL.md` +
  459. `scripts/` + `references/` + `assets/`),**不绑定任何单一智能体平台**。仓库根目录**就是**
  460. 技能目录,所以 clone 到下表任一路径即可直接生效,不需要再拷子目录。
  461. | 智能体 | 个人级(全局) | 项目级(仓库内) |
  462. |---|---|---|
  463. | WorkBuddy | `~/.workbuddy/skills/` | `<工作区>/.workbuddy/skills/` |
  464. | Claude Code | `~/.claude/skills/` | `.claude/skills/` |
  465. | OpenAI Codex | `~/.codex/skills/` | `.codex/skills/` 或 `.agents/skills/` |
  466. | Gemini CLI | `~/.gemini/skills/` | `.gemini/skills/` 或 `.agents/skills/` |
  467. | Cursor | `~/.cursor/skills/` | `.cursor/skills/` |
  468. | GitHub Copilot / VS Code | `~/.copilot/skills/` | `.github/skills/` |
  469. | OpenCode | `~/.config/opencode/skills/` | `.opencode/skills/` |
  470. | Windsurf | `~/.windsurf/skills/` | `.windsurf/skills/` |
  471. | 通用约定 | `~/.agents/skills/` | `.agents/skills/` |
  472. 手动安装(把 `~/.claude` 换成你所用智能体的目录):
  473. ```bash
  474. git clone https://github.com/OneMoh/html-explainer.git ~/.claude/skills/html-explainer
  475. bash ~/.claude/skills/html-explainer/setup_env.sh --install
  476. ```
  477. 也可以直接把这句话交给智能体,让它自己装:
  478. > 给当前本地环境安装该 Skill:https://github.com/OneMoh/html-explainer.git
  479. > 安装到你的技能目录,并检测安装必要的运行环境(Python 3.9+ / Node 18+ / Chrome 或 Edge / ffmpeg)
  480. 装完**新开一个会话**,让智能体重新扫描技能目录。同理,调用本技能时应把
  481. `<SKILL_ROOT>` 替换成实际安装路径 —— 派子 agent 时要展开成**绝对路径**写进 prompt。
  482. ## 打包移植
  483. 技能目录自包含,不引用本机任何绝对路径(脚本按自身位置定位 `SKILL_ROOT`)。
  484. 仅有两处**兜底探测**会去探 WorkBuddy 托管的运行时目录(`setup_env.sh` 的 Python/Node
  485. 候选、`peek_frame.mjs` 的技能根候选)—— 探不到就自动跳过,不影响其它平台。
  486. **零依赖声明(重要)**:本技能**不需要** html-video 或 anything2explainer 存在。
  487. 两个来源项目的名字只出现在:① 代码注释的出处署名 ② `scripts/import_styles.py`
  488. 这个**移植期一次性工具**的用法说明里。跑一条视频(tts → timeline → subs → render →
  489. qc → cover)**完全不碰这两个项目**。风格库是抄成纯文本的设计规范
  490. (`references/style-catalog.md`),已随技能打包。
  491. ```bash
  492. # ① 打包(默认不含 node_modules,只有 ~110KB)
  493. python package_skill.py # → dist/html-explainer-v<版本>.zip
  494. python package_skill.py --with-deps # 含 playwright-core,~14MB(目标机全程离线)
  495. # ② 新机器:解压到任意目录(放进上表任一「个人级」技能目录即可被该智能体识别)
  496. bash setup_env.sh --install # 自检 + 装缺项(先装后判定,装成功即算就绪)
  497. # ③ 跑一遍端到端(可选,验证链路)
  498. python scripts/new_project.py demo --topic "人工智能"
  499. # …填 narration.json / 写 frames/*.html / 填 project.json.order…
  500. python scripts/tts_build.py --project . && python scripts/timeline_build.py --project .
  501. python scripts/subs.py --project . && python scripts/style_director.py --project .
  502. node scripts/render_video.mjs . --profile balanced --audio audio/narration-full.mp3
  503. python scripts/qc_check.py --project . && node scripts/cover_build.mjs .
  504. ```
  505. **v2.0 提速自检**:跑一次基准,确认本机各档位速度符合预期(不需要素材):
  506. ```bash
  507. python scripts/bench_render.py --out .scratch/bench --scenes 6 --sec 2.0 --fps 30 \
  508. --configs legacy,draft,balanced --preview 6
  509. ```
  510. **依赖探测顺序**(都尽量用系统已有的,避免下载):
  511. - Python:先找 WorkBuddy 托管 venv,再 `python3` / `python`
  512. - Node:`node -v` ≥18;没有则扫 `~/.workbuddy/binaries/node/versions/*`(WorkBuddy 托管路径)
  513. - 浏览器:Chrome → Edge → playwright chromium → `BROWSER_PATH` 环境变量
  514. - ffmpeg:PATH → `imageio_ffmpeg.get_ffmpeg_exe()`(pip 装依赖时自带静态二进制)
  515. - GSAP:包内 `assets/gsap.min.js`(离线,不外链)
  516. 已验证:把 zip 解压到干净目录、只跑 `setup_env.sh --install`,**全链路输出与原目录逐帧一致**
  517. (同 346 帧、同抽帧体积、同音画差 0.05s)。
  518. ## 许可与致谢
  519. - 本技能**原创代码与文档**:MIT © 2026 **Moh**(见 `LICENSE`)。
  520. - **画面风格目录**(`references/style-catalog.md` / `.json`)由 [nexu-io/html-video](https://github.com/nexu-io/html-video)
  521. (Apache-2.0)的模板设计规范转写而来,已保留署名;转写文本按 Apache-2.0 分发。
  522. - **方法论思路来源**:[Vincentwei1021/anything2explainer](https://github.com/Vincentwei1021/anything2explainer)
  523. (词边界字幕 / 两级时钟 / 语速标定 / QC 判据)。两者均为**他人独立项目,与本技能不是同一作者**。
  524. 确定性 seek 渲染器、`B()` 节拍锚定、多画幅独立排版封面(16:9 / 3:4 / 9:16)为本项目原创。
  525. - **打包内置**:GSAP 3.13(GreenSock 标准「no charge」许可,见 `assets/gsap-README.md`)、
  526. playwright-core(Apache-2.0)。
  527. - 完整清单与逐条授权见 **`THIRD_PARTY_NOTICES.md`**。发布/再分发前请连同该文件一起带上。
README.md · README · 330 lines
  1. <div align="center">
  2. # html-explainer
  3. **一个 Agent Skill:给任意主题,产出一条带配音、硬字幕、封面的讲解视频。**
  4. **不需要视频生成模型。** 画面是 agent 现写的 HTML/CSS,确定性逐帧渲染成**真 MP4**(不是录屏):
  5. 动效库是 `t → 数字` 的纯函数,可任意 seek;风格由主题编排;渲染支持 **4K60 · 180° 快门运动模糊 · 多进程并行**。
  6. **全本地跑,核心链路零 API key、零按次计费。**
  7. 一条 **2 分钟的片子,全流程最快约 30 分钟**(调研 → 解说词 → 配音字幕 → 写画面 → 渲染 → 封面)。
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  9. [![Version](https://img.shields.io/badge/version-2.0.10-blue.svg)](CHANGELOG.md)
  10. [![Stars](https://img.shields.io/github/stars/OneMoh/html-explainer?style=flat&logo=github)](https://github.com/OneMoh/html-explainer/stargazers)
  11. [![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-8A2BE2.svg)](SKILL.md)
  12. [![Claude Code](https://img.shields.io/badge/Claude%20Code-%E2%9C%93-D97757.svg)](#安装)
  13. [![Codex](https://img.shields.io/badge/Codex-%E2%9C%93-000000.svg)](#安装)
  14. [![WorkBuddy](https://img.shields.io/badge/WorkBuddy-%E2%9C%93-1f6feb.svg)](#安装)
  15. [![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB.svg?logo=python&logoColor=white)](#环境要求)
  16. [![Node](https://img.shields.io/badge/Node-18%2B-339933.svg?logo=node.js&logoColor=white)](#环境要求)
  17. [简体中文](README.md) · [English](README.en.md)
  18. <br/>
  19. 两条用本技能生成的成片——画面、配音、字幕、封面全部由流水线产出,无手工后期。
  20. 封面等素材托管在[演示仓库](https://github.com/OneMoh/html-explainer-demos),本仓库零体积。
  21. | 港股创新药 · 早盘 | 量化简史 |
  22. |---|---|
  23. | https://github.com/user-attachments/assets/8007843c-088d-457c-8550-81ec912e0add | https://github.com/user-attachments/assets/28949988-449b-4c4e-8d0f-6706af6f64ee |
  24. </div>
  25. ---
  26. ## 它是什么
  27. `html-explainer` 把一个主题做成**带配音、带硬字幕、带进度条**的讲解视频,画面用
  28. HTML/CSS/GSAP 写。
  29. 它**是一个 Agent Skill**(`SKILL.md` + `scripts/` + `references/`),遵循
  30. [Agent Skills](https://code.claude.com/docs/en/skills) 约定,Claude Code / OpenAI Codex /
  31. WorkBuddy / Cursor / Gemini CLI 等都能直接加载。内部是普通的 Python 与 Node 脚本,
  32. 手工跑也完全没问题。
  33. 你只需要说一句:
  34. > 把「为什么天空是蓝色的」做成一条 1 分钟的讲解视频。
  35. 技能会带着智能体走完:调研 → 解说词 → 配音 → 字幕与节拍 → **编排风格并写画面** → 渲染 → 体检 → 封面。
  36. **与「文生视频」模型的区别**:那条路线要模型把画面像素生成出来,代价是算力、按次计费、
  37. 以及不可复现的文字(画面上的中文经常是糊的)。这里要模型**写代码**,像素由浏览器画 ——
  38. 所以文字永远清晰、同一帧永远长一样,画面是一份可读的文件,能改也能 diff。
  39. ## 30 分钟是怎么来的
  40. 一条 2 分钟的片子约 3600 帧(1080p30)。最快档的典型耗时:
  41. | 阶段 | 约 | 说明 |
  42. |---|---|---|
  43. | 调研 + 解说词 | 14 分钟 | 每个数字带出处;解说词按 `\|` 切成字幕块 |
  44. | 配音 + 字幕 + 时间轴 | 2 分钟 | edge-tts 免费免密钥;词级时间戳直接出硬字幕 |
  45. | 写画面 | 8 分钟 | 从 23 个风格里挑、用动效库拼;一句一场景 |
  46. | 渲染 | 4 分钟 | 1080p30 实测 **16.4 帧/秒**,3600 帧 ≈ 3.7 分钟 |
  47. | 封面 + 体检 | 2 分钟 | 16:9 与 3:4 各排一次版,几何实测把关 |
  48. > 量级参考,不是承诺:真正吃时间的是「调研深度」和「画面迭代次数」。渲染这一环很便宜 ——
  49. > 一条 5982 帧的真实片子端到端 7 分 49 秒,**换 4K60 才是数倍代价**(见[渲染实测](DESIGN.md#渲染性能实测))。
  50. ---
  51. ## 安装
  52. ### 一句话安装(推荐)
  53. 把下面这句发给你的智能体:
  54. ```text
  55. 给当前本地环境安装该 Skill:https://github.com/OneMoh/html-explainer.git
  56. 安装到你的技能目录,并检测安装必要的运行环境(Python 3.9+ / Node 18+ / Chrome 或 Edge / ffmpeg)
  57. ```
  58. 它会自己 clone 到对应目录、跑环境自检、把缺的东西装上。装完**新开一个会话**,让智能体重新
  59. 扫描技能目录。
  60. ### 手动安装
  61. 仓库根目录**就是**技能目录(`SKILL.md` 在根),直接 clone 进技能目录即可,不用再拷子目录:
  62. ```bash
  63. git clone https://github.com/OneMoh/html-explainer.git ~/.workbuddy/skills/html-explainer
  64. bash ~/.workbuddy/skills/html-explainer/setup_env.sh --install
  65. ```
  66. Windows 上 `~` 就是 `C:\Users\<你的用户名>`。
  67. > **Windows 注意**:上面的 `bash` 指 **Git Bash**(装了 Git for Windows 就有),PowerShell / cmd
  68. > 里直接跑 `bash setup_env.sh --install` 会找不到命令 —— 用 `& "C:\Program Files\Git\bin\bash.exe" setup_env.sh --install`,
  69. > 或先开一个 Git Bash 窗口。
  70. > 另外,不少宿主会在技能目录名后加命名空间后缀(例如 WorkBuddy 装出来的是
  71. > `~/.workbuddy/skills/html-explainer__skillhub`),照实际目录改路径即可,技能本身不认名字。
  72. > 项目路径请保持**全 ASCII** —— Windows 的 ffmpeg 把 UTF-8 当 ANSI 读,中文路径会在渲染阶段炸。
  73. ### 环境要求
  74. | 项 | 最低 | 说明 |
  75. |---|---|---|
  76. | Python | 3.9+ | `edge-tts==7.3.1`(刻意钉死;7.2.8 握手已被微软 403)、`numpy`、`pillow`、`imageio-ffmpeg`;火山引擎**零额外依赖**(只用标准库 `urllib`) |
  77. | Node.js | 18+ | 渲染器与封面器用 |
  78. | 浏览器 | Chrome 或 Edge | 自动探测;都没有才下载 playwright chromium(约 115MB,只需一次) |
  79. | ffmpeg | 任意版本 | 先在 `PATH` 找;没有则用 `imageio-ffmpeg` 自带的静态二进制 |
  80. | 磁盘 | 每条成片约 2GB | 帧 PNG 体积大,合成后可删 |
  81. `bash setup_env.sh` 只检查并报告缺什么,`--install` 才会装。全程不需要管理员权限。
  82. **没有 GPU 要求,没有模型权重要下载** —— 依赖就是上面这几样。
  83. ---
  84. ## 核心特性
  85. | | |
  86. |---|---|
  87. | **不需要视频模型** | 画面是 HTML/CSS/GSAP,浏览器逐帧渲染。零 API key、零按次计费、可离线 |
  88. | **节拍锚定解说词** | 动画按**字幕文本**定位(`B('块文本')`),不硬编码帧号。改解说词,全片自动重排,画面代码零改动 |
  89. | **词边界字幕** | 时序来自 TTS 的**字级时间戳**,不按字数插值 —— 中文里同字数的短语时长能差 3 倍 |
  90. | **两个配音引擎** | `edge-tts`(免费免密钥,默认)或**火山引擎语音合成 2.0**(音质更好)。manifest 结构一致,下游零改动 |
  91. | **23 种画面风格** | 8 个类别,每种都记录了画布、字阶、时间轴与配色纪律。不用对着空白页从零设计 |
  92. | **动效库(40+ 动作词汇)** | `assets/motion.js`:入场 / 承接 / 接触 / 运镜 / 环境五组,全是「`t` → 一组数字」的纯函数,天生可 seek |
  93. | **主题驱动模板编排** | `style_director.py` 读解说词推断每场角色,挑主风格 + 搭次风格 + 决定开场与转场。**不是「一片一模板」** |
  94. | **4K60 + 快门运动模糊** | `--profile` 四档;快门在**线性光下做多样本积分**(不是 blur 滤镜);`--workers N` 多进程并行、`--resume` 断点续渲 |
  95. | **多画幅封面** | 16:9 与**独立重排**的 3:4(不是裁切 —— 裁切会丢掉 57.8% 的画面宽度),竖版再加 9:16 |
  96. | **三道渲染前体检** | `check_beats_refs.py`(`B()` 能否解析)、`lint_frames.py`(八条契约)、`check_layout.mjs`(越界 / 侵入字幕带 / 遮挡) |
  97. | **结构性离线** | GSAP 内置;浏览器自动探测;ffmpeg 缺失回退静态二进制;网络字体被契约禁止 |
  98. > 原理(为什么不用录屏、动效库怎么设计、封面怎么重排)单独成篇 → [**DESIGN.md**](DESIGN.md)。
  99. ---
  100. ## 流水线
  101. ```mermaid
  102. flowchart LR
  103. A["主题"] --> B["调研<br/><i>每个数字带出处</i>"]
  104. B --> C["narration.json<br/><i>竖线切字幕块</i>"]
  105. C --> S["tts_setup.py<br/><i>问 TTS 方案 · 配密钥 · 选音色</i>"]
  106. S --> D["tts_build.py<br/><i>edge-tts / 火山引擎 → MP3 + 词边界</i>"]
  107. D --> E["timeline_build.py<br/><i>全局轴 + 拼接音轨</i>"]
  108. E --> F["subs.py<br/><i>subs.json · srt/vtt · beats.js</i>"]
  109. F --> CB["check_beats_refs.py<br/><i>B()/Be() 能否解析</i>"]
  110. CB --> SD["style_director.py<br/><i>读解说词挑风格 → style-plan.json</i>"]
  111. SD --> G["frames/*.html<br/><i>一句一场景 · 动效库 HXM</i>"]
  112. G --> H{"lint_frames.py<br/>八条契约"}
  113. H -->|不过| G
  114. H -->|通过| CL["check_layout.mjs<br/><i>几何:越界 · 侵入字幕带 · 遮挡</i>"]
  115. CL --> GC{"gate_check.py<br/>通道已由用户拍板?"}
  116. GC -->|未定| Q["问用户选通道"]
  117. Q --> GC
  118. GC -->|已定| I["render_video.mjs<br/><i>逐帧 seek → png-fast / jpeg</i>"]
  119. I --> J["ffmpeg<br/><i>H.264 + AAC 合成</i>"]
  120. J --> K[("out/slug.mp4")]
  121. I --> L["qc_check.py<br/><i>响度 · 漂移 · 抽帧速览</i>"]
  122. K --> M["cover_build.mjs<br/><i>cover_169.png · cover_34.png · cover_916.png</i>"]
  123. M --> N["check_cover.mjs<br/><i>终态几何实测</i>"]
  124. style K fill:#1f6feb,color:#fff
  125. style H fill:#8957e5,color:#fff
  126. style CL fill:#8957e5,color:#fff
  127. style GC fill:#8957e5,color:#fff
  128. style SD fill:#bf8700,color:#fff
  129. style CB fill:#6e7781,color:#fff
  130. style M fill:#238636,color:#fff
  131. style N fill:#238636,color:#fff
  132. ```
  133. 完整命令序列(含每个脚本的参数)见 [`SKILL.md`](SKILL.md) 的「命令流水线」。
  134. ---
  135. ## 两个要你拍板的决定
  136. 智能体不会替你选这两件事 —— 选择被写进 `consent.json`,`gate_check.py` 挡在渲染之前。
  137. ### 1. 配音引擎
  138. | | `edge-tts` | 火山引擎语音合成 2.0 |
  139. |---|---|---|
  140. | 你要做什么 | 什么都不用做 | 填一次 API Key |
  141. | 费用 | 免费 | 按字符计费 |
  142. | 音色 | 内置中英文若干 | 豆包 2.0 音色库,含声音复刻 |
  143. | 额外依赖 | `edge-tts==7.3.1`、`imageio-ffmpeg` | **零** —— 只用标准库 `urllib` |
  144. | 什么时候选它 | 默认。开箱可用、够用 | 想要更自然的语气与更好音质 |
  145. 选火山时,技能会生成 `tts.env` 并**停下来**让你把 Key 填进去 —— 这一步刻意不经过对话窗口:
  146. 密钥不发给智能体、不进对话、不进仓库、不进日志。音色清单与密钥纪律的完整说明见
  147. [`DESIGN.md`](DESIGN.md#配音细节)。
  148. ### 2. 渲染档位与中间帧通道
  149. ```bash
  150. node <skill>/scripts/render_video.mjs . --list-profiles # 看全部档位
  151. ```
  152. | 档位 | 画质 | 帧率 | 快门 | 中间帧 | 用途 |
  153. |---|---|---|---|---|---|
  154. | `draft` | 1080p | 30 | 关 | `png-fast` | 打样 / 迭代,最快 |
  155. | `balanced` | 1080p | 30 | 180° | `png-fast` | **默认推荐**(质量/速度平衡) |
  156. | `final` | 4K | 60 | 180° | `png-fast` | 终稿(工作量约 1080p30 的 8–12×) |
  157. | `master` | 4K | 60 | 180° | 精细 PNG | 极限画质(很慢) |
  158. | `legacy` | 1080p | 项目 fps | 关 | 精细 PNG | 逐位复现 v1.4.x 旧成片 |
  159. 中间帧通道四条,**渲染前必须问你选哪条**:
  160. | 通道 | 定位 |
  161. |---|---|
  162. | **`--png-fast`** ★默认 | 逐像素无损;纯 CSS/MG 图形帧上与 JPEG q95 同速、体积更小 |
  163. | `--jpeg --jpeg-quality 95` | **含满幅照片 / 4K 终稿**时首选(照片帧上精细 PNG 是 582ms/帧的黑洞) |
  164. | `--png` | 只有 `legacy` 复现 / `master` 极限档用 |
  165. | `--jpeg --jpeg-quality 82` | 只做打样预览 |
  166. 档位只改 `deviceScaleFactor`,**布局逐像素不变**。速度实测、快门积分原理与完整参数见
  167. [`references/render-profiles.md`](references/render-profiles.md)。
  168. ---
  169. ## 视频项目结构
  170. 产物落在 `out/`:`slug.mp4`、`cover_169.png`、`cover_34.png`、`slug.srt`、`slug.vtt`,
  171. 外加 `qc_report.md` 与 `qc_sheet.jpg`;做竖版投放时再加一张 `cover_916.png`。
  172. ```
  173. my-video/
  174. ├── project.json # slug、fps、尺寸、音色、语速、场景顺序、章节
  175. ├── narration.json # [{ id, text }] —— 用 "|" 切字幕块
  176. ├── theme.css # 所有颜色,以 CSS 变量形式
  177. ├── style-plan.json # 每场的主/次风格、角色、转场、动效强度(编排器产出)
  178. ├── consent.json # 六个确认点(含渲染通道)由用户拍板才放行
  179. ├── frames/ # 一个场景一个 HTML;<id>.beats.js 自动生成,绝不手改
  180. ├── audio/ render/ research/ script/
  181. └── out/ # MP4、封面、SRT/VTT、QC 报告
  182. ```
  183. ---
  184. ## 疑难排查
  185. | 症状 | 原因 | 处理 |
  186. |---|---|---|
  187. | 每一帧都是静止首帧,且不报错 | 时间轴没注册到 `window.__tl`;或 `page.evaluate` 传了**字符串**而非函数字面量(Playwright 只求值一次,函数体根本不执行) | 传真正的函数字面量 |
  188. | 视频变成 1280×720 | `viewport` 传给了 `browser.launch()` —— 它是 *context* 级选项 | 传给 `newPage()` |
  189. | 封面出成 1 倍图 | 同上,`deviceScaleFactor` 的孪生坑 | 传 `newPage()` + `screenshot({ scale: 'device' })` |
  190. | 数字能渲染但永远不动 | seek 抑制了 `onUpdate` 回调 | 渲染器已修(`pause(t, false)`);帧里改用 transform 数字卷轴 |
  191. | `--jpeg` 通道下 ffmpeg 首帧即崩(`unsupported coding type`) | 「hold 帧」被写成「后缀 `.jpg`、内容 PNG」的脏帧 | 升级到 v2.0.4 或更高(该版本已修) |
  192. | 日志打了「浏览器:…」却仍报 `Executable doesn't exist at …ms-playwright…` | v2.0.9 及之前只探测到系统浏览器、没把路径传给 `chromium.launch()` | 升级到 v2.0.10(已接上 `executablePath`);临时可用 `--browser <path>` 或 `BROWSER_PATH` |
  193. | TTS 报 `WSServerHandshakeError: 403 Forbidden`(微软端点) | edge-tts 7.2.8 的握手已被微软拒绝,与网络无关 | 升级到 v2.0.10 后跑 `bash setup_env.sh --install`(pin 已提到 7.3.1),或手动 `pip install -U edge-tts==7.3.1` |
  194. | Windows 上 `No such file or directory` | 非 ASCII 路径 —— Windows 的 ffmpeg 把 UTF-8 当 ANSI 读 | 路径保持 ASCII |
  195. | 字幕开始飘 / 位置对不上 | TTS 没返回字级时间戳,`subs.py` 退回**按字数插值** | 看 `tts_build` 有没有打 `⚠ 未返回字级时间戳`;换个受支持的音色(中英文 2.0) |
  196. | 火山报 `resource ID is mismatched with speaker related resource` | `speaker` 收到了中文显示名而不是音色 ID;或复刻音色配了预置资源 ID | 音色用内置名/ID(接口包会解析);复刻音色配 `VOLC_RESOURCE_ID=seed-icl-2.0` |
  197. | 火山报 `HTTP 401/403` | `tts.env` 里的 key 不对,或该服务未开通 | 核对 `VOLC_API_KEY`;`tts_setup.py --status` 看脱敏状态 |
  198. | 火山报 `网络不可达` | 本包默认**绕过系统代理直连**(境内端点) | 确实需要代理时设 `VOLC_PROXY=http://127.0.0.1:<port>` |
  199. | 重跑后字幕整体晚一帧 | 命中缓存时丢掉了首裁量(历史 bug,已修) | 升级到 v1.3.0+;缓存格式已带 `lead_cut_sec` |
  200. **先读 [`references/lessons.md`](references/lessons.md) 再 debug。** 133 条编号记录,每一条都是
  201. 「成片看着挺正常、其实是错的」的 bug —— 包括它一开始是怎么被误判的。
  202. ---
  203. ## 深入阅读
  204. | 想看什么 | 去哪里 |
  205. |---|---|
  206. | **原理**:为什么不用录屏、seek 怎么保证逐像素一致 | [`DESIGN.md`](DESIGN.md#渲染原理为什么不用录屏) |
  207. | **`B()` 节拍系统**:为什么改一句词不用重新对位 | [`DESIGN.md`](DESIGN.md#b-节拍系统) |
  208. | **23 个风格**的画布 / 字阶 / 时间轴规范 | [`references/style-catalog.md`](references/style-catalog.md) |
  209. | **动效库** 40+ 动作词汇与分层设计 | [`DESIGN.md`](DESIGN.md#动效库) · [`references/motion-library.md`](references/motion-library.md) |
  210. | **模板编排**怎么挑风格、怎么混用 | [`references/style-director.md`](references/style-director.md) |
  211. | **封面**三画幅的重排规则与自检清单 | [`DESIGN.md`](DESIGN.md#封面多画幅) · [`references/cover-guide.md`](references/cover-guide.md) |
  212. | **渲染**档位、快门积分、性能实测 | [`DESIGN.md`](DESIGN.md#渲染性能实测) · [`references/render-profiles.md`](references/render-profiles.md) |
  213. | 完整命令序列与确认点 | [`SKILL.md`](SKILL.md) |
  214. | 踩过的坑(133 条) | [`references/lessons.md`](references/lessons.md) |
  215. | 版本变更 | [`CHANGELOG.md`](CHANGELOG.md) |
  216. ---
  217. ## 适合谁
  218. **适合**:想成规模地把文章 / 文档 / 某个主题做成带解说的视频;已经在用 AI 编程智能体,
  219. 且宁愿用 HTML 描述画面也不想学动效软件;需要可复现的输出;需要离线跑或拒绝按次计费。
  220. **不适合**:实拍剪辑、真人口播、复刻已有视频;想要图形化拖拽编辑器(画面是代码,这是刻意
  221. 选择);想用文生视频模型「一句话出片」(本项目要模型写代码,不生成像素)。
  222. ---
  223. ## 参与贡献
  224. 欢迎提 issue 和 PR。最有价值的贡献,是一条**已被定位的静默失败**,加进
  225. `references/lessons.md` —— 写下它一开始是怎么误导你的、证明病因的证据、修法,以及由此得出的
  226. 通用规则。请先读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
  227. ## 许可与致谢
  228. [MIT](LICENSE) © 2026 Moh
  229. MIT 覆盖原创代码与文档。第三方组件与衍生出的风格规范仍适用其各自的条款;GSAP 按 GreenSock
  230. 的 [standard "no charge" 许可](https://gsap.com/standard-license) 内置。本项目的方法论有两处
  231. 明确的思想来源(`anything2explainer` 与 `html-video`),**不打包、运行时不依赖它们的任何代码** ——
  232. 完整的署名与逐风格对应关系见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md),
  233. 叙事版见 [`DESIGN.md`](DESIGN.md#思想来源)。
  234. ---
  235. ## Star 曲线
  236. <a href="https://star-history.com/#OneMoh/html-explainer&Date">
  237. <img src="https://api.star-history.com/svg?repos=OneMoh/html-explainer&type=Date" alt="Star History Chart" width="720">
  238. </a>
  239. ---
  240. <div align="center">
  241. 如果这个项目对你有帮助,欢迎请作者喝杯咖啡 ☕
  242. <img src="https://raw.githubusercontent.com/OneMoh/html-explainer-demos/main/images/wechat-reward-qr.jpg" width="340" alt="Moh 的赞赏码">
  243. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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