html-to-video
把 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.
Badge for your README
Markdown
[](/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
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
- ---
- name: html-to-video
- description: 把 HTML/Canvas 动画逐帧渲染成 MP4(可配乐、可卡点、可出 GIF、可出透明层)。当用户说「用代码做视频」「HTML 转视频」「导出 MP4/GIF」「做个动态图解/宣传片/数据动画」「逐帧渲染」「换个风格」「卡点」「音乐配画面」「加运镜」「成片检查」「响度归一」时使用。自带渲染器、14 个版式模板(多镜头讲解片、竖屏 9:16、前后对比、流程图、字幕卡、引言卡、章节卡、界面演示)、14 种视觉风格(孔版印刷 / 木刻 / 剪纸 / 粉笔 / 铅笔 / 黏土 / 水墨 / 水彩 / 蓝图 / 等距 / 瑞士 / 半调 / 霓虹 / 玻璃拟态,分五个家族,一条命令切换)、节拍分析与卡点(--beats / --snap)、**镜头语言(12 个命名运动 + 5 种缓动,一行自然语言一条镜头,自带防露边)**、分镜预演、浏览器预览、环境自检、图标/人物/运镜素材库、**文案自检(字数 / 条数 / 陈词滥调 / 转折)**、**成片质检(hook / 黑场 / 冻结 / 重复帧 / 响度 / 联系表)**、**EBU R128 响度母版(−14 LUFS / −2 dBTP)**,支持透明输出、外部字幕时间轴与 JSON 镜头表,装好依赖后一条命令出片。
- agent_created: true
- ---
- # html-to-video · 代码逐帧做视频
- ## 这套东西是什么
- **不是 AI 生成视频**,是**用代码逐帧画视频**:
- ```
- 写 HTML/Canvas,把画面写成 frame(t) 纯函数
- → 无头浏览器逐帧 seek 到 t,截图
- → ffmpeg 编成 H.264 MP4
- 字幕 / 运镜 / 转场全在代码里,改代码重渲即可
- ```
- 优点:**确定性**(同输入同输出)、**可控到帧**、**中文文字完美**、**零费用**。
- 最适合做:讲解动画、动态图解、产品演示、数据可视化动画、宣传片片头。
- 不适合:实拍感/氛围镜头(那种走 VideoGen)。
- **交付前四道关**(分别管四个不同的东西,别只跑一个):
- | 命令 | 管什么 | 查不出会怎样 |
- |---|---|---|
- | `h2v check story.json` | 文案 | 字太多读者跳读、全片没有转折 |
- | `assets/qa.sh page.html` | 页面 | 画面混了随机数、文字出框/叠字、字体悄悄回退 |
- | `h2v qc out.mp4` | 成片 | 前 2 秒没动、黑场、冻结、音轨静音 |
- | `h2v master in.mp4` | 声音 | 手机外放听着比别人小一截 |
- **能拿它做什么**(`assets/templates/` 里 14 个模板直接改字就能出片):
- | 模板 | 用途 | 出片 |
- |---|---|---|
- | `explainer.html` | **多镜头讲解片**:片头 / 人物+气泡 / 要点 / 条形对比 / 片尾,镜头带转场,可喂 JSON 镜头表;横屏恰好三条要点时自动并排成三栏,竖屏(1080×1920)另有上下版式 | `--duration=17.6` |
- | `title-card.html` | 视频片头:主标题逐字弹入 + 副标题 | `--duration=6` |
- | `bar-chart.html` | 条形图/排名:条形依次生长,数值同步滚动 | `--duration=6` |
- | `line-chart.html` | 折线趋势:折线生长 + 数据点亮起 + 末点浮标 | `--duration=8` |
- | `number-counter.html` | 大数字/KPI:从 0 滚到目标值 + 涨跌标签 | `--duration=7` |
- | `timeline.html` | 时间线/流程:中轴生长,节点逐个点亮 | `--duration=7` |
- | `vertical-card.html` | **竖屏 9:16 卡片**:大字标题 + 大数字,抖音/视频号/Reels 用 | `--duration=6 --width=1080 --height=1920` |
- | `compare.html` | **前后对比**:左右两栏对照,结论条收口 | `--duration=7` |
- | `flow-steps.html` | **流程图动画**:步骤依次点亮,当前步高亮 | `--duration=7` |
- | `subtitle-card.html` | **逐句解说卡**:一句话一句地出,底部带进度条 | `--duration=8` + `--srt` |
- | `vertical-subtitle.html` | **竖屏字幕卡**:关键词高亮,9:16 原生版式 | `--duration=8 --width=1080 --height=1920` + `--srt` |
- | `quote-card.html` | **引言卡**:大引号 + 引文逐行推进 + 出处短线 | `--duration=7` |
- | `chapter-card.html` | **章节卡**:序号水印 + 标题 + 章节进度点,切分长片 | `--duration=4` |
- | `ui-showcase.html` | **界面演示**:窗口推入 + 缓推 + 两处聚光标注,可换真实截图(`CFG.shot`) | `--duration=8` |
- 每个模板**单文件自包含**,顶部有一个显眼的 `CFG` 配置块,改文案/数据即可 ——
- 不用懂 canvas 也能出片。**14 个模板全部支持换主题与 14 种视觉风格**(见「换配色」一节)。
- 想做别的,再看 `assets/animation-skeleton.html` 从零写。
- **上面 14 个是「版式」。想要不同的「观感」,加一个 `--theme` 就有 14 种视觉语言**:
- ```bash
- bash assets/render.sh assets/style-film.html --duration=13 --theme=ink # 水墨
- bash assets/render.sh assets/style-film.html --duration=13 --theme=clay # 黏土立体
- bash assets/render.sh assets/style-film.html --duration=13 --theme=watercolor # 水彩
- ```
- 版式 × 风格 = 14 × 14 种组合。想先挑风格,跑一次十四宫格即可(见「风格」一节)。
- **做「一支片子」而不是「一段动画」**:用 `assets/lib/scenes.js` 写多镜头 + 转场,
- 镜头表还能用 `--story=shots.json` 外置 —— LLM 写 JSON 比写几百行 canvas 代码可靠得多。
- 详见下面「多镜头与转场」一节。
- ### 尺寸:模板跟视口走,不用手改
- 14 个模板都按 `window.innerWidth/innerHeight` 设画布,所以**换任何尺寸都不裁切**:
- ```bash
- # 横屏 1080p(默认)
- bash assets/render.sh title-card.html --duration=6 --fps=60
- # 竖屏 9:16
- bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1080 --height=1920
- # 720p / 4K 同理
- bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1280 --height=720
- ```
- 模板内部用三档缩放把设计稿落到实际画布:
- | 变量 | 含义 | 1920×1080 | 1080×1920 |
- |---|---|---|---|
- | `SX = W/1920` | 横向尺寸、左右边距 | 1 | 0.5625 |
- | `SY = H/1080` | 纵向尺寸、行距 | 1 | 1.7778 |
- | `SF = √(SX·SY)` | 字号、线宽、圆角、模糊 | 1 | 1 |
- 字号用面积等比(`SF`)而不是跟宽度走 —— 换成竖屏时字**不会变小**,只是版式铺开。
- `1920×1080` 下三者都等于 1,所以**默认输出与旧版逐像素一致**(实测 PSNR = inf)。
- **自己写的动画也照这个来**,否则改 `--width/--height` 会静默裁掉右下角:
- ```js
- const cv = document.getElementById('stage');
- cv.width = window.innerWidth; // ← 不要写死 1920
- cv.height = window.innerHeight; // ← 不要写死 1080
- ```
- 渲染器现在会主动量一次画布尺寸,比视口小就明确告警(不再静默出半张图)。
- ## 先装依赖(只需一次)
- 渲染器需要 **Node 工作区**(内含 playwright + 完整版 ffmpeg)。一条命令搞定:
- ```bash
- bash scripts/install-deps.sh # 工作区默认 ~/.workbuddy/binaries/node/workspace
- bash scripts/install-deps.sh /path/to/workspace # 或自己指定
- ```
- 它会自动探测本机浏览器缓存、挑匹配的 playwright 版本、装完整版 ffmpeg,
- 并把工作区路径写进 `~/.workbuddy/.html2video-env`,之后 render.sh / smoke.sh / qa.sh 开箱即用。
- 手动装也行(工作区需含 `playwright` + `@ffmpeg-installer/ffmpeg`),然后自己写配置:
- ```bash
- # ~/.workbuddy/.html2video-env
- WB_NODE_WORKSPACE="<你的 node 工作区绝对路径>"
- ```
- > 也可以用环境变量临时指定:`export WB_NODE_WORKSPACE="<路径>"`。
- > **不要**把路径写进 `${VAR:-默认值}`——用户名若含撇号(如 `O'Brien`),
- > bash 会把撇号当引号开始,报 `bad substitution`。
- ### 四条硬约束(踩过,别重犯)
- 1. **Playwright 版本必须和浏览器缓存匹配。**
- `playwright-core@X` 只认自己在 `browsers.json` 里声明的 chromium build 号,
- 不匹配就报 "Executable doesn't exist"。
- → **别猜版本,用 `scripts/install-deps.sh`**,它会跑 `scripts/detect-env.js` 探测缓存后自动挑版本。
- 单独探测:`node scripts/detect-env.js`(输出 `RECOMMEND_PW=...`)。
- 已知映射:build 1148→1.49.1、1155→1.50.1、1169→1.52.0、1187→1.55.0、1208→1.58.0。
- **注意**:某些网络环境下 chromium 下载会反复中断(表现为缓存目录里躺着半截的残缺目录)。
- 此时优先复用已有缓存而非升级——这正是探测脚本存在的理由。
- 2. **Playwright 自带的那个 ffmpeg 没用。**
- `ms-playwright/ffmpeg-*/ffmpeg-win64.exe` 是 `--disable-everything` 编译的,
- 只有 VP8 编码 + webm 封装,**没有 H.264、没有 GIF、连 PNG 解码都没开**。
- 必须用 `@ffmpeg-installer/ffmpeg` 的完整版。
- 3. **ESM 不认 `NODE_PATH`。** `.mjs` 里 `import 'playwright'` 必然 `ERR_MODULE_NOT_FOUND`。
- → 辅助脚本一律写 **CJS(`.cjs` / `require`)**。
- 4. **PATH 不可靠。** 尤其在 Git Bash / Windows 上,塞进 PATH 的 Windows 风格路径会被转换搞坏。
- → **别靠 PATH 传 ffmpeg,用 `FFMPEG` 环境变量**(渲染器已支持)。
- ## 三种入口:CLI / 预览 / 自检
- **统一命令**(`bin/h2v.js`,只是子命令到脚本的映射,不改任何默认行为):
- ```bash
- npx html-to-video doctor # 环境自检:缺什么、怎么修(只读)
- npx html-to-video templates # 14 个模板
- npx html-to-video styles # 14 种风格(按家族分组)
- npx html-to-video camera # 12 个镜头运动 + 一行字怎么写
- npx html-to-video new my-video --template=chapter-card
- npx html-to-video preview my-video.html --duration=6 --open
- npx html-to-video render my-video.html --duration=6 --fps=60
- npx html-to-video check story.json # 文案自检(字数 / 条数 / 陈词滥调 / 转折)
- npx html-to-video qc out/film.mp4 # 成片质检(hook / 黑场 / 冻结 / 响度 / 联系表)
- npx html-to-video master in.mp4 --video=in.mp4 --out=final.mp4 # 响度母版 −14 LUFS
- ```
- **一句话分工**:`check` 管文案,`qa` 管页面,`qc` 管成片,`master` 管声音。
- 四个都能 `--json`,Agent 直接读。
- **预览**:`scripts/preview.js` 起本地 http(ESM/fetch 都能跑),把页面放进 iframe,
- 注入 `__seekRender` 冻结它自己的时钟,然后用滑块/空格/←→ 直接推 `__seek(t)`。
- 竖屏项目记得 `--size=1080x1920`,否则预览框是横的、模板按 16:9 排版,会误判成版式崩了。
- **自检**:`scripts/doctor.js` 检查 Node / Playwright(含版本与浏览器缓存是否匹配)/
- ffmpeg(是否含 libx264 与 ProRes)/ 中文字体 / 临时盘余量 / 工作区配置,
- 阻塞项给可执行修法;`--json` 给 CI 与 Agent 用。
- ## 出片流程
- ### 第 0 步(最省事的路):挑一个模板改字
- ```bash
- npx html-to-video new my-video --template=bar-chart # 推荐:依赖一起搬好
- # 或者,如果就在仓库目录里工作:
- cp assets/templates/bar-chart.html my-video.html
- # 打开 my-video.html,只改顶部 CFG 里的 title / data / note
- bash assets/render.sh my-video.html --duration=6 --fps=60
- ```
- ⚠️ **模板不是单文件**:`./themes.js`(配色)和 `../lib/*.js`(动效 / 镜头 / 图形库)
- 必须跟着走。只 `cp` 一个 HTML 出去,页面会 404 —— 而渲染器把「页面报错」判为失败,
- 你看到的是「渲染失败」,很难联想到少文件。`h2v new` 会自动把依赖搬齐,
- 并把 `../lib/camera.js` 改写成 `./lib/camera.js`;手工搬的话记得这一步。
- 模板有**字幕安全区**意识:文字不会落在画面底部 15%(烧录字幕后会被盖住)。
- 自己做版式时也照这个来。
- ### 第 1 步:写动画 HTML(模板不够用时)
- 用 `assets/animation-skeleton.html` 当骨架。**核心契约**(渲染器靠它工作):
- ```js
- // 必须暴露这两个
- window.__seek = (t) => { /* 把 t 时刻的画面完整重绘一帧 */ };
- window.__ready = true; // 就绪信号
- // 渲染器会注入 window.__seekRender = true,
- // 此时必须【冻结自驱时钟】,完全由外部 __seek 推帧(保证确定性)
- if (window.__seekRender) { renderAt(0); window.__ready = true; }
- else { /* 浏览器预览:requestAnimationFrame 自驱循环 */ }
- ```
- **铁律:每一帧画面 = 时间 t 的纯函数。** 不要依赖「上一帧」的状态,
- 不要用 `Math.random()` / `Date.now()` / `performance.now()`——那会让同输入不同输出,
- QA 里的「确定性」会亮红灯,而且多 worker 并行渲染会各渲各的。
- **画布就是唯一输出**:`<canvas width=1920 height=1080>`,CSS 定位在 `left:0; top:0`,
- body `margin:0`。渲染器用 `clip:{x:0,y:0,width:W,height:H}` 截左上角,所以画布必须正好铺满视口、不能居中。
- (渲染器也支持 DOM/CSS/SVG 动画,同样只需暴露 `__seek`——但注意:DOM 动画每帧重排较慢,
- 纯 canvas 通常更稳更快。)
- **禁止使用的 class 名**(渲染器注入的 CSS 会无条件隐藏它们,元素会凭空消失):
- `.no-record .progress .progress-bar .counter .tCur .phases .phase-label .phase .replay .masthead .kicker .title .footer`
- 另外别给 `position:fixed/sticky` 的元素加 `<button>`,会被启发式规则当成播放控件隐藏。
- (想让某块**出现在成片里**,给它加 `data-record-keep="true"` 就能豁免启发式隐藏。)
- **中文字体**:`'"Microsoft YaHei", "PingFang SC", system-ui, sans-serif'`;等宽用 `'ui-monospace, Consolas, monospace'`。
- ### 第 2 步:冒烟测试(**别跳**)
- 先只截几帧,确认契约就绪、没控制台报错、画面没糊,再跑全量:
- ```bash
- bash assets/smoke.sh animation.html
- # SMOKE_T="0,1,2" SMOKE_W=1280 SMOKE_H=720 bash assets/smoke.sh animation.html
- ```
- 更快的迭代方式:**只渲一小段**,几秒就能看到动态效果。
- ```bash
- bash assets/render.sh animation.html --from=3 --to=5 --fps=30 # 只渲 3s–5s
- bash assets/render.sh animation.html --stills=1,3,5 # 只导出三张静帧
- ```
- ### 第 3 步:全量渲染
- ```bash
- bash assets/render.sh animation.html --duration=12 --fps=60 --width=1920 --height=1080 --concurrency=4
- ```
- 常用参数:
- | 参数 | 作用 |
- |---|---|
- | `--duration` / `--from` / `--to` | 时长 / 只渲某段(秒)。给了范围时输出名变成 `名.起-止s.mp4`,**不会覆盖成品** |
- | `--stills=0.5,2.0` | 只导出这些时刻的 PNG,不编码 |
- | `--fps` / `--width` / `--height` | 帧率与分辨率 |
- | `--preset=<名>` | 按平台预设定尺寸:`douyin` / `tiktok` / `vertical`(1080×1920)、`xiaohongshu`(1080×1440)、`instagram`(1080×1350)、`square`(1080×1080)、`bilibili` / `youtube` / `landscape`(1920×1080) |
- | `--presets=a,b,c` | **一条命令出全套比例**,每个比例一个成片(文件名自动加 `-比例名` 后缀)。跨平台发布用这个 |
- | `--theme=<名>` | 换主题(`midnight` / `paper` / `neon`),覆盖模板里的 `CFG.theme`,不用改文件。名字打错会明确告警并回退 midnight |
- | `--out=<文件>` | 指定成片路径(默认同目录同名)。一份 HTML 出多套配色时用它,否则后渲的会盖掉前一个;上级目录不存在会自动建 |
- | `--json` | stdout 只输出一行结果 JSON(`output` / `duration` / `frames` / `warnings` 等),人读日志全部走 stderr。给 Agent 解析用 |
- | `--concurrency` | 并行 worker 数(每个 worker 一个 Chromium 页面,注意内存)。给 `auto` 按 CPU 与内存自己挑 |
- | `--audio=<file>` | 编码后自动混音(视频流直接 copy,不重编码)。**没给 `--duration` 时自动按音频长度出片**(向上取整到整帧,尾音不被削) |
- | `--audio-fit=trim\|pad` | 音画长度不一致时怎么办:`trim` 按音轨收尾(默认)/`pad` 给音频补静音、保住视频长度 |
- | `--beats` / `--beats=<json>` | 分析 `--audio` 的拍点(或用预计算的网格),注入 `window.__beats` |
- | `--snap=beats` | 总时长吸到下一个拍点 |
- | `--snap-shots` | 镜头表里每个镜头的时长量化到整拍 |
- | `--bpm=<数>` / `--offset=<秒>` | 跳过估计,手工给 BPM / 首拍(纯配音硬卡点时用) |
- | `--gop=<秒>` | 关键帧间隔,如 `--gop=1` 每秒一个关键帧,方便后期按秒 seek |
- | `--keep-frames` | 成功也保留逐帧 PNG(换 CRF 重编码时不必重截) |
- | `--tmpdir=<目录>` | 逐帧 PNG 放哪块盘(默认挨着 HTML)。1080p 一分钟约 2.4 GB,系统盘没余量时指到别的盘 |
- | `--resume` | 上次渲到一半被打断?接着渲,已渲好的帧直接复用(参数和上次不一致会拒绝,见下) |
- | `--alpha` | 透明背景输出(ProRes 4444 `.mov`),叠到实拍 / AI 生成画面上用,见下 |
- | `--srt=<file>` | 外部字幕时间轴(SRT / VTT / JSON),注入 `window.__cues`,见下。同义参数 `--cues` |
- | `--cue-log=<file>` | 导出 `frame,t,cue_index,cue_start,cue_end` CSV,用来核对字幕到底对不对轴 |
- | `--story=<file>` | 镜头表 JSON,注入 `window.__story`,整份换掉剧本(见「多镜头与转场」) |
- | `--scene-log=<file>` | 导出镜头时间轴 CSV;镜头表总时长与 `--duration` 不一致会告警 |
- | `--gif[=fps,宽]` | 出片后顺手产 GIF(默认 15fps / 宽 960),两阶段 palette 优化,不重渲 |
- | `--poster=<秒>` | 出片后顺手抽一张封面静帧 `.jpg`,发站 / 社媒用 |
- | `--batch=<file.json>` | 一串任务按顺序渲,最后打汇总表;单个失败不连坐已渲好的,但整体非零退出 |
- | `--headed` | 开着浏览器窗口渲(调试用;并发自动降到 1,免得弹一排窗口) |
- | `--allow-errors` | 页面报错不判失败(默认:有报错 → 非零退出) |
- | `--keep-chrome` | 不隐藏播放控件(调试用) |
- | `--readytimeout=8` | 等 `__seek` 就绪的秒数(启动慢的大字体/大数据可调大) |
- | `--no-serve` | 用 `file://` 加载页面(默认走本地 http server,见下) |
- **ESM / fetch 项目直接能渲**。渲染器默认起一个只绑 `127.0.0.1` 的本地 http server 来加载页面 ——
- `file://` 下 `<script type="module">` 和 `fetch()` 会被 CORS 拦死,用 Vite/esbuild 组织的动画、
- 读本地 JSON 的项目根本起不来;走 http 就没这些事。渲染开头会打印这个地址,排障时直接粘到浏览器里看控制台最方便。
- 服务器起不来会自动退回 `file://` 并提示(只警告,不判失败)。
- - 输出与 HTML 同名的 `.mp4`
- - 帧数 = `fps × duration`。**12s@60fps = 720 帧,实测约 6~7 分钟**(concurrency=4)
- - 编码约 1 分钟(crf 18 / preset medium)
- **渲染结束有页面报错会非零退出**(但成片照样产出,方便你核对)。
- ### 渲到一半断了,别从零开始
- 长片子(60fps × 30s = 1800 帧)跑到 80% 崩了,从零重来最伤。加 `--resume` 就接着渲:
- ```bash
- bash assets/render.sh animation.html --fps=60 --duration=30 --resume
- # ▸ resume: 已复用 1432 帧,还需渲 368 帧
- ```
- 规则三条,都是为了「续出来的片子和一次渲完的片子一模一样」:
- - **帧先写 `.part` 再改名**。被 kill 的那一帧不会留下半个 PNG 冒充「已完成」,所以复用的帧都是真画完的。
- - **参数变了直接拒绝**。上次 30fps、这次 60fps 会把两批帧混着编码,片子前后节奏不一致还不报错 ——
- 所以 `fps / 尺寸 / 范围 / 渲染模式` 任一不同就退出并打印「上次 vs 这次」,让你自己决定删不删。
- - **帧号必须连续**。缺一张 ffmpeg 会静默提前收尾、成片莫名变短,所以编码前按 `[起,止)` 逐个核号,
- 有洞就报出来并提示加 `--resume` 补。
- 临时目录固定在 HTML 旁边的 `.seek-tmp-resume/`(不加 `--resume` 时仍是一次性目录,并发渲互不干扰)。
- 渲完自动清掉;中途想留着就配 `--keep-frames`。
- 这是故意的:页面报错常常意味着「整片黑屏 / 缺了半屏内容」,以前的版本会一路说成功,
- 直到你回抽帧才发现——现在它会在编码前就把报错打出来,并在最后判失败。
- ### 透明输出:把文字层叠到别人拍的画面上
- AI 生成的背景 + 代码生成的文字层,是现在最省钱的组合(模型画文字必糊,代码画文字精确到像素)。
- `--alpha` 就是为这条路准备的:
- ```bash
- bash assets/render.sh animation.html --duration=6 --fps=30 --alpha
- # → animation.mov(ProRes 4444 / yuva444p10le,背景透明)
- ```
- **模板侧要配合一件事**:读到 `window.__transparent` 为真时跳过背景层绘制。
- 目前 `title-card`、`compare`、`flow-steps`、`subtitle-card`、`vertical-subtitle`、
- `explainer` 这 6 个已经这样写,直接加 `--alpha` 就有透明效果;
- 其余 5 个是满版图表(条形 / 折线 / 大数字 / 时间线 / 竖屏卡),本来就要底色,加了也只会得到不透明的片子。
- 自己写的动画照这个来:
- ```js
- const TRANSPARENT = !!window.__transparent;
- function drawFrame(t) {
- g.clearRect(0, 0, W, H);
- if (!TRANSPARENT) {
- // 底色 / 全屏渐变 / 光斑 —— 这些都要跳过
- g.fillStyle = '#080A10';
- g.fillRect(0, 0, W, H);
- }
- // 文字、图形照常画
- }
- ```
- **全屏的半透明光晕也要一起跳过**。哪怕它只有 5% 不透明度,叠到实拍上会让整片区域泛白,
- 剪辑师第一反应是「这素材脏」。实测:只跳底色、留着光斑时,四角 alpha=12(不是 0);
- 全跳之后四角 alpha=0、只有 3.7% 的像素不透明(全是文字)。
- **体积代价**(960×540 / 2s / 20 帧实测):
- | 输出 | 体积 | 用途 |
- |---|---|---|
- | H.264 `.mp4` | 118 KB | 成片直接发 |
- | ProRes 4444 `.mov` | 760 KB(6.5×) | 拖进剪辑软件叠层 |
- **只有 ProRes,没有 VP9**。试过 `--pix_fmt yuva420p` + `-auto-alt-ref 0`,文件确实从 7.8KB
- 涨到 16.8KB(alpha 数据写进去了),但 Chromium 播出来整帧 alpha 全 0 —— 连文字都透明;
- 换 lossless、固定码率、`-lag-in-frames 0` 都一样。既然没法自证正确,就不把它作为选项发布。
- 要小体积透明素材,用 ProRes 导入剪辑软件后再导 webm,那是那边的活。
- ### 配音对齐:先有声音,再定画面长度
- 真实工作流是「写文案 → 配音 → 配画面」,而不是先定 6 秒再想办法把配音塞进去。
- 所以**给了 `--audio` 又没给 `--duration` 时,视频按音频长度出片**:
- ```bash
- bash assets/render.sh title-card.html --audio=voice.m4a --story=shots.json
- # ▸ audio: 音频 12.48s,未指定 --duration → 视频按音频定长(12.5s,向上取整到整帧)
- ```
- - **向上取整到整帧**,不是四舍五入:少半帧就会把最后一个字的尾音削掉。
- - 显式给了 `--duration` 且与音频差超过 0.35s 会**明确告警**,说清差多少、伤在哪边。
- 旧版本这里会静默出一支短片 —— 画面后半段整段消失,日志却只有一句 `✓ Done`。
- - `--audio-fit=pad`:音频比视频短时补静音,保住整段画面(默认 `trim` 按音轨收尾)。
- 注意:`trim` 下成片**不会精确等于音频秒数**。视频流是 `-c:v copy` 直接复制的,
- ffmpeg 只能按帧包边界收尾,实测会多留 0.3–0.5s。想要毫秒级对齐得重编码,
- 那是拿画质换精度,不值得 —— 片尾多留几帧通常看不出来。
- ### 卡点:让切点落在拍上
- 「切点落在拍上」是片子显得专业的最短路径。手工对齐是数秒表挪关键帧,
- 换一首 BGM 全部重来;这里把拍点量出来,镜头时长直接量化到整拍:
- ```bash
- bash assets/render.sh style-film.html --audio=bgm.mp3 --beats --snap=beats
- # ▸ 节拍: 120.14 BPM · 20 个拍点 · 首拍 0.49s · 置信度 0.85
- # ▸ 时长对齐拍点: 25.2s → 25.5s(+0.3s)
- bash assets/render.sh style-film.html --story=shots.json --beats=beats.json --snap-shots
- # ▸ 镜头对齐拍点(1 拍 = 0.499s):8 个镜头改了时长
- # · hook 2.80s → 3.00s
- # → 片长按镜头表定为 25.472s
- ```
- 规则(都是踩过才知道的):
- - **改镜头,不改 BGM。** 配乐是骨架;除非你明确要裁音乐,否则画面去迁就拍子。
- - **--snap-shots 会明说改了多少**,单镜变化 >25% 会警告 —— 节奏真的变了,导演得知道。
- - **没给 `--duration` 时,片长跟着镜头表走**;给了就以你为准,只告警不偷偷改。
- - **测不出稳定 BPM 就报警**,不硬卡。纯配音/环境音在物理上没有周期性重音,
- 这时候正确做法是按句子切(`--srt`),不是按拍切。
- - 模板侧:`window.__beats` = `{ bpm, offset, beats[], downbeats[], confidence }`;
- 风格库给 `SV.pulse(t)`(拍点处 1、按 `decay` 衰减)与 `SV.beatPhase(t)`。
- 没有 `--beats` 时 `pulse()` 恒为 0,所以同一份模板加不加卡点都能跑。
- 单独跑分析器(零依赖,纯 ffmpeg + 算术):
- ```bash
- node scripts/beats.js bgm.mp3 --json # {bpm, confidence, offset, beats:[...]}
- node scripts/beats.js bgm.mp3 --out=beats.json # 存下来复用(同一 BGM 出多条片子)
- ```
- 精度:120BPM 鼓点实测 BPM 误差 <2、相位误差 ~9ms;分析 10 秒音频约 25ms。
- ### 一稿多发:一条命令出全套平台比例
- 同一条片子要发抖音、小红书、B 站,剪辑软件里得一个比例一个序列、导一次盯一次。
- 这里版式本来就是参数化的,多渲一遍只是多一次循环:
- ```bash
- bash assets/render.sh bar-chart.html --duration=8 \
- --presets=douyin,xiaohongshu,square --out=dist/chart.mp4
- # → dist/chart-douyin.mp4 1080×1920
- # dist/chart-xiaohongshu.mp4 1080×1440
- # dist/chart-square.mp4 1080×1080
- ```
- | 预设 | 尺寸 | 给谁用 |
- |---|---|---|
- | `douyin` / `tiktok` / `vertical` | 1080×1920 | 抖音、快手、视频号、Reels、Shorts |
- | `xiaohongshu` / `xhs` | 1080×1440 | 小红书 3:4 |
- | `instagram` / `ig` | 1080×1350 | IG 信息流 4:5 |
- | `square` | 1080×1080 | 方版 1:1 |
- | `bilibili` / `youtube` / `landscape` | 1920×1080 | 横屏 16:9 |
- - 单个比例用 `--preset=xiaohongshu`;多个用 `--presets=a,b`(**至少两个**,只想要一个就用 `--preset`)。
- - 预设名拼错会直接失败并列出可用名字 —— 不会悄悄按 1920×1080 渲一版比例错误的片子。
- - **版式能不能撑住是另一回事**:模板跟视口自适应,但 9:16 与 16:9 的信息密度不同,
- 3:4 上字号偏大 / 内容偏挤要自己看一眼。`--presets` 只保证尺寸对,不保证构图好看。
- - **竖屏底部那块留白是故意的**,不是排版出错:平台进度条和按钮压在那儿,
- 模板统一给烧录字幕留了 15% 安全区。
- - 与 `--stills` 互斥(一个是出多片、一个是只截图);与 `--batch` 不能嵌套。
- ### 给 Agent 用:`--json`
- 这个工具的主力调用方是 AI Agent。人读 `✓ Done: xxx.mp4 (1.2 MB · 30fps · 12s)` 没问题,
- Agent 只能拿正则去猜 —— 路径里带空格、中文、括号就崩。`--json` 把结果结构化:
- ```bash
- bash assets/render.sh title-card.html --duration=6 --json
- ```
- ```json
- {"ok":true,"exitCode":0,"input":"…/title-card.html","output":"…/title-card.mp4",
- "width":1920,"height":1080,"fps":60,"duration":6,"frames":360,"bytes":2411724,
- "gif":null,"poster":null,"warnings":[],"mode":"video","theme":null,"preset":null}
- ```
- - **stdout 只有这一行**,进度与人读日志全部改道 stderr —— 直接 `JSON.parse(stdout)` 即可。
- - `warnings` 是数组:参数冲突、音画长度不符、主题名不认识都进这里。空数组 = 干净。
- - `duration` 是**成片实际时长**(ffmpeg 读回来的),不是计划值。
- - `--presets` 时 `output` 变成数组,另附 `presets: [{name,width,height,output,ok,bytes}]`。
- ### 字幕挂外部时间轴:配音改了,字幕跟着走
- 字幕文案写在模板的 `CFG.lines` 里最省事,但一旦要配音,时间点就得跟着音频走 ——
- 总不能每改一句都回去手数秒数。所以支持直接喂一坨字幕文件:
- ```bash
- bash assets/render.sh subtitle-card.html --duration=8 --srt=voice.srt --cue-log=cues.csv
- ```
- - 支持 **SRT**(`HH:MM:SS,mmm`)、**WebVTT**(`MM:SS.mmm` 也行)、**JSON**(`[{start,end,text}]`)。
- - 解析一次,注入 `window.__cues`,模板按当前帧的 `t` 自己去查该显示哪句。
- 模板里用 `--srt` 时**优先读 `__cues`,没有才回退 `CFG.lines`**,所以同一个模板两种用法都成立。
- - `--cue-log` 输出 `frame,t,cue_index,cue_start,cue_end` 的 CSV。把「字幕时间对不对」
- 变成一个能算的数:拿每句的首帧时间减 SRT 的起点,就是误差。
- 实测 4 句 / 80 帧,每句误差 **0 ms**,帧覆盖数与理论值完全一致。
- 模板侧只要两行就能支持:
- ```js
- const cues = (window.__cues && window.__cues.length) ? window.__cues : CFG.lines;
- const cur = cues.find(c => t >= c.start && t < c.end) || cues[cues.length - 1];
- ```
- **字幕别踩进底部 15%**。那是各平台的进度条 / 点赞按钮区,写进去等于白写。
- `qa.js` 会提示「进字幕带」,四个新模板的竖屏版式都留出了这条安全带。
- ### 换配色:改一个字段,不用碰画布代码
- `assets/templates/themes.js` 里有三套调色板,**14 个模板全部接入**;另有 12 套风格色板走 `lib/styles.js`。两种换法:
- ```bash
- # ① 命令行换(推荐):不改任何文件,一次渲染一个主题
- bash assets/render.sh bar-chart.html --duration=6 --theme=paper --out=bar-paper.mp4
- # ② 改文件:在模板顶部 CFG 里写死
- ```
- ```js
- const CFG = {
- theme: 'paper', // midnight(默认,暗色)| paper(浅色)| neon(黑紫霓虹)
- ...
- };
- ```
- 命令行优先于 `CFG.theme`(渲染器注入 `window.__h2vTheme`,模板读
- `h2vTheme(window.__h2vTheme || CFG.theme)`)。所以同一份 HTML 可以批量出三套配色:
- ```json
- [{ "html": "bar-chart.html", "duration": 6, "theme": "midnight", "out": "bar-dark.mp4" },
- { "html": "bar-chart.html", "duration": 6, "theme": "paper", "out": "bar-light.mp4" }]
- ```
- 批量里**必须配 `out`**:成片默认名是 `<HTML 名>.mp4`,同一个 HTML 渲两套配色
- 不换输出名的话,后一个会把前一个盖掉。
- | 主题 | 观感 | 适合 |
- |---|---|---|
- | `midnight` | 近黑底 + 暖橙强调 | 通用,默认 |
- | `paper` | 米白底 + 深墨文字 | 文档、教学、要打印或投影的场合 |
- | `neon` | 黑紫底 + 紫/青霓虹 | 科技、发布会、社区宣传 |
- 要微调就传对象,缺的字段自动从 `midnight` 补:
- ```js
- theme: { bg: '#0B1020', accent: '#22D3EE' }
- ```
- **加主题不背「默认画面偷偷变了」的债**,靠一条约定:`themes.js` 里
- `midnight` 只填 11 个基础字段,另外 5 个可选字段(`bgFar` / `accentDeep` /
- `accentSoft` / `sweep` / `onAccent`)只给 `paper` 和 `neon` 填;
- 模板一律写成 `TH.accentDeep || '<历史常量>'`。于是默认主题走的还是原来那些常量,
- 换主题时才用新色。测试会盯住这条约定(midnight 填了可选字段就报错)。
- **`themes.js` 是外部脚本,拷模板时连它一起拷**。只拷 HTML 会怎样:页面的兜底色板让画面
- 照常画出来,但 `<script src="./themes.js">` 会 404 —— 而渲染器把「页面报错」判为失败,
- 于是你会看到「Failed to load resource: 404」加一句渲染失败。**这不是画面坏了**,
- 把 `themes.js` 拷到同目录(或者加 `--allow-errors`)即可。
- `test/templates-contract.test.mjs` 会检查「登记了主题能力就必须真的引入
- themes.js,并且必须读 `window.__h2vTheme`」——后者保证命令行换主题不是空操作。
- ### 第 4 步:配乐 / 派生格式
- 渲染时加 `--audio=` 就能直接混音;需要更细的控制时用下面的命令:
- ```bash
- FF="<node工作区>/node_modules/@ffmpeg-installer/win32-x64/ffmpeg.exe" # Windows
- # 其它平台:FF="<node工作区>/node_modules/@ffmpeg-installer/ffmpeg"
- # 混 BGM(0.8s 淡入 / 1.4s 淡出,视频流不重编码)
- "$FF" -y -i animation.mp4 -i "$BGM" -filter_complex \
- "[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]" \
- -map 0:v -map "[a]" -c:v copy -c:a aac -b:a 192k -shortest -movflags +faststart animation-bgm.mp4
- # GIF(两阶段 palette 优化,否则糊)
- "$FF" -y -i animation.mp4 -vf "fps=15,scale=960:-1:flags=lanczos,palettegen=stats_mode=diff" palette.png
- "$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
- # 竖屏:改 HTML 画布尺寸后重渲,别用裁剪
- ```
- ### 响度母版:`h2v master`(同一个片子,在不同平台一样响)
- 手机外放听着小、笔记本上听着大 —— 不是错觉,是没做响度归一。
- 平台之间的差异可以差 6–8 LU。母版的目标是 **−14 LUFS / −2 dBTP**(视频平台通行的落点)。
- ```bash
- node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4 # 带画面
- node scripts/audio-master.js voice.wav --out=voice-master.wav # 只要音频
- node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4 --no-limit # 不加限幅器
- ```
- **两遍 `loudnorm`,第二遍必须线性**:
- | 遍 | 干什么 | 为什么不能合成一遍 |
- |---|---|---|
- | pass 1 | 只**测量**(LUFS / LRA / true peak),丢弃输出 | 归一化要用到整片的统计量,必须先看完 |
- | pass 2 | 用测得的数值 `linear=true` 做**固定增益** | 一遍式是动态模式 = 边跑边压,会改变动态、抽气 |
- 两个坑,都踩过:
- - **LRA 超过目标时,`loudnorm` 会静默切回动态模式。** 报告里 `type` 字段不是 `linear`
- 就说明它偷偷加压限器了 —— 这时要放宽 `--lra` 或接受动态模式,别以为"归一成功了"。
- - **限幅之后要重新测量。** 限幅器改变峰值,pass 2 还用限幅前的数值会算错增益。
- 代码里是 `let m = measure('')`,限幅后 `m = r.m` 接回去 —— 用 `const` 就会静默错误。
- - **AAC 编码会把真峰值抬 0.5–0.7 dB。** 所以带视频时目标压到 −2 dBTP,留出编码余量。
- 限幅链固定为 `volume=${g}dB,alimiter=limit=…:attack=5:release=60:level=false`。
- `level=false` 是**必须**的:默认 `level=true` 会把输出自动抬到 0 dB,等于白限。
- (本机那版 ffmpeg 的 `alimiter` 没有 `latency` 参数,写上去整条 filter 会解析失败。)
- 实测一组:原始 −17.77 LUFS → 母版 −13.9 LUFS,真峰值 −1.8 dBTP,`type=linear`。
- ### 第 5 步:自动化验收(**交付前跑**)
- 渲染器只保证「帧渲出来了」,不保证「画面是对的」。这一步把肉眼最容易漏的问题量化:
- ```bash
- bash assets/qa.sh animation.html --duration=12 --fps=30
- ```
- 它做的事:
- | 维度 | 量什么 |
- |---|---|
- | 确定性 | 抽 首/中/末 3 个时刻,各做两轮逐像素比对:同页面 seek 回去(验累积状态)+ 全新页面重渲(验随机初始化)。不一致 = 画面里混了随机数/时钟/累积状态 |
- | 动感 | 相邻帧变化像素占比(运动%)、静止帧对比例、**最长连续静止秒数** |
- | 流畅 | 相邻帧差的峰值/中位数,报「跳变」时刻 |
- | 框景 | 从加载起 hook `fillText/strokeText` + DOM 文字行框 → 报**半截字 / 叠字 / 进字幕带 / 近空白** |
- | 字体 | 声明的字体是否可用、是否悄悄回退到兜底字体(缺字形是静默失败) |
- | 报错 | pageerror / console.error 清单(有则判失败,退出码非零) |
- 产物:`qa/qa.md`(表 + 线索清单)、`qa/qa.json`(原始数字)、`qa/<名>.heat.png`(运动热图)。
- 判据的脾气:**经验阈值,不是规则**。运动 0.5%–8% 多数好看;最长静止 ≥3s 会提示
- (有意定格可以忽略);跳变 >0 先去看那一帧;框景线索只是「去看一眼」的提示,不让 QA 失败。
- 关键参数:`--safe-bottom=0.15`(画面底部这个比例内出现文字就警告,烧录字幕会盖住;`0` 关掉)、
- `--skip=0.35`(跳过段首的镜头冲击)、`--samples=120`(采样帧数上限)。
- **采样间隔要 ≤0.1s**,否则一段快速位移在相邻两帧之间看着就像「跳」——那是采样假象不是穿帮。
- `qa.sh` 在间隔 >0.15s 时会提示该把 `--samples` 提到多少。(实测:同一段 title-card,
- `--fps=6` 报 2 处跳变,`--fps=30` 报 0 处。)
- > 已知盲区:画进离屏 canvas 再 `drawImage` 上来的文字追不到;被图形挡住的字查不到;
- > 采样从 `--skip` 之后开始,开场瞬间的问题看不到。这些都在报告里说明了。
- ### 成片质检:`h2v qc`(量的是**已编码的 mp4**,不是页面)
- `qa.js` 查的是页面(帧对不对),`qc.js` 查的是成片(片能不能用)。
- 两者不重复:编码参数、音轨、真实播放时的冻结与黑场,只有解码之后才看得见。
- ```bash
- node scripts/qc.js out/film.mp4 # 人看的报告
- node scripts/qc.js out/film.mp4 --json # Agent 读的 JSON
- node scripts/qc.js out/film.mp4 --hook-min=0.5 # 实拍片用严一点的 hook 门槛
- ```
- | 检查 | 判据 | 为什么值得单列一项 |
- |---|---|---|
- | `hook` | 前 2 秒相邻帧平均灰度差 ≥ 0.35 | 短视频前 2 秒没动 = 划走。用 `tblend=difference` + `signalstats` 量,不看"感觉" |
- | `black` | `blackdetect` 无 ≥0.3s 的黑段 | 模板淡入淡出常把首帧做成纯黑,人眼在播放器里看不出来 |
- | `freeze` | `freezedetect` 无 ≥1s 的定格 | 渲染卡住/时间轴算错会得到"看着像静帧"的片子 |
- | `dup` | 相邻帧完全相同的对数 | 与 freeze 互补:dup 抓"整段复制",freeze 抓"画到一半不动" |
- | `bright` | 平均亮度落在 16–240 | 全黑/全白通常是主题配错或图层顺序错了 |
- | `info` | 分辨率 / 帧率 / 时长 / 编码 / 采样率 | 一稿多发时确认没渲错比例 |
- | `cuts` | 场景切换点数量与位置 | 和镜头表对不上 = `--story` 没生效 |
- | `loud` | 有音轨时量响度,无音轨明确标 N/A | 见下面的响度母版 |
- | `sheet` | 抽 9 帧拼一张联系表 | 一眼扫完整片,比逐帧看快 |
- **hook 门槛的实测基线**(这是给阈值找依据,不是拍脑袋):
- | 画面 | 相邻帧平均灰度差 |
- |---|---|
- | 纯色静止 | 0.00 |
- | 极简标题卡(有文字入场) | 0.36 – 0.42 |
- | 同画面再加胶片颗粒 | 0.71 |
- | 正常有运动的片子 | 0.85 – 1.2 |
- 所以默认 `0.35`(数字/文字类刚好过线),实拍或强运动片建议 `--hook-min=0.5`。
- `hook` 失败会让进程 `exit 1` —— 这一条是硬规则,其余都是「提示去看一眼」。
- > 只用 ffmpeg,不依赖 ffprobe(很多精简环境没有)。元数据靠解析 `ffmpeg -i` 的 stderr。
- > 无音轨的片子走 `{ noAudio: true }` 分支,不会误报「有音轨但没声音」。
- ### 第 6 步:独立验证(别只看工具说成功)
- ```bash
- # 从成片回抽帧,亲眼确认画面
- "$FF" -y -ss 4.0 -i animation-bgm.mp4 -frames:v 1 -q:v 2 out/verify-4.0.jpg
- # 校验规格
- "$FF" -hide_banner -i animation-bgm.mp4 2>&1 | grep -E "Duration|Stream"
- # 解码完整性(无输出即无错误)
- "$FF" -v error -i animation-bgm.mp4 -f null -
- ```
- ⚠️ **验证渲染时务必换输出名或另建目录**。渲染器输出名固定为「HTML 同名 .mp4」,
- 拿真文件名跑一次短渲染验证,会把成品覆盖成短版。(踩过,只能重新编码。)
- 用 `--from/--to` 时输出名自带范围后缀,天然不会覆盖;也可以直接换目录。
- ## 文案:先写对,再写好看
- 技术再好,文案烂一样没人看完。这一段是**规则**,不是灵感建议 ——
- 完整版在 `references/writing.md`,下面是能立刻用的部分。
- ```bash
- node scripts/script-check.js story.json # 横屏:单行上限 14 字
- node scripts/script-check.js story.json --vertical # 竖屏:12 字
- ```
- 输出示例(真实跑出来的):
- ```
- 6 镜 / 20.5s / 193 字 / 9.4 字每秒
- 1. hook 3s 25 字
- ⚠ 2. points 4s 57 字 3 条
- 5. compare 3.5s 43 字
- ✗ 要改的:
- · 第 1 镜(hook)的 sub 有 17 个汉字 > 14:「渲染器自己量拍子,镜头时长量化到整拍」
- ```
- **四条最容易违反的**:
- | 规则 | 具体 | 为什么 |
- |---|---|---|
- | 一行不超过 14 字(竖屏 12) | 超了观众开始跳读,不是"信息量大" | 手机屏上一行塞 18 个字,字号必然缩到看不清 |
- | 每镜条目 ≤ 4 条(竖屏 ≤ 3) | 多了就不是"看",是"读" | 观众在一镜里能接住的信息有上限 |
- | 阅读速度 ≤ 12 字/秒 | 中文口播约 4.5 字/秒,屏幕文字可以快但要留出反应时间 | 快过这个数,字幕变成噪声 |
- | 一镜一个转折 | 6 种转法:对比 / 反转 / 代价 / 意外数字 / 时间跳 / 视角换 | 全片没有转折 = 没有"看到最后"的理由 |
- **字幕测试(caption test)**:把这句话当这一镜的图注读一遍 —— 如果它只是把画面又说了一遍,删掉。
- 旁白要加画面给不了的东西:潜台词、对照、过去、心里的声音、一条规则。
- **陈词滥调一出现就删**:「在这个时代」「随着……的发展」「赋能」「闭环」「未来已来」「重新定义」
- 「极致体验」。换成一个能拍出来的动作或一个具体数字 ——
- 「极致体验」→「按下到出片,4 秒」。
- **字数预算表**(要超之前先看这张):
- | 时长 | 旁白预算 | 单条屏幕文字 | 每镜最多几条 |
- |---|---|---|---|
- | 15 秒 | ≤ 65 字 | ≤ 12 字 | 2 |
- | 30 秒 | ≤ 130 字 | ≤ 14 字 | 3 |
- | 60 秒 | ≤ 260 字 | ≤ 16 字 | 4 |
- | 3 分钟 | ≤ 780 字 | ≤ 18 字 | 5 |
- `script-check.js` 只是机器能查的部分。剩下两条机器查不了,但必须做:
- **读出声**(打结的地方就是观众听不懂的地方)、**砍 30%**(第二遍不是润色,是删)。
- ## 动效库:assets/lib/motion.js
- 缓动、弹簧、步进、错开、拍号的纯函数库,和「冻结时钟 + `__seek(t)`」天然契合:
- ```html
- <script src="../lib/motion.js"></script>
- <script>
- const p = MO.expoOut(MO.seg(t, 0.3, 1.4)); // 0..1 进度
- const y = MO.lerp(80, 0, p); // 位移
- const s = 1 + MO.settle(t - 1.2, 0.06); // 到位后的余振
- </script>
- ```
- 选缓动的一句话:讲解类用 `MO.smooth` / `sineInOut`(两端都停稳);发布会用 `MO.appleOut` / `MO.snappy`;
- 动态大字用 `expoOut` + `MO.springHz`;纸片/拼贴按 `MO.step(t, 12)` 一拍二;逐项入场用 `MO.stagger`。
- **别让画面「死」掉**:一段动效做完后如果还要停留好几秒,加一点持续微动
- (慢速光扫、呼吸、漂浮 `MO.float`),否则观众会觉得视频卡住了。模板里都带了这一手。
- ## 多镜头与转场:assets/lib/scenes.js
- 一支能看的片子是「多镜头 + 转场」,不是几段动画硬拼。以前只能渲几段再拿 ffmpeg 拼
- (还要自己算 offset);现在**一个 HTML 里写镜头表**,渲染器照旧只管按 `t` 推帧,
- 转场在页面内合成 —— 一条命令照样出片。
- ```html
- <script src="../lib/scenes.js"></script>
- <script>
- const TL = SC.build([
- { id: 'hook', dur: 3.0, draw: (g, lt, c) => drawHook(g, lt, c) },
- { id: 'point', dur: 4.0, trans: { in: 'slide', dur: 0.5 }, draw: (g, lt, c) => drawPoint(g, lt, c) },
- ], { lead: 0.4, tail: 0.6 });
- function frame(t) { SC.paint(g, TL, clamp(t, 0, TL.dur - 1e-4), { W, H, bg: TH.bg }); }
- </script>
- ```
- | 转场 | 观感 | 什么时候用 |
- |---|---|---|
- | `fade` | 交叉溶解 | **文字类片子的默认**,讲理、讲解、数据 |
- | `dip` | 经底色过渡 | 两段情绪差得远;或两镜版式完全换掉 |
- | `slide` | 下一镜整块推入 | 满幅图形 / 照片 / 色块之间 |
- | `push` | 两镜贴着一起走 | 同上,更要方向感(流程往下走) |
- | `rise` | 下一镜从下方升起 | 竖屏、解说卡(两镜共用左边距时才稳) |
- | `zoom` | 变焦穿过 | 满幅画面之间,强调「一口气穿过去」 |
- | `wipe` | 竖边扫擦 + 扫描亮线 | 科技感、数据揭示(满幅图形) |
- | `cut` | 硬切 | 节奏紧、或转场时长给 0 |
- **选型铁律:画面里有文字,就只用 `fade` / `dip`。** 带位移的转场会把上一镜的文字
- 从中间切一半推走,两镜标题还会在同一位置叠成乱码 —— 观感是「画面坏了」,不是
- 「镜头动了」。位移类转场只留给边缘没有语义的画面(满幅图形、照片、色块)。
- 五条约定(踩过的):
- 1. **每个镜头的 `draw` 必须把背景画满**。转场是按 alpha 叠加两张画,
- 镜头自己留透明,交叉溶解时会透出底色,看着像闪一下。
- 2. **镜头动画一律用局部时间 `lt`**,不要用全局 `t`;转场窗口里上一镜的 `lt`
- 正好走到它自己的末尾(不会越界),所以镜头代码不用为转场写特例。
- 3. **带转场的镜头,别在 `draw` 里再叠一层整体淡入**。转场已经在做透明度了,
- 两层同时压 alpha,前 0.3 秒会糊成一团。`ctx.trans.dur > 0` 就跳过自己那层。
- 4. **退场侧要先把内容撤干净**:转场窗口里 `ctx.role = { side:'a'|'b', p }`,
- `side==='a'` 时把内容 alpha 按 `p` 收到 0(背景照画),`side==='b'` 的内容
- 晚 `0.22 × 转场时长` 起步。这样两镜内容永不同时在场 —— 这是文字类片子做溶解
- 不翻车的关键,标准写法见 `assets/templates/explainer.html` 的 `draw` 包装。
- 5. **转场是重叠的**:总时长 = Σ镜头时长 − Σ转场时长。加了转场,片子不会变长。
- 6. `SC.expose(TL)` 把镜头表挂到 `window.__sceneTable`,配渲染器 `--scene-log` 导出 CSV;
- **镜头表总时长与 `--duration` 不一致会告警**(否则结尾静默多一截静止画面)。
- 镜头表可以整份外置,LLM 写 JSON 最省事:
- ```bash
- bash assets/render.sh explainer.html --duration=17.6 --fps=30 --story=shots.json
- ```
- ```json
- [{ "kind": "title", "id": "hook", "dur": 3.0, "title": "..." },
- { "kind": "talk", "id": "why", "dur": 3.5, "say": "...", "trans": { "in": "fade", "dur": 0.45 } }]
- ```
- ## 先看分镜,再渲全片(省时间的关键一步)
- 一支 60 秒 1080p 的片子逐帧渲要 3~10 分钟。渲完才发现「第 4 镜字太小」「转场太赶」,
- 改一轮又要几分钟。**分镜板**只取每镜中点渲一张静帧,十几秒出,一页看完:
- ```bash
- node scripts/storyboard.js my.html # 4 列网格
- node scripts/storyboard.js my.html --cols=2 --theme=chalk
- node scripts/storyboard.js my.html --story=shots.json --width=1080 --height=1920
- ```
- 产出 `<名>.storyboard/`:每个镜头一张 PNG、一页带标注的 `storyboard.html`、一张整页截图
- `storyboard.png`(贴给别人问「这样行不行」最方便)。
- **什么时候必须先跑**:
- - 镜头 >= 3 个,或总时长 >= 10 秒
- - 改了版式/文案之后要重渲全片
- - 用户还没看过这支片长什么样
- **它靠什么知道镜头表**:页面里调过 `SC.expose(TL)` 就能读到 `window.__sceneTable`;
- 没调就按总时长均分(会提示)。所以写多镜头页面时,记得 expose 一句。
- 分镜板能看出的问题:镜头时长分配、层级(标题/正文/注释大小)、有没有哪一镜是空的、
- 风格与内容的匹配度。**看不出的**:动效手感、转场是否顺、音画是否对齐 —— 那些要出片或
- `--stills` 抽帧连看。
- ## 风格:8 种视觉语言,一条命令换
- 模板决定**画什么**(标题 / 要点 / 条形图),风格决定**长什么样**(什么纸、什么墨、线多粗、
- 字多紧、入场怎么动、签名元素是什么)。`assets/lib/styles.js` 把这两层拆开了。
- ```bash
- bash assets/render.sh assets/style-film.html --duration=13 --theme=chalk
- bash assets/render.sh assets/style-film.html --duration=13 --theme=水墨 --width=1080 --height=1920
- ```
- | id | 中文 | 一句话 | 适合 |
- |---|---|---|---|
- | `riso` | 孔版印刷 | 米白纸 + 三色网点(真实网角)+ 标题套印错位 | 观点、数据、独立杂志感(**默认**,辨识度最高) |
- | `cutpaper` | 剪纸拼贴 | 四边手撕的纸片 + 锐利硬投影 + 两张纸叠着 | 故事、人物、教育 |
- | `blueprint` | 工程蓝图 | 深蓝 + 双层格网 + 四角十字标记 + 等宽字 | 技术、架构、API |
- | `chalk` | 黑板粉笔 | 墨绿板 + 双线抖动笔触 + 粉尘 + 楷体 | 教学、科普 |
- | `isometric` | 等距线稿 | 白底 + 2:1 等距立体块 + 白面遮挡 | 机制、结构、流程 |
- | `synthwave` | 霓虹复古 | 条纹太阳 + 透视地面网格 + CRT 扫描线 | 音乐、游戏、复古科技 |
- | `swiss` | 瑞士网格 | 白底 + 超大字号 + 单一信号红 + 零圆角 | 品牌、观点、发布会 |
- | `ink` | 水墨宣纸 | 宣纸纤维 + 三层洇墨 + 朱红印章色 | 国风、文化、历史 |
- **中文名也认**(`--theme=水墨`、`--theme=剪纸`)。完整选择指南、每种风格的签名元素与禁忌
- 见 `assets/STYLES.md`。
- 两个现成入口:
- ```bash
- # 八宫格:一秒一个风格,出 8 张全屏静帧,一眼挑风格
- 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
- # 一支 13 秒的风格短片(片头 / 要点 / 数据 / 片尾),支持 --story 外置文案
- bash assets/render.sh assets/style-film.html --duration=13 --fps=60 --theme=riso
- ```
- **自己写页面时,四条硬约定**(踩过,都是"画出来是黑的"这种):
- 1. `SV.card()` **必须用返回值排版**。它返回 `{x, y, w, h, ink}` —— 内容安全框。
- 每种风格能放字的地方不同(等距只给顶面、水墨只给内圈、瑞士要反白),
- 拿原始 box 硬排,字一定压边或消失。
- 2. **每个镜头的 `draw` 自己画满背景**(`SV.bg(...)`)。`SC.paint` 里 `paintShot()`
- 会先 `clearRect`,漏了这步背景就是黑的。
- 3. **`SV.overlay` 放在最外层**,在所有镜头之上。放镜头里,转场时扫描线会跟着淡入淡出。
- 4. 纹理噪点用 `SV.rng(seed)`、手抖用 `SV.boil(st, t, i, amp)`,**不要 `Math.random()`** ——
- 它们是纯函数,换机器渲出来一模一样。
- **原来的 11 个模板已经全部接上风格**,不用改一行代码:
- ```bash
- bash assets/render.sh assets/templates/bar-chart.html --theme=blueprint --duration=6
- bash assets/render.sh assets/templates/explainer.html --theme=riso --duration=18
- bash assets/render.sh assets/templates/vertical-card.html --theme=synthwave --width=1080 --height=1920
- ```
- 换的不只是配色,背景整层被换成该风格的纸纹 / 网点 / 格网 / 透视地面,
- 气泡、图标底这些可选色也跟着明暗走。机制只有一句:模板背景层判断 `TH.__style`,
- 有就走 `SV.bgCached(...)`。**`styles.js` 不需要在模板里引** —— 渲染器启动时注入,
- 所以模板可以单独拷走、也可以在临时目录里跑测试,不会因为相对路径 404 被判失败。
- 哪种模板配哪种风格顺手,见 `assets/STYLES.md` 末尾的匹配表。
- ### 镜头类型:8 种,一条 JSON 排顺序
- `style-film.html` 内置 8 种镜头。给 `--story` 就是整份替换(给了 6 个镜头就渲 6 个,
- 不是只覆盖前 4 个):
- | id | 用途 | 关键字段 |
- |---|---|---|
- | `hook` | 片头 | `kicker` / `lines[]` / `sub` / `badgeNum` / `badge` |
- | `points` | 要点清单(2~4 条) | `head` / `items[{n,t,d}]` |
- | `quote` | 引用(左侧粗引线 + 大字) | `text` / `by` |
- | `steps` | 流程步骤(2~4 步,带箭头) | `head` / `items[{n,t}]` / `note` |
- | `metric` | 一个大数字 + 对比条 | `head` / `value` / `unit` / `note` / `bars[{label,p}]` |
- | `compare` | 前后对比 + 结论条 | `head` / `before{label,title,note}` / `after{...}` / `conclusion` |
- | `timeline` | 时间线(节点上下交错) | `head` / `items[{n,t}]` |
- | `outro` | 片尾 | `big` / `small` |
- 每个镜头都要 `dur`(秒)。8 个镜头 = 64 种组合(8 镜头 × 8 风格)。
- ```bash
- # 现成示例:8 个镜头串成一支 26 秒的片子
- node scripts/storyboard.js assets/style-film.html \
- --story=assets/examples/story-8shots.json --cols=4 # 先看分镜板
- bash assets/render.sh assets/style-film.html \
- --story=assets/examples/story-8shots.json --theme=chalk --duration=26
- ```
- **加新镜头类型**:写一个 `shotXxx(g2, lt, c)`,从 `SHOTS[c.index]` 取数据,
- 放进 `DRAW` 映射表。三条规矩:
- - 开头必须 `backdrop(g2, lt, c)` + `chrome(g2, 1)`
- - 所有卡片用 `SV.card()` 的返回值排版,字号用 `Math.min(理想值, cb.h * 比例)` 夹一道
- - 入场用 `SV.clamp((t - 延迟) / 时长)` + `SV.enter(ST, p)`,别自己写缓动
- ## 运镜与镜头语言:assets/lib/camera.js
- 分两层,互不干扰:**第一层是参数**(从哪到哪,像素级控制),
- **第二层是意图**(推、摇、环绕,一句话一条镜头)。老代码只用第一层,不受影响。
- ### 第一层:轻运镜(治「画面死了」)
- 画面元素都到位之后还剩几秒 —— 那几秒最容易「死」,`qa.js` 会报「最长连续静止」。
- 加一点持续运镜能活过来,而且比堆装饰元素更不抢戏。
- ```js
- const cam = CAM.breath(); // 呼吸:1.4% 的持续缩放,周期 4.2s
- CAM.withCam(g, CAM.at(cam, t, W, H), W, H, () => { /* 画内容 */ });
- ```
- | kind | 用途 |
- |---|---|
- | `breath()` | 极轻缩放,专门治「画面死了」 |
- | `kenburns({from,to})` | 缓慢推拉 / 平移(照片、大图镜头) |
- | `handheld` | 手持微抖:确定性伪噪声(**不是** `Math.random()`),多 worker 结果一致 |
- | `shake` | 撞击式震动,会衰减到 0(强调、转场落点) |
- | `stack([...])` | 多个运镜叠加:位移相加、缩放相乘 |
- 两条硬规矩:**运镜前先把底色铺满**(缩放/平移会露边);
- **缩放小于 1 一定露边**,要拉远就把内容画得比视口大。
- ### 第二层:镜头语言(一行字一条镜头)
- 专业分镜表里写的是「推镜,6 秒,缓入缓出」,不是 `from:[0,0,1] to:[0.02,0,1.06]`。
- 第二层让你直接把那句话喂进去 —— 这也是 [cinecode](https://github.com/sarpstar/cinecode)(MIT)的思路,
- 本项目按 Canvas 2D 重写了运动、缓动与手感,不是照抄。
- ```js
- const line = window.__h2vCamera !== undefined ? window.__h2vCamera : CFG.camera;
- const cam = (!TRANSPARENT && line && typeof CAM !== 'undefined') ? CAM.move(line, T, DUR) : null;
- if (!cam) { drawScene(T); return; } // 没镜头:一条像素都不变
- g.fillStyle = TH.bg; g.fillRect(0, 0, W, H); // 先铺底,否则露边
- CAM.begin(g, cam, W, H); // 内含 save()
- drawScene(T);
- CAM.end(g); // 内含 restore()
- ```
- `move()` 返回 `{ scale, tx, ty, rot, blur, bgScale, ... }`,**`tx/ty` 是比例不是像素**
- (`0.02` = 画宽的 2%),换分辨率不用改数值。
- **12 个运动**(`CAM.list()` 一次打印全部):写分镜先想「观众该感觉到什么」,再挑名字。
- | 名字 | 中文 | 感觉 | 默认 |
- |---|---|---|---|
- | `dolly in` | 推镜 | 亲近、紧张、"这件事重要" | 4s / inertia |
- | `dolly out` | 拉镜 | 孤立、释放、交代环境 | 5s / inOut |
- | `pan` | 横摇 | 扫视、跟随、把两件事连起来 | 4s / inertia |
- | `tilt` | 纵摇 | 仰视=敬畏,俯视=发现与重量 | 3.5s / inOut |
- | `orbit` | 环绕 | 审视、强调、英雄感 | 6s / inertia |
- | `crane` | 升降 | 希望、尺度、从上方揭示 | 5s / inOut |
- | `handheld` | 手持 | 在场、紧迫、纪实 | 跟镜头等长 |
- | `dolly zoom` | 变焦推拉 | 醒悟、不安、失真(**一片只用一次**) | 3.5s / inOut |
- | `rack focus` | 拉焦 | 注意力从一处移到另一处 | 1.2s / inOut |
- | `whip pan` | 甩镜 | 能量、跳切、喜剧 | 0.32s / inOut |
- | `push to` | 推近细节 | "看这里":线索、一个表情 | 3s / inOut |
- | `static` | 固定 | 让主体或光自己动 | 不动 |
- **一句话的语法**(容错优先,中英文混写都认):
- ```
- <运动名> [, <时长>] [, <缓动|速度>] [, <方向/锚点>]
- ```
- ```js
- 'dolly in, 6s, slow ease-in-out' // 推镜 · 6 秒 · 幅度调慢
- 'pan, 5s, medium, left' // 横摇 · 5 秒 · 往左
- 'handheld, 1' // 手持 · 幅度 1(时长跟镜头走)
- 'whip, 0.3s' '推镜,3s,慢' // 甩镜 / 中文写法
- ```
- - **时长**只认带单位的数字(`6s` / `6秒`);裸数字是**幅度**(`handheld, 1`),
- 只有该运动本身没有默认时长(`handheld` / `static`)时才当秒数。
- - **5 种缓动**:`linear` / `ease-in` / `ease-out` / `ease-in-out` / `inertia`。
- `inertia = 0.35·linear + 0.65·smoothstep` —— 两端都保留速度,所以镜头进、出都不"停死",
- 切点落在运动中间时不会看着像卡了一下。
- - 速度词(`slow` / `fast` / `慢` / `快`)**只改幅度不改时长**,时长仍由 `--snap-shots` 对齐拍点。
- **三条护栏,写代码时不用自己算**:
- 1. **防露边是默认的。** 所有运动都保证 `scale ≥ 1`,位移量按放大余量裁剪:
- `maxT = (scale - 1) / 2`,放多大就最多能平移多少画幅。想推 8% 就最多横移 4%,
- 写超了会被夹住 —— 宁可镜头少动,不露黑边。测试里 200+ 个时刻逐个验证过。
- 2. **同一帧永远长一样。** 手持抖动用正弦叠加 + 固定种子,不用 `Math.random()`;
- `move(line, t, dur)` 是 `t` 的纯函数,多 worker 并行渲染结果一致。
- 3. **`RETIME` 不重算镜头。** 换主题、改时长时用 `CAM.retime(line, newDur)` 只改速度,
- 不重新解析字符串。
- **CLI 上怎么用**:
- ```bash
- node scripts/render-video-seek.js page.html --camera='dolly in, 6s, slow' # 全片统一
- node scripts/render-video-seek.js page.html --camera=auto # 按镜头类型自动配
- node scripts/render-video-seek.js page.html --camera=off # 关掉,对比用
- ```
- `--camera=auto` 的导演逻辑在 `assets/style-film.html` 的 `AUTO_CAM` 表里,可按片子改:
- | 镜头 | 配什么 | 为什么 |
- |---|---|---|
- | `hook` | `dolly in` | 第一秒就要有"往前走"的感觉 |
- | `points` | `pan` | 扫过几条要点 = 一条视线把它们连起来 |
- | `metric` | `push to` | 数字是线索,推近 |
- | `quote` | `dolly in` | 让观众靠近那句话 |
- | `steps` / `compare` | `tilt` | 上下比较,眼睛自然会往下走 |
- | `timeline` | `crane` | 升降最能交代"一条时间线有多长" |
- | `outro` | `dolly out` | 拉远 = 收束、离开 |
- 优先级:代码里 `shot.camera`(字符串)> `window.__h2vCamera`(注入)> `CFG.camera`;
- `shot.camera: null` 和 `--camera=off` 都能把某个镜头/整片钉成不动。
- ## 素材库:图标 / 人物 / 图形
- 想画图标、箭头、卡片、人物,不用找图、也不用从零写 path —— `assets/lib/` 里有三个零依赖库:
- | 库 | 提供 |
- |---|---|
- | `shapes.js` | 40+ 线性图标(`SH.icon(g,'bolt',x,y,48,{color})`)、卡片 / 胶囊 / 箭头 / 正交连接线 / 虚线框 / 进度弧、网格 / 点阵 / 柔光 / 暗角 / 流动极光 / 胶片颗粒 |
- | `figures.js` | 参数化扁平小人:`FIG.draw(g, FIG.preset('dev', {x,y,h,t,pose:'wave',mood:'happy'}))`,发型 / 表情 / 姿势 / 配色全可调,自带对话气泡 `FIG.say()`;`FIG.shade(hex, -0.14)` 取同色系深浅一档 —— 袖子和上衣必须差一档,否则手会像浮在衣服上的色块 |
- | `camera.js` | 见上 |
- **为什么是代码画的元件,不是预置图片素材包**:版权干净(没有一张外部图)、
- 风格必然统一(同一套圆角线宽、跟着主题走)、任意分辨率都清晰、不占体积。
- **刻意不做**卡通人物位图包 / 标志性建筑照片包 —— 版权说不清、风格和用户自己的画面打架,
- 还会把仓库撑成几十 MB 的二进制库。要人物就用 `figures.js` 参数化生成。
- ```js
- SH.icon(g, 'bolt', x, y, 48, { color: TH.accent, width: 2.5 });
- SH.card(g, { x, y, w, h }, { fill: TH.panel, stroke: TH.faint, radius: 18 });
- FIG.draw(g, FIG.preset('host', { x: W * 0.22, y: H * 0.84, h: H * 0.42, t, pose: 'wave' }));
- ```
- ## 中文字体与跨机器一致
- 默认用系统字体(`Microsoft YaHei` / `PingFang SC`)。**这意味着"确定性"只在单机成立**:
- 同一个 HTML 换台没有这款字体的机器(比如 Mac),字形就会变。
- - 只是本机出片 → 不用管。
- - 要跨机器/跨人复现 → 自己内嵌一份子集字体:
- ```css
- @font-face { font-family: 'MyCJK'; src: url('fonts/subset.woff2') format('woff2'); font-display: block; }
- ```
- 子集化(只保留画面里真正用到的字,一个思源黑体 1.38MB → 约 300KB):
- 装 `fonttools` 后 `pyftsubset 源字体.ttf --text-file=<把文案导出成 txt> --flavor=woff2 --output-file=subset.woff2`。
- **只统计会画到画面上的字**——把注释里的中文也算进去,子集会胖很多倍。
- `qa.sh` 会检查字体可用性,并在「声明的字体其实没生效(悄悄回退了)」时给出警告。
- ## 程序化电影:一个世界,一条镜头轨迹(v2.0)
- 在这之前,所有模板都是「一镜一画」:每个镜头画到自己的离屏画布,再转场合成。
- 这套结构能出很干净的图表和卡片,但有三件事做不到:
- - 镜头**推过去看某个东西** —— 下一镜里那东西已经没了,因为每镜都是新画布;
- - 镜头**穿过**一个空间 —— 一条街、一列门、一层层结构,穿不过去;
- - **光随时间变** —— 窗外的天从黄昏暗到夜,只能靠叠一层半透明黑。
- v2.0 加了三层来补这三件事。三个库互相独立,可以只用其中一个。
- ### 空间:`assets/lib/space.js`
- 不是 3D 引擎(没有网格、没有光照模型、没有 z-buffer),只做一件事:
- **让镜头在一个连续空间里移动**。物体是贴在空间里的平面片,按深度排序、按距离缩放、加雾。
- ```js
- const cam = SP.cam({ pos: [0, -300, -1500], look: [0, -250, 400], fov: 46, w: W, h: H });
- const p = SP.project(cam, [120, 0, 600]); // → { x, y, z, s, vis }
- // x,y 屏幕像素 · z 相机深度 · s「1 世界单位 = 多少像素」
- ```
- | API | 用途 |
- |---|---|
- | `SP.cam({pos, look, fov, roll, w, h})` | 建相机。`roll` 做视角滚转(Pong 变通道那种) |
- | `SP.project(cam, [x,y,z])` | 投影。`vis=false` 表示在近裁剪面之后 |
- | `SP.sort(cam, items)` / `SP.draw(g, cam, items)` | 深度排序 / 排序后逐个回调 |
- | `SP.fog(cam, z, {near, far, max})` | 距离雾。伪造深度最便宜也最有效的一招 |
- | `SP.lerpCam(a, b, k)` / `SP.track(keys, t)` | 机位插值 / 关键帧相机 |
- | `SP.ring / grid / helix / rowZ / orbit` | 布局:摆物体最费事的是算坐标 |
- **坐标约定**:世界 x 右、y **下**、z 朝远离观众。相机在地面之上,所以 `y` 是负数。
- 这一条写错,楼会翻到天上去 —— 而且画面照画,不会报错。
- **手性别凭直觉改**:`basis()` 里那三行(`r = f × worldUp`、`u = f × r`)反了就是
- 左右颠倒 + 上下颠倒。`test/space.test.mjs` 里全是对方向的断言,改坏了会立刻红。
- ### 笔触:`assets/lib/brush.js`
- 版式模板一次画几十个元素,`fillRect` 量级够用。但「十万笔」「每帧百万笔」那种片子
- 不是靠更精细的代码,是靠数量级:单笔在十万笔里根本看不出来,能看出来的是整体的
- 疏密、方向、留白。这一层专门解决「量」。
- ```js
- const f = BR.field(120000, {
- seed: 7, area: { x: 0, y: 0, w: W, h: H },
- angle: BR.vortex(W / 2, H / 2, 1.0), // 方向场:漩涡
- len: [8, 44], wid: [1.1, 3.6], // 每笔长度 / 粗细
- color: BR.jitterColor([38, 58, 92], 0.10, 7, 6), // 同色系 6 档
- });
- BR.draw(g, f, { alpha: 0.9, reveal: k }); // reveal: 逐笔生长
- ```
- | API | 用途 |
- |---|---|
- | `BR.field(n, opts)` | 生成笔触场(TypedArray,确定性 rng) |
- | `BR.draw(g, f, {alpha, reveal, widMul})` | 按「颜色 × 粗细」分桶批量提交 |
- | `BR.drawDots(g, f, opts)` | 点画模式(星光、纸屑、雨) |
- | `BR.morph(a, b, k)` | 两个场插值 → 「纸张聚成鸟」 |
- | `BR.textPoints(text, opts)` + `BR.snap(f, pts, {k})` | 文字轮廓采样 + 笔触吸附 → 「笔触聚成字」 |
- | `BR.vortex / wind / dir / nz` | 方向场与噪声 |
- **为什么必须分桶**:10 万次 `fillRect` 每次过一遍状态检查,实测比批量 `stroke` 慢 15~20 倍。
- 分桶后 `stroke` 调用次数从 10 万降到十几个。
- **颜色必须量化**:桶数 = 色数 × 粗细档。颜色每笔都不同时桶数等于笔数,批量提交就白做了。
- `jitterColor` 走固定档位;`field` 的 `maxColors`(默认 32)兜底,超了就把通道量化合并。
- **实测**:12 万笔生成 61ms、morph 22ms、10 万笔吸附 310ms。
- ### 光照:`assets/lib/light.js`
- 「配色」和「光」不是一回事。同一组颜色,正午的硬光和黄昏的斜光完全是两支片。
- ```js
- const L = LT.timeline([[0, 'golden'], [0.2, 'dusk'], [0.6, 'night'], [1, 'night']], u);
- LT.grade(g, W, H, L, { alpha: 0.2 }); // 全屏统一色温
- LT.radial(g, { x, y, r, color: L.sun, i: 0.4 });
- LT.vignette(g, W, H, { amount: 0.45 });
- ```
- | API | 用途 |
- |---|---|
- | `LT.kelvin(K)` | 黑体辐射近似。1900K 烛光橙 / 5600K 日光 / 9500K 阴天冷蓝 |
- | `LT.sky(t)` | 昼夜循环(0=深夜 → 0.5 正午 → 1=深夜) |
- | `LT.timeline(keys, t)` | 任意关键帧。插值用 smoothstep,不是线性 |
- | `LT.grade / exposure / vignette / bloom / flash` | 全屏调色 / 曝光 / 暗角 / 泛光 / 闪白 |
- | `LT.radial / shaft` | 径向光 / 光束(体积光的 2D 近似) |
- **环境光与主光必须分开**:只调一个就是「加滤镜」,不是「换时间」。
- `SKY` 里每个预设都有 `ambient`(阴影里的颜色)和 `sun`(受光面的颜色)。
- **grade 用 overlay 而不是 multiply/screen**:它保留明暗只改色相。
- 用 multiply 会整体变暗,用 screen 会整体发白,都不像光。
- ### 承载体:`assets/templates/program-film.html`
- 这个模板把三层串起来:一条街、两排楼、一条推进的镜头轨迹、一段从日落到深夜的光。
- 默认出片 20 秒(`CFG.DUR`),改 `LINES` 换文案,改 `CFG.sky` 换光线时间轴。
- ```bash
- h2v new my-film --template=program-film
- # 改文件顶部的 CFG:DUR / sky / LINES
- h2v render my-film.html --duration=20 --fps=30
- ```
- `h2v new` 会把 `brush.js / space.js / light.js` 一起拷到 `./lib/` 并改好路径 ——
- v2.0 起不再写死 `camera.js`,模板引用哪个就拷哪个。
- ### 现在能做什么、做不了什么
- | 能做 | 例子 |
- |---|---|
- | 镜头在空间里推、摇、穿行 | 沿着一条街走、穿过一列门 |
- | 镜头「移过去讲某个东西」 | 3D 细胞课件那种「讲到核糖体,镜头转过去」 |
- | 十万级笔触的质感 | 油画、星空、灯海、纸张聚成鸟 |
- | 光随时间变 | 黄昏 → 夜 → 晨 |
- | 视角连续变换 | 平面游戏视角滚转成 3D 通道 |
- | 做不了 | 原因 |
- |---|---|
- | 阴影贴图 / 屏幕空间反射 / PBR | 画家算法没有 z-buffer,阴影只能靠「高度 AO + 方向光」暗示 |
- | 逐像素 shader(流体、火焰、折射) | Canvas 2D 没有可编程管线 |
- | 次表面散射、真实金属反射 | 用半球光 + Blinn 高光 + 逐面取色去「暗示」,不是物理模拟 |
- | 百万级粒子每帧现算 | 单帧 100 万次 draw 调用在浏览器里是秒级。要么预渲染,要么不到这个量 |
- > v2.1 起,**逐面着色**(Lambert + Blinn + 边缘光 + 半球光 + AO)已经有了,
- > 见下一节。上面「平面着色」的限制只适用于 `space.js` 的 billboard 路径。
- 需要真 3D 时:直接用 `three.js` + 我们这套渲染器(它只认 canvas,不关心你怎么画)。
- `--alpha` 透明输出也可以把 WebGL 图层叠到实拍上。
- ## 实体世界:能受光、能转身、有材质(v2.1)
- `space.js` 的 billboard 解决「空间连续」,但平面片没有法线 —— 不能着色、
- 不能转身、做不出曲面。要「像真的」,需要**面**。
- 三层,按依赖顺序加载:
- ```html
- <script src="../lib/space.js"></script>
- <script src="../lib/light.js"></script>
- <script src="../lib/solid.js"></script> <!-- 实体:几何 + 着色 -->
- <script src="../lib/atmos.js"></script> <!-- 大气:雾 / 光束 / 星芒 / 颗粒 -->
- <script src="../lib/lens.js"></script> <!-- 镜头:轨道 / 对数推拉 / 呼吸 -->
- ```
- ### `solid.js`:几何 + 着色
- ```js
- /* 几何:全部是纯数据,生成一次,每帧只投影 */
- const tower = SD.lathe([[24,0],[22,-50],[17,-150],[12.5,-224]], 24, { color:[230,226,216] });
- const ball = SD.sphere(50, { seg: 24, rings: 16, color:[200,120,90], mat:'matte' });
- const rock = SD.terrain(132, 132, 1700, 1700, (u,v)=>H(u,v), { color:[104,100,96], mat:'rock' });
- const pipe = SD.tube([[0,0,0],[0,-100,40]], r => 6 - 2*r, { seg: 10 });
- const crate = SD.box(40, 40, 40, { color:[120,90,60] });
- /* 逐面取色:岩石分层、金属污渍、地形渐变。不给就是整块单色 */
- rock.colorBy = (x, y, z) => y > 0 ? [40,36,36] : [96 + y*0.2, 98, 104];
- rock.bump = 0.24; // 表面粗糙度(扰动法线,不是加几何)
- /* 变换在生成时算好,不每帧算 */
- const placed = SD.xform(crate, { p:[200, -50, 300], ry: 0.7, s: 1.4 });
- /* 光照:自动布光(以机位为基准,永不逆光) */
- const L = SD.keyLight(LT.sky('dusk'), cam, { azimuth: -40, elev: 24, fill: 0.2 });
- SD.draw(ctx, cam, [tower, ball, rock, placed], L);
- ```
- **材质**:`matte` / `rock` / `metal` / `glass` / `emissive` / `water` / `skin`。
- **性能**:17,000 面 / 1080p 单帧 20–45ms。面数在生成侧控制(`seg` / `rings` / `terrain` 的网格数)。
- 三个必须知道的约定:
- 1. **`dir` 是「从物体指向光源」**。放在相机同侧才是正面受光;放反了正面全黑,
- 而灯还亮着,很难一眼看出是光的问题。用 `keyLight()` 就不会错。
- 2. **颜色要过色调映射**。线性乘出来的值直接当 sRGB 用会整体偏暗,
- 别以为是材质色选错了。`light()` 内置 1K 查找表做曝光 + 高光滚降 + gamma。
- 3. **绕序写反不会报错**,只会出现「太阳从地下照上来」。生成器内部有 `orient()`
- 自动校正;自己拼 `fromFaces()` 时要给对。
- ### `lens.js`:镜头语言
- ```js
- /* 球坐标机位:az 绕主体转、el 升降、dist 推拉 */
- const cam = LN.orbitCam([0,-200,0], { az: 0.6, el: 0.1, dist: 560, fov: 34, w, h });
- /* 轨道关键帧:在参数空间插值 —— 镜头绕主体转,不穿模 */
- const cam2 = LN.orbitTrack([[0,{az:0,dist:900}], [6,{az:2.4,dist:300}]], target, T);
- /* 对数推拉:16 倍推近,前快后慢 */
- const cam3 = LN.push(target, { from: 1500, to: 92, u, ease: LN.EASE.inOutCubic });
- /* 给半径 + 景别,自动算距离(大远景 / 远景 / 中景 / 近景 / 特写) */
- const d = LN.distFor(120, 'close');
- /* 手持呼吸:三个不同频率的正弦叠加,不是随机抖动 */
- LN.apply(cam, LN.handheld(T, { amp: 0.9, speed: 0.8, seed: 3 }));
- ```
- ### `atmos.js`:介质与后期
- ```js
- AT.sky(ctx, W, H, { horizon: 0.55, stops:[[0,'#0b1322'],[1,'#e6a05f']], band:'#ffb871', bandX: W*0.7 });
- AT.stars(ctx, W, H, { horizon: 0.55, n: 300, t: T, i: 0.8 });
- AT.haze(ctx, W, H, { y: 0.50, h: 0.16, color:'#6a4a44', i: 0.42 });
- AT.beam(ctx, { x, y, angle: -2.9, len: 1700, w0: 10, w1: 380, spread: 0.3, i: 0.4, rays: 58 });
- AT.glow(ctx, { x, y, r: 120, color:'#ffe3b4', i: 0.6 });
- AT.flare(ctx, { x, y, len: 160, color:'#fff6dc', i: 0.4 });
- AT.water(ctx, W, H, horizonY, { t: T, x: sunX, rows: 46 });
- AT.grain(ctx, W, H, { i: 0.05, t: T });
- ```
- 画这些的顺序就是「什么挡住什么」:**天空 → 星 → 水 → 远景 3D → 雾 → 近景 3D → 光 → 后期**。
- 雾插在两次 3D 绘制之间是有意的 —— 一张 z-buffer 做不到「只雾远景」,
- 分层反而能精确控制。
- ### `scripts/foley.js`:程序化音效
- ```bash
- node scripts/foley.js --list
- node scripts/foley.js --out=bed.wav --dur=41 --preset=lighthouse
- node scripts/foley.js --out=bed.wav --dur=20 --events=foley.json
- h2v render film.html --duration=41 --audio=bed.wav # 直接混进成片
- ```
- 八个音色:`wave`(海浪)/ `wind` / `hum`(灯丝)/ `foghorn`(雾笛)/ `paper` / `brush` /
- `impact` / `chime`。全部是「噪声整形 + 双二阶滤波 + 包络」合成,带 Schroeder 混响。
- **为什么要自己合成**:外部素材有版权、节奏对不上、装不上(本项目硬依赖只有 playwright + ffmpeg)。
- 而「海浪」本质就是「低频噪声 + 周期 7 秒的慢包络 + 一层高频泡沫」,三十行代码就能做。
- ### 完整例子:`assets/templates/lighthouse.html`
- 41 秒 / 7 镜 —— 一条「一个人,一座塔,一整夜」。
- ```bash
- h2v new my-world --template=lighthouse
- h2v render my-world.html --duration=41 --fps=30 --audio=bed.wav
- ```
- 它同时演示了:实体几何(礁石 / 塔身 / 灯室)、逐面取色(岩层 / 盐渍 / 苔)、
- 球坐标环绕、对数推轨、昼夜插值(黄昏 3000K → 深夜 6800K)、射线束、星芒、
- 水面波纹、胶片颗粒,以及声音与画面的**同一个时间码**(13.6s 灯亮 = 嗡鸣淡入)。
- ## 渲染中途 ffmpeg 失败怎么办
- **帧不会丢**:渲染器在编码失败时保留 `.seek-tmp-*/` 里的全部 PNG,并打印出可直接粘贴的编码命令。
- 修好 ffmpeg 后手动编码即可,不必重截 720 帧:
- ```bash
- "$FF" -y -framerate 60 -start_number 0 -i .seek-tmp-*/frame-%06d.png -c:v libx264 -pix_fmt yuv420p \
- -crf 18 -preset medium -r 60 -movflags +faststart animation.mp4
- ```
- 顺带:`.seek-tmp-*/` 有 720 张 PNG,**约 316 MB**。成功渲染后会自动删;加 `--keep-frames`
- 可以主动留住(换画质重编码时省一次渲染)。
- > 某些沙箱/托管环境给 `fs.rmSync` 套了「批量删除保护」,一次删几十个文件会被拦下。
- > 这时渲染器会提示「逐帧目录没能自动删除」并给出路径,**成片不受影响**——手动删那个目录即可。
- > 这也是为什么有时会看到残留的 `.seek-tmp-*` 目录。
- ## 文件说明
- | 文件 | 作用 |
- |---|---|
- | `scripts/render-video-seek.js` | 渲染器内核(冻结时钟 + 逐帧 seek 截图 + ffmpeg 编码 + 报错判定),自包含 |
- | `scripts/qa.js` | 自动化验收(确定性/动感/流畅/框景/字体/报错),纯 Node 零新依赖 |
- | `scripts/qc.js` | **成片质检**:hook / 黑场 / 冻结 / 重复帧 / 亮度 / 场景切换 / 响度 / 联系表,只依赖 ffmpeg |
- | `scripts/audio-master.js` | **响度母版**:两遍 `loudnorm` 线性归一 → −14 LUFS / −2 dBTP,可选限幅 |
- | `scripts/script-check.js` | **文案自检**:单行字数 / 每镜条数 / 阅读速度 / 陈词滥调 / 有没有转折 |
- | `references/writing.md` | 文案规则全文:分叉收敛、六种转折、字数预算、陈词滥调清单、首次观看者检查 |
- | `references/style-recipe.md` | **加新风格前必读**:十一章骨架(本质/材料/色彩/字体/运动/运镜/声音/招牌动作/介质陷阱/实现映射/可变空间)、每章写到什么颗粒度、查旧风格的五问、本项目固定陷阱清单、我们做不了的清单 |
- | `scripts/lib/hide-chrome.cjs` | 「隐藏播放控件」的共享规则,渲染器与验收器用同一份,规则不会漂移 |
- | `scripts/lib/local-server.cjs` | 本地 http 静态服务器(只绑 127.0.0.1),解锁 ESM / fetch;零新依赖 |
- | `scripts/detect-env.js` | 探测本机浏览器缓存,输出该装哪个 playwright 版本 |
- | `scripts/install-deps.sh` | 一键装依赖并写配置(探测 → 装 → 落地配置文件) |
- | `scripts/bench.js` | 性能基线:量 `s/帧` 并估算长片耗时,产出 `bench/bench.md` |
- | `assets/render.sh` | 全量渲染包装器,自动解析 node 工作区与 ffmpeg 路径 |
- | `assets/smoke.sh` / `smoke.cjs` | 冒烟测试:验证 `__seek` 契约 + 试截关键帧 |
- | `assets/qa.sh` | 验收包装器,环境解析同上 |
- | `assets/animation-skeleton.html` | 动画骨架模板,已实现完整渲染契约 |
- | `scripts/lib/cues.cjs` | 字幕时间轴解析(SRT / VTT / JSON),会自动排序并修掉时长非正、首尾重叠的 cue |
- | `scripts/lib/qa-rules.cjs` | 验收判据的纯函数(框景 / 持续 / 分块 / 统计),可脱离浏览器单测 |
- | `assets/templates/*.html` | 16 个开箱即用模板(多镜头讲解片/片头/条形图/折线/大数字/时间线/竖屏卡/前后对比/流程图/解说卡/竖屏字幕卡/**程序化电影**),改 CFG 即用 |
- | `assets/templates/program-film.html` | **程序化电影**:一个世界 + 一条镜头轨迹 + 一段日光变化。笔触、2.5D 空间、光照三层串起来的最小完整例子 |
- | `assets/templates/lighthouse.html` | **实体世界**:41 秒 / 7 镜,礁石+灯塔+灯室实模、岩层取色、对数推轨、环绕、昼夜、射线束、星空、颗粒。四层(solid/atmos/lens/foley)串起来的完整片 |
- | `assets/templates/themes.js` | 三套内置主题(midnight / paper / neon),新模板用它换配色 |
- | `assets/lib/motion.js` | 动效时间库(缓动/弹簧/步进/错开),纯函数、零依赖 |
- | `assets/lib/scenes.js` | 多镜头时间轴 + 8 种转场(cut/fade/dip/slide/push/rise/zoom/wipe),纯函数、零依赖 |
- | `assets/lib/camera.js` | **两层**:运镜(推拉 / 呼吸 / 手持微抖 / 撞击震动,确定性伪噪声)+ **镜头语言**(12 个命名运动 / 5 种缓动 / 一行字解析 / 防露边),确定性 |
- | `assets/lib/space.js` | **2.5D 空间**:透视投影 / 深度排序 / 距离雾 / look-at 相机 / 关键帧轨迹 / 环形·网格·螺旋布局 |
- | `assets/lib/brush.js` | **大规模笔触**:TypedArray 笔触场 / 颜色×粗细分桶批量提交 / 形态插值 / 文字吸附 / 方向场(十万笔量级) |
- | `assets/lib/light.js` | **光照**:黑体色温 / 昼夜关键帧 / 径向光·光束 / 全屏调色·曝光·暗角·泛光 |
- | `assets/lib/solid.js` | **实体与着色**:box / lathe / sphere / tube / terrain 几何 + Lambert·Blinn·边缘光·半球光·AO + 色调映射 + 逐面取色 + 法线自校正 |
- | `assets/lib/atmos.js` | **大气与后期**:天空 / 星空 / 贴地雾 / 体积光束(射线束)/ 辉光 / 星芒 / 胶片颗粒 / 水面 / 浮尘 |
- | `assets/lib/lens.js` | **镜头语言**:球坐标机位 / 轨道插值 / 对数推拉 / 景别距离 / 手持呼吸 / 切镜表 |
- | `scripts/foley.js` | **程序化音效**:8 种音色 + 事件表 + Schroeder 混响 + 软限幅,输出 48kHz 立体声 WAV |
- | `assets/lib/shapes.js` | 图形元件:40+ 线性图标 / 卡片 / 箭头 / 正交连接线 / 背景纹理 |
- | `assets/lib/figures.js` | 参数化人物(发型 / 表情 / 姿势 / 配色)+ 对话气泡 |
- | `assets/lib/styles.js` | **风格库**:14 种视觉语言,分五个家族(印刷 / 手作 / 绘画 / 信息图 / 数字界面),`SV.bg` / `SV.text` / `SV.card` / `SV.bar` / `SV.overlay` / `SV.boil` / `SV.BEAT` / `SV.pulse` / `SV.FAMILY` |
- | `assets/STYLES.md` | 风格选择指南:每种风格的签名元素、适用场景、禁忌、加新风格的字段清单 |
- | `assets/style-film.html` | **风格短片**:片头/要点/数据/片尾 4 镜,8 风格通用,支持 `--story` 与横竖屏 |
- | `assets/style-gallery.html` | 八宫格风格样张,第 k 秒一个风格,配 `--stills` 一次出 8 张静帧 |
- | `scripts/storyboard.js` | **分镜预演**:每镜中点一张静帧 → 一页分镜板 HTML + 整页截图,渲全片前先确认 |
- ### 渲得有多慢:自己量一次,别信文档
- 不同机器差 3–5 倍(CPU、内存、画面复杂度都影响),所以这里不写「约几分钟」:
- ```bash
- npm run bench # 两个页面 × 两档分辨率 × 两种并发 → bench/bench.md
- node scripts/bench.js --frames=60 --html=assets/templates/explainer.html
- ```
- 表里给 `s/帧`(已把并发算进去)和「10s@60fps 预估」。**并发不是越大越好**:
- 超过 CPU 核数之后页面之间抢 CPU,`s/帧` 不降反升,表上能直接看出来。
- ## 设计品味另找专业分工
- 本技能只负责「环境 + 出片链路 + 质量门」。分镜方法、镜头语言、视觉风格属于设计范畴,
- 交给专门的设计类技能处理,别在这里重复造。
README.md · README · 1,067 lines
- # html-to-video · 用代码逐帧做视频
- [English](README.en.md) · **中文**
- [](https://github.com/wx4766/html-to-video/actions/workflows/ci.yml)
- [](LICENSE)
- [](package.json)
- [](docs/demo-hero.mp4)
- <sub>这段片子就是 [`docs/demo-hero.html`](docs/demo-hero.html)(447 行、零依赖)渲出来的。自己复现一遍:<br>
- `node scripts/render-video-seek.js docs/demo-hero.html --duration=10 --fps=60`</sub>
- 把 HTML / Canvas 动画**逐帧渲染成 MP4**(可配乐、可出 GIF)。
- 不是 AI 文生视频,而是:
- ```
- 写 HTML/Canvas,把画面写成 frame(t) 纯函数
- → 无头浏览器逐帧 seek 到时刻 t,截图
- → ffmpeg 编成 H.264 MP4
- ```
- 字幕、运镜、转场全在代码里,**改一行代码重渲即可**。
- ## 为什么用它
- | | |
- |---|---|
- | **确定性** | 同样的输入永远得到同样的输出,可复现、可版本管理 |
- | **可控到帧** | 任意帧率(真 60fps,不是插帧),任意时刻精确对齐 |
- | **文字完美** | 中文字体渲染正常,不会像文生视频那样糊成一团或错别字 |
- | **零费用** | 本地跑,不调任何 API |
- | **四道质量门** | 文案 `check` / 页面 `qa` / 成片 `qc` / 声音 `master` —— 四类问题分别量化,不靠眼睛 |
- | **一句话一条镜头** | 12 个命名运动 + 5 种缓动,`dolly in, 6s, slow` 直接喂进去,自带防露边 |
- | **开箱即用** | 14 个模板改个配置块就出片,不用从零学 canvas |
- | **横竖屏都行** | 模板跟视口自适应,16:9 / 9:16 换 `--width/--height` 即可,不裁切 |
- | **能出「一支片子」** | 多镜头 + 8 种转场 + 镜头运动,一个 HTML 出整支,不用渲几段再拼 |
- | **自带素材** | 40+ 图标 / 参数化人物 / 卡片箭头 / 背景纹理,纯代码零依赖零版权风险 |
- | **能叠能配** | `--alpha` 出透明层叠到实拍上;`--srt` 挂外部字幕时间轴 |
- | **渲一次发一堆** | `--gif` / `--poster` / `--batch` 一次渲染出成片、动图、封面、批量任务 |
- 适合:讲解动画、动态图解、产品演示、数据可视化动画、游戏宣传片。
- 不适合:实拍感 / 氛围镜头(那个应该走 VideoGen)。
- ### 和 Remotion / Motion Canvas 什么关系
- 同类工具里最常被拿来比的三个,说清楚各自适合什么,省得你上手才发现选错:
- | | html-to-video | Remotion | Motion Canvas |
- |---|---|---|---|
- | 心智模型 | 一个 HTML 文件 + `frame(t)` 纯函数 | React 组件 + `useCurrentFrame()` | TS 生成器 + 场景图 |
- | 起步成本 | 复制模板、改顶部 `CFG` | 建 React 工程、学组件与 API | 装编辑器、学场景 API |
- | 构建步骤 | 无,浏览器直接跑 | 要打包 | 要构建 |
- | 工程化 | 测试 / CI / 六维 QA | 成熟生态、Lambda 云端渲染、播放器组件 | 编辑器体验好,适合手工精修 |
- | 许可 | MIT | 个人与 ≤3 人团队免费,4 人以上需商业许可 | MIT |
- **一句话选择**:要在 React 应用里内嵌视频编辑器、或大规模云端渲染 → Remotion 更合适;
- 要手工一帧帧精修分镜 → Motion Canvas 更合适;
- **只想把一屏现成的 HTML 变成 mp4,不想为此建个工程 → 用这个**。
- 尤其是「AI 写出来的 HTML 动画想变成视频」这种场景:不需要它懂框架,
- 输出一个能跑的 HTML 就够了,剩下交给渲染器。
- ### 交给 AI / 脚本跑:最舒服的一条路
- 这个工具的三条性质凑在一起,正好是「无人值守出片」需要的:
- | 性质 | 带来的好处 |
- |---|---|
- | **镜头表是 JSON** | 让模型产出 `[{kind,dur,title}, ...]` 比让它写 500 行 canvas 代码可靠得多 —— 改片子就是改 JSON |
- | **同输入同输出** | 改一句文案重渲,其它帧**逐像素不变**,可以做自动回归,不用担心「顺手改坏了别处」 |
- | **四道质量门** | `check` 管文案、`qa` 管页面、`qc` 管成片、`master` 管声音,全部输出数字与 JSON,脚本能自己判断渲坏了没有 |
- 于是闭环是:LLM 写 JSON/HTML → 渲 → QA 自己判红绿 → 红了就照着报告改 → 再渲。
- 人只在最后看一眼成片。
- ## 16 个开箱即用模板
- 拷贝一个,改顶部 `CFG` 里的文案和数据,直接出片。
- | | 模板 | 用途 |
- |---|---|---|
- | [](docs/demo-explainer.mp4) | `assets/templates/explainer.html` | **多镜头讲解片**:片头 → 人物+气泡 → 分条要点 → 条形对比 → 片尾,镜头带转场,可喂 JSON 镜头表;横屏三条要点自动并排成三栏,竖屏另有上下版式 |
- | [](docs/demo-title-card.mp4) | `assets/templates/title-card.html` | **片头标题卡**:主标题逐字弹入 + 副标题 + 标签 |
- | [](docs/demo-bar-chart.mp4) | `assets/templates/bar-chart.html` | **条形图 / 排名**:条形依次生长,数值同步滚动,第一条高亮 |
- | [](docs/demo-line-chart.mp4) | `assets/templates/line-chart.html` | **折线趋势**:折线生长 + 数据点亮起 + 末点数值浮标 |
- | [](docs/demo-number-counter.mp4) | `assets/templates/number-counter.html` | **大数字 / KPI**:从 0 滚到目标值 + 涨跌标签 + 进度条 |
- | [](docs/demo-timeline.mp4) | `assets/templates/timeline.html` | **时间线 / 流程**:中轴生长,节点逐个点亮 |
- | [](docs/demo-compare.mp4) | `assets/templates/compare.html` | **前后对比**:左右两栏对照,底部结论条收口 |
- | [](docs/demo-flow-steps.mp4) | `assets/templates/flow-steps.html` | **流程图动画**:步骤依次点亮,当前步高亮外扩 |
- | [](docs/demo-subtitle-card.mp4) | `assets/templates/subtitle-card.html` | **逐句解说卡**:一句话一句地出 + 分段进度条,可挂 SRT |
- | [<img src="docs/demo-vertical-card.gif" width="150" alt="竖屏卡">](docs/demo-vertical-card.mp4) | `assets/templates/vertical-card.html` | **竖屏 9:16 卡**:大字标题 + 大数字,抖音 / 视频号 / Reels 用 |
- | [<img src="docs/demo-vertical-subtitle.gif" width="150" alt="竖屏字幕卡">](docs/demo-vertical-subtitle.mp4) | `assets/templates/vertical-subtitle.html` | **竖屏字幕卡**:`**关键词**` 自动高亮,原生 9:16 版式 |
- | [<img src="docs/img/preview-quote-card.jpg" width="150" alt="引言卡">](docs/img/preview-quote-card.jpg) | `assets/templates/quote-card.html` | **引言卡 / 金句**:大引号压底 + 引文逐行推进 + 出处短线,访谈 / 书摘 / 播客切片用 |
- | [<img src="docs/img/preview-chapter-card.jpg" width="150" alt="章节卡">](docs/img/preview-chapter-card.jpg) | `assets/templates/chapter-card.html` | **章节卡 / 过渡页**:序号水印 + 标题 + 章节进度点,把长片切成几段 |
- | [<img src="docs/img/preview-ui-showcase.jpg" width="150" alt="界面演示">](docs/img/preview-ui-showcase.jpg) | `assets/templates/ui-showcase.html` | **界面演示**:窗口推入 + 缓推 + 两块聚光标注,产品发布 / 功能更新用;也可换成真实截图 |
- | [<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 三层能力的最小完整例子 |
- | [<img src="docs/preview-solid-dusk.png" width="150" alt="实体渲染">](docs/preview-solid-beam.png) | `assets/templates/lighthouse.html` | **实体渲染 / 场景片**:礁石、海、灯塔全是带法线的实体面,逐面着色。41 秒 7 镜,岩层 / 盐渍 / 苔按高度取色,光束扫出二十四海里。v2.1 的能力样本 |
- > 动图只为让你看见「它在动」;**点动图打开原片**看真实画质(横屏 1080p,竖屏 1080×1920)。
- > 静帧大图在 `docs/preview-*.png`。
- ```bash
- cp assets/templates/bar-chart.html my-video.html
- # 改 my-video.html 顶部的 CFG:title / data / note
- bash assets/render.sh my-video.html --duration=6 --fps=60
- ```
- ### 横屏 / 竖屏:换两个参数就行
- 模板都按视口设画布,**不用改代码**:
- ```bash
- bash assets/render.sh title-card.html --duration=6 --fps=60 # 1920×1080
- bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1080 --height=1920 # 9:16
- bash assets/render.sh title-card.html --duration=6 --fps=60 --width=1280 --height=720 # 720p
- ```
- 模板内部用三档缩放落版:`SX = W/1920`(横向)、`SY = H/1080`(纵向)、
- `SF = √(SX·SY)`(字号 / 线宽)。1920×1080 下三者都是 1,所以默认输出保持不变;
- 换竖屏时字号不缩、版式铺开。自己写的动画照这三行来,就不会出现「改了 --width 只截到左上角」。
- > 渲染器现在会主动量画布尺寸,比视口小会明确告警,不再静默出半张图。
- ### 一稿多发:一条命令出全套平台比例
- 同一条片子要发抖音、小红书、B 站,剪辑软件里得一个比例一个序列、导一次盯一次。
- 这里版式本来就是参数化的,多渲一遍只是多一次循环:
- ```bash
- bash assets/render.sh bar-chart.html --duration=8 \
- --presets=douyin,xiaohongshu,square --out=dist/chart.mp4
- ```
- ```text
- dist/chart-douyin.mp4 1080×1920 抖音 / 快手 / 视频号
- dist/chart-xiaohongshu.mp4 1080×1440 小红书 3:4
- dist/chart-square.mp4 1080×1080 方版 1:1
- ```
- | 预设 | 尺寸 | 给谁用 |
- |---|---|---|
- | `douyin` / `tiktok` / `vertical` | 1080×1920 | 抖音、快手、视频号、Reels、Shorts |
- | `xiaohongshu` / `xhs` | 1080×1440 | 小红书 3:4 |
- | `instagram` / `ig` | 1080×1350 | IG 信息流 4:5 |
- | `square` | 1080×1080 | 方版 1:1 |
- | `bilibili` / `youtube` / `landscape` | 1920×1080 | 横屏 16:9 |
- 只想要一个尺寸用 `--preset=xiaohongshu`。**预设名拼错直接报错并列出可用名字**,
- 不会悄悄按 1920×1080 渲一版比例错误的片子。
- 一句实话:`--presets` 只保证**尺寸**对,不保证**构图**好看。9:16 和 16:9 的信息密度不同,
- 同一条内容在 3:4 上可能偏挤 —— 出来自己看一眼,该调字号就调。
- 另外,竖屏底部那块留白**是故意的**:平台进度条和按钮压在那儿,模板给烧录字幕留了 15% 安全区。
- ### 配音:没给时长,就按音频长度出片
- 真实工作流是「写文案 → 配音 → 配画面」,不是先定 6 秒再想办法把配音塞进去:
- ```bash
- bash assets/render.sh title-card.html --audio=voice.m4a --story=shots.json
- # ▸ audio: 音频 12.48s,未指定 --duration → 视频按音频定长(12.5s,向上取整到整帧)
- ```
- - **向上取整到整帧**:少半帧就会把最后一个字的尾音削掉。
- - 显式给了 `--duration` 且和音频差超过 0.35s 会明确告警 —— 说清差多少、伤在哪边。
- 旧版本这里会静默出一支短片:画面后半段整段消失,日志却只有一句 `✓ Done`。
- - `--audio-fit=pad`:音频比视频短时补静音,保住整段画面(默认 `trim` 按音轨收尾)。
- 一个必须说清的边界:`trim` 下成片**不会精确等于音频秒数**。视频流是 `-c:v copy`
- 直接复制的,ffmpeg 只能按帧包边界收尾,实测会多留 0.3–0.5s。毫秒级对齐得重编码,
- 那是拿画质换精度,不值得。
- ### 卡点:让切点落在拍上
- 所有"看着专业"的片子都遵守同一条潜规则:**切点落在拍上**。
- 手工对齐是数着秒表挪关键帧,改一句文案又得重来。把拍点算出来交给程序,
- "卡点"就从手感变成了参数:
- ```bash
- bash assets/render.sh style-film.html --audio=bgm.mp3 --beats --snap=beats
- # ▸ 节拍: 120.14 BPM · 20 个拍点 · 首拍 0.49s · 置信度 0.85
- # ▸ 时长对齐拍点: 25.2s → 25.5s(+0.3s)
- ```
- - `--beats` 直接分析 `--audio` 那条音轨;`--beats=beats.json` 用预先算好的网格
- (同一个 BGM 出多条片子时别反复分析)。
- - `--snap=beats` 把总时长吸到下一个拍点 —— 成片不会"差 0.2 秒收在半个拍上"。
- - `--snap-shots` 把**每个镜头**的时长量化到整拍,这才是"切点真的落在拍上"。
- 改动会逐条打印(`3.60s → 3.50s`),幅度超过 25% 会警告 —— 节奏变了得让你知道。
- - 模板里也能吃到拍点:`window.__beats` 有 `bpm / beats / downbeats / offset`,
- 风格库提供 `SV.pulse(t)`(拍点处为 1、之后衰减)和 `SV.beatPhase(t)`。
- 分析器是零依赖的(`scripts/beats.js`):ffmpeg 解成 22.05kHz 单声道 →
- 对数能量通量 → 自相关估周期 → 扫相位。实测 120BPM 鼓点误差 < 2BPM、相位误差 ~9ms;
- 纯人声测不出稳定 BPM 时会明确报警(旁白本来就该按句子切,不该按拍切)。
- ```bash
- node scripts/beats.js bgm.mp3 --out=beats.json # 单独跑,看 BPM 与置信度
- ```
- ### 镜头:一行字一条镜头
- 切点解决了"什么时候换",镜头解决"换的时候画面怎么动"。
- 分镜表里写的是「推镜,6 秒,缓入缓出」,不是 `from:[0,0,1] → to:[0.02,0,1.06]` ——
- 现在可以直接把那句话喂给渲染器:
- ```bash
- bash assets/render.sh style-film.html --camera='dolly in, 6s, slow ease-in-out'
- bash assets/render.sh style-film.html --camera=auto # 按镜头类型自动配
- bash assets/render.sh style-film.html --camera=off # 关掉,做 A/B 对比
- ```
- ```js
- // 模板里就两行
- const cam = CAM.move(CFG.camera, t, DUR); // ← 解析这句话
- CAM.begin(g, cam, W, H); drawScene(t); CAM.end(g);
- ```
- **12 个运动**,每个对应一种"观众该感觉到什么":
- | 运动 | 感觉 | 运动 | 感觉 |
- |---|---|---|---|
- | `dolly in` 推镜 | 亲近、紧张、"这件事重要" | `handheld` 手持 | 在场、紧迫、纪实 |
- | `dolly out` 拉镜 | 孤立、释放、交代环境 | `dolly zoom` 变焦推拉 | 醒悟、不安(一片只用一次) |
- | `pan` 横摇 | 扫视、跟随、把两件事连起来 | `rack focus` 拉焦 | 注意力从一处移到另一处 |
- | `tilt` 纵摇 | 仰视=敬畏,俯视=发现与重量 | `whip pan` 甩镜 | 能量、跳切、喜剧 |
- | `orbit` 环绕 | 审视、强调、英雄感 | `push to` 推近细节 | "看这里":线索、一个表情 |
- | `crane` 升降 | 希望、尺度、从上方揭示 | `static` 固定 | 让主体或光自己动 |
- 三个不用操心的细节:
- - **不会露黑边**。所有运动都保证 `scale ≥ 1`,位移按放大余量裁到 `(scale-1)/2` ——
- 想推 8% 就最多横移 4%,写超了会被夹住。200+ 个时刻在测试里逐个验证过。
- - **不会抖得不一样**。手持用正弦叠加 + 固定种子,不是 `Math.random()`;
- `move()` 是 `t` 的纯函数,并行渲染的帧完全一致。
- - **换分辨率不用改数值**。`tx/ty` 是比例(`0.02` = 画宽 2%),不是像素。
- `npx html-to-video camera` 一次列全 12 个运动和写法;`--camera=auto` 的导演逻辑在
- `assets/style-film.html` 的 `AUTO_CAM` 表里,可以按片子改。
- ### 成片质检:`h2v qc`
- `qa.sh` 查页面,`qc` 查**已经编好的 mp4** —— 编码参数、音轨、真实播放时的冻结与黑场,
- 只有解码之后才看得见:
- ```bash
- node scripts/qc.js out/film.mp4
- ```
- ```
- qc · film.mp4
- info 1920×1080 · 30fps · 20.5s · h264 · aac 48k
- hook 0.482 ✓(前 2 秒在动)
- black none ✓ freeze none ✓ dup 0 ✓
- bright 34–212 ✓
- cuts 6(1.0 / 4.0 / 7.0 / 10.5 / 14.0 / 17.5)
- loud −17.8 LUFS · 真峰值 −3.2 dBTP ⚠ 偏轻,跑 h2v master
- sheet → qc/film.sheet.png
- ```
- | 检查 | 判据 |
- |---|---|
- | `hook` | 前 2 秒相邻帧平均灰度差 ≥ 0.35(**硬规则,不过就 exit 1**) |
- | `black` / `freeze` | `blackdetect` 无 ≥0.3s 黑段 / `freezedetect` 无 ≥1s 定格 |
- | `dup` | 相邻帧完全相同的对数(抓"整段复制") |
- | `bright` | 平均亮度在 16–240(全黑全白通常是主题配错) |
- | `cuts` | 场景切换点数量与位置(对不上镜头表 = `--story` 没生效) |
- | `sheet` | 抽 9 帧拼一张联系表,一眼扫完整片 |
- hook 门槛有实测基线,不是拍脑袋:纯色静止 0.00 / 极简标题卡 0.36–0.42 /
- 加胶片颗粒 0.71 / 正常运动片 0.85–1.2。实拍或强运动片用 `--hook-min=0.5`。
- ### 响度母版:`h2v master`
- 手机外放听着小、笔记本上听着大 —— 不是错觉,是没做响度归一,平台间能差 6–8 LU。
- 目标是 **−14 LUFS / −2 dBTP**:
- ```bash
- node scripts/audio-master.js in.mp4 --video=in.mp4 --out=final.mp4
- # ▸ −17.77 LUFS → −13.90 LUFS(type=linear)· 真峰值 −1.8 dBTP
- ```
- 两遍 `loudnorm`:pass 1 只测量,pass 2 用测得值 `linear=true` 做固定增益。
- 一遍式是动态模式(边跑边压),会改变动态、抽气。三个坑已经在代码里填了:
- - **LRA 超目标时 `loudnorm` 会静默切回动态模式** —— 报告里 `type` 不是 `linear` 就明确告警。
- - **限幅后必须重新测量**,否则 pass 2 用限幅前的峰值算错增益。
- - **AAC 编码会把真峰值抬 0.5–0.7 dB**,所以带视频时目标压到 −2 dBTP。
- ### 文案自检:`h2v check`
- ```bash
- node scripts/script-check.js story.json
- ```
- ```
- 6 镜 / 20.5s / 193 字 / 9.4 字每秒
- ✗ 要改的:
- · 第 1 镜(hook)的 sub 有 17 个汉字 > 14:「渲染器自己量拍子,镜头时长量化到整拍」
- ```
- 查机器能查的:单行上限(横屏 14 字 / 竖屏 12 字)、每镜条目数(≤4)、
- 阅读速度(≤12 字/秒)、陈词滥调命中、有没有转折镜头。
- 机器查不了的(读出声打结、该砍的 30%)写在 `references/writing.md` 里 —— 那是规则,不是灵感。
- ### 给 Agent 用:`--json`
- 人读 `✓ Done: xxx.mp4 (1.2 MB · 30fps · 12s)` 没问题,Agent 只能拿正则去猜,
- 路径里带空格、中文、括号就崩。加 `--json`,stdout 只留一行结果:
- ```bash
- bash assets/render.sh title-card.html --duration=6 --json
- ```
- ```json
- {"ok":true,"exitCode":0,"output":"…/title-card.mp4","width":1920,"height":1080,
- "fps":60,"duration":6,"frames":360,"bytes":2411724,"warnings":[],"mode":"video"}
- ```
- - 进度与人读日志全部走 stderr,直接 `JSON.parse(stdout)` 即可。
- - `warnings` 是数组:参数冲突、音画长度不符、主题名不认识都进这里;空数组 = 干净。
- - `duration` 是成片**实际**时长(ffmpeg 读回来的),不是计划值。
- - `--presets` 时 `output` 变数组,另附 `presets: [{name,width,height,output,ok,bytes}]`。
- ### 换配色:改一个字段,或者一条命令
- **11 个模板全部接入** `assets/templates/themes.js`。两种换法,效果一样:
- ```bash
- # ① 命令行(推荐):不改文件,一次渲一个主题
- bash assets/render.sh bar-chart.html --duration=6 --theme=paper --out=bar-paper.mp4
- ```
- ```js
- // ② 写进模板:CFG.theme 一行
- const CFG = {
- theme: 'paper', // midnight(默认,暗色)| paper(浅色)| neon(黑紫霓虹)
- ...
- };
- ```
- 命令行优先于 `CFG.theme`。名字打错会明确告警并告诉你有哪些可选,不会静默变成默认色。
- 因为主题是注入的,`--batch` 里每个任务可以各用一套配色 —— 同一份片子出「暗色版 + 浅色版」不用复制文件:
- ```json
- [{ "html": "bar-chart.html", "duration": 6, "theme": "midnight", "out": "bar-dark.mp4" },
- { "html": "bar-chart.html", "duration": 6, "theme": "paper", "out": "bar-light.mp4" }]
- ```
- 上面每条命令都带 `--out`,不是可选项:成片默认叫 `<HTML 名>.mp4`,
- 同一个 HTML 渲两套配色不换名字,后一个会盖掉前一个。
- 也可以传对象只覆盖要改的字段:`theme: { bg: '#0B1020', accent: '#22D3EE' }`。
- 拷模板时记得把 `themes.js` 一起拷到同目录。只拷 HTML 时画面照常出来(模板里有兜底色板),
- 但 `themes.js` 会 404,而渲染器把「页面报错」判为失败 —— 这时补上文件或加 `--allow-errors`。
- ### 多镜头与转场:一份 HTML 出整支片子
- 一支能看的片子是「多镜头 + 转场」,不是几段动画硬拼。用 `assets/lib/scenes.js`
- 在**同一个 HTML** 里写镜头表,渲染器照旧按 `t` 推帧,转场在页面内合成 ——
- 不用渲几段再拿 ffmpeg 拼,也不用开剪辑软件:
- ```bash
- bash assets/render.sh explainer.html --duration=17.6 --fps=30 --gif --poster=6.0
- ```
- 镜头表也可以整份外置(`--story=shots.json`),**LLM 写 JSON 比写几百行 canvas 代码可靠得多**:
- ```bash
- bash assets/render.sh explainer.html --duration=17.6 --fps=30 --story=shots.json
- ```
- ```json
- [{ "kind": "title", "id": "hook", "dur": 3.0, "title": "为什么你的构建这么慢" },
- { "kind": "talk", "id": "why", "dur": 3.5, "say": "先别急着换工具",
- "who": "dev", "pose": "wave", "trans": { "in": "fade", "dur": 0.45 } }]
- ```
- | 转场 | 观感 | 什么时候用 |
- |---|---|---|
- | `fade` | 交叉溶解 | **文字类片子的默认** |
- | `dip` | 经底色过渡 | 两段情绪差得远,或两镜版式完全换掉 |
- | `slide` | 下一镜整块推入 | 满幅图形 / 照片 / 色块之间 |
- | `push` | 两镜贴着一起走 | 同上,更要方向感 |
- | `rise` | 下一镜从下方升起 | 竖屏、解说卡 |
- | `zoom` | 变焦穿过 | 满幅画面之间,「一口气穿过去」 |
- | `wipe` | 竖边扫擦 + 扫描亮线 | 科技感、数据揭示(满幅图形) |
- | `cut` | 硬切 | 节奏紧,或转场时长给 0 |
- > **选型铁律:画面里有文字,就只用 `fade` / `dip`。**
- > 带位移的转场会把上一镜的文字从中间切一半推走,两镜标题还会在同一位置叠成乱码 ——
- > 观感是「画面坏了」,不是「镜头动了」。位移类转场只留给边缘没有语义的画面。
- > `explainer.html` 的 `draw` 包装里有配套的两条纪律(退场先撤内容、进场晚 0.22×转场时长起步),
- > 自己写多镜头模板时照抄即可。
- 转场是**重叠**的:总时长 = Σ镜头时长 − Σ转场时长,加了转场片子不会变长。
- `--scene-log=shots.csv` 能导出镜头时间轴(含每镜起止与转场),
- **镜头表总时长和 `--duration` 不一致会告警**,免得结尾静默多一截静止画面。
- ### 自带素材:图标 / 人物 / 运镜
- 想画图标、箭头、卡片、人物,不用找图也不用从零写 path —— `assets/lib/` 三个零依赖库:
- ```js
- SH.icon(g, 'bolt', x, y, 48, { color: TH.accent, width: 2.5 }); // 40+ 线性图标
- SH.card(g, { x, y, w, h }, { fill: TH.panel, radius: 18 }); // 卡片 / 箭头 / 连接线 / 纹理
- FIG.draw(g, FIG.preset('dev', { x, y, h, t, pose: 'wave' })); // 参数化小人 + 对话气泡
- CAM.withCam(g, CAM.at(CAM.breath(), t, W, H), W, H, () => drawContent(g)); // 持续运镜,治「画面死了」
- ```
- | 库 | 提供 |
- |---|---|
- | `shapes.js` | 40+ 图标、卡片 / 胶囊 / 箭头 / 正交连接线 / 虚线框 / 进度弧、网格 / 点阵 / 柔光 / 暗角 / 流动极光 / 胶片颗粒 |
- | `figures.js` | 参数化扁平小人:发型 6 种 / 表情 6 种 / 姿势 6 种 / 配色任意,4 个开箱预设,自带 `FIG.say()` 气泡 |
- | `camera.js` | `breath` 呼吸、`kenburns` 推拉、`handheld` 确定性手持微抖、`shake` 衰减震动 |
- **为什么是代码画的元件而不是预置图片素材包**:版权干净(没有一张外部图)、风格必然统一、
- 任意分辨率清晰、不占体积。**刻意不做**卡通人物位图包 / 标志性建筑照片包 ——
- 版权说不清、风格和用户自己的画面打架,还会把仓库撑成几十 MB 的二进制库。
- ### 透明输出:叠到别人拍的画面上
- AI 生成的背景 + 代码生成的文字层,是现在最省钱的组合(模型画文字必糊,代码画文字精确到像素)。
- ```bash
- node scripts/render-video-seek.js animation.html --duration=6 --fps=30 --alpha
- # → animation.mov(ProRes 4444 / yuva444p10le,背景透明)
- ```
- 模板侧只要两行:读到 `window.__transparent` 为真时**把底色连同全屏光斑一起跳过**
- (只跳底色、留着光斑时四角 alpha=12 而不是 0,叠到实拍上整片泛白):
- ```js
- const TRANSPARENT = !!window.__transparent;
- if (!TRANSPARENT) { /* 底色 / 全屏渐变 / 光斑 / 光扫 */ }
- ```
- 体积代价(960×540 / 2s):H.264 约 118 KB,ProRes 4444 约 760 KB。
- **只有 ProRes,没有 VP9 alpha** —— 实测 `yuva420p` 能把 alpha 写进文件(7.8 KB → 16.8 KB),
- 但 Chromium 播出来整帧 alpha 全 0,既然没法自证正确就不作为选项发布。
- ### 字幕:挂外部时间轴,配音改了字幕跟着走
- ```bash
- node scripts/render-video-seek.js subtitle-card.html --duration=8 --srt=voice.srt --cue-log=cues.csv
- ```
- 支持 SRT / WebVTT / JSON。渲染器解析一次、注入 `window.__cues`,模板按当前 `t` 自己查句;
- 模板里 `--srt` 优先、没有就用自带的 `CFG.lines`。`--cue-log` 输出
- `frame,t,cue_index,cue_start,cue_end` CSV —— 每句首帧时间减 SRT 起点就是误差,
- 实测 4 句 / 80 帧,误差 0 ms。
- > 底部 15% 是各平台进度条 / 按钮区,字幕踩进去等于白写;`qa.js` 会提示「进字幕带」。
- ## 一个世界,一条镜头轨迹(v2.0)
- 1.x 的模板都是「一镜一画」:每镜画到自己的离屏画布再合成。干净,但做不了三件事——
- **镜头推过去看某个东西**(下一镜是全新画布,那东西已经不在了)、**镜头穿过一条街**、
- **光随时间变**(只能叠半透明黑,那是滤镜不是光)。
- 2.0 加了三层。三个库互相独立,可以只用其中一个:
- | 库 | 解决什么 | 关键能力 |
- |---|---|---|
- | `assets/lib/space.js` | 镜头在连续空间里移动 | 透视投影 / 深度排序 / 距离雾 / look-at 相机 / 关键帧轨迹 / 环形·网格·螺旋布局 |
- | `assets/lib/brush.js` | 「量」——十万笔的质感 | 按「颜色 × 粗细」分桶批量提交(`stroke` 从 10 万次降到十几个)/ 形态插值 / 文字轮廓吸附 / 方向场 |
- | `assets/lib/light.js` | 光随时间变 | 黑体色温(1900K→9500K)/ 昼夜关键帧 / 径向光·光束 / 调色·曝光·暗角·泛光 |
- ```bash
- node scripts/render-video-seek.js assets/templates/program-film.html --duration=20
- ```
- 出的是**一条街从黄昏到深夜的 20 秒**:两排 3D 盒子楼(真实 3D 顶点投影,正面背光、侧面受光)、
- 7.8 万点城市灯海分三层亮起、6 盏路灯与地面光斑、一条推进的镜头轨迹、色温 2200K → 9500K。
- **为什么是 2.0 而不是 1.10**:它换的是渲染结构(逐镜离屏 → 一个世界),不是加功能。
- | 实测 | 数字 |
- |---|---|
- | 12 万笔生成 | 61 ms |
- | 12 万笔形态插值 | 22 ms |
- | 10 万笔吸附到文字 | 310 ms |
- | 20s 成片(1920×1080 / 30fps) | 600 帧,`h2v qc` 全绿 |
- | 能做 | 做不了 |
- |---|---|
- | 镜头在空间里推、摇、穿行 | 阴影贴图 / PBR(没有 z-buffer,只有画家算法) |
- | 十万级笔触的质感 | 逐像素 shader(流体、火焰、玻璃折射) |
- | 光随时间变(黄昏→夜→晨) | 百万级粒子每帧现算(要那个量级得预渲染) |
- | 视角连续变换(平面→3D 通道) | 真实材质反射(用光照 + 笔触去「暗示」) |
- 需要真 3D 时直接上 `three.js` —— 渲染器只认 canvas,不关心你怎么画;`--alpha` 可以把 WebGL 图层叠到实拍上。
- ## 东西是真的:实体、着色、气氛(v2.1)
- 2.0 解决了「空间连续」,但空间里的东西还是**平面片**。平面片没有法线 ——
- 不能着色、不能转身、做不出曲面。镜头在动,画面还是平的。
- 2.1 补的是「面」:
- | 库 | 解决什么 | 关键能力 |
- |---|---|---|
- | `assets/lib/solid.js` | 东西是实体 | `box` / `lathe`(旋转体)/ `sphere` / `tube`(扫掠)/ `terrain`(高度场)+ Lambert·Blinn·边缘光·半球光·AO + 色调映射 + 逐面取色 + 表面粗糙度 |
- | `assets/lib/atmos.js` | 光在空气里走 | 多段天空 / 星空(按星等分布)/ 贴地雾 / 体积光束(54 条射线且相互重叠,不是几层梯形)/ 辉光 / 星芒 / 水面波纹 / 胶片颗粒 |
- | `assets/lib/lens.js` | 镜头有语言 | 球坐标轨道(绕主体转,不穿模)/ **对数**推拉 / 景别→距离 / 手持呼吸 / 切镜表 |
- | `scripts/foley.js` | 声音对得上画面 | 8 种程序化音色(海浪/风/雾笛/灯丝/纸/笔触/撞击/铃)+ 事件表 + Schroeder 混响 |
- ```bash
- h2v new my-world --template=lighthouse
- node scripts/foley.js --out=bed.wav --dur=41 --preset=lighthouse
- h2v render my-world.html --duration=41 --fps=30 --audio=bed.wav
- ```
- `lighthouse.html` 是 41 秒 / 7 镜的一条片:礁石与灯塔是建模的(岩层取色、盐渍、
- 苔、塔身污渍逐面算),镜头从 1500 推到 90(16 倍,对数),再拉到 3100(31 倍);
- 光从黄昏 3000K 推到深夜 6800K;灯在 13.6 秒点亮 —— 音轨里的嗡鸣也在 13.6 秒淡入。
- **为什么「着色」是分水岭**:同一组颜色,有没有法线,是「贴纸」和「石头」的区别。
- 一帧画面里,暗面偏冷、亮面偏暖、边缘有一道亮线 —— 这三件事占了立体感来源的绝大部分,
- 而它们全都需要面法线。
- | 实测 | 数字 |
- |---|---|
- | 17,000 面 / 1080p 单帧 | 20–45 ms(含大气与后期) |
- | 41s 成片 | 1230 帧,1920×1080 / 30fps |
- | 音效床合成 | 41s 立体声,1.5 s |
- ## 14 种风格:同样的内容,换个样子
- 模板解决「这段内容怎么排」,风格解决「这支片长什么样」。两者分开之后,
- 14 个版式 × 14 种视觉语言 = 196 种观感,而不用写 196 个模板。
- ```bash
- bash assets/render.sh assets/style-film.html --duration=13 --theme=chalk # 黑板粉笔
- bash assets/render.sh assets/style-film.html --duration=13 --theme=水墨 --width=1080 --height=1920
- ```
- | 风格 | 一句话 | 适合 |
- |---|---|---|
- | `riso` 孔版印刷 | 米白纸 + 荧光粉/蓝/绿三套网点(真实印刷网角)+ 标题套印错位 | 观点、数据、独立杂志感 |
- | `cutpaper` 剪纸拼贴 | 四边手撕的纸片 + 锐利硬投影 + 两层纸叠着 | 故事、人物、教育 |
- | `blueprint` 工程蓝图 | 深蓝 + 20/100px 双层格网 + 四角十字定位标记 + 等宽字 | 技术、架构、API |
- | `chalk` 黑板粉笔 | 墨绿板 + 双线抖动笔触 + 粉尘 + 楷体 | 教学、科普 |
- | `isometric` 等距线稿 | 白底 + 2:1 等距立体块(顶面/左面/右面)+ 白面遮挡 | 机制、结构、流程 |
- | `synthwave` 霓虹复古 | 条纹太阳 + 透视地面网格 + CRT 扫描线 + 色差 | 音乐、游戏、复古科技 |
- | `swiss` 瑞士网格 | 白底 + 超大字号 + 单一信号红 + 零圆角 | 品牌、观点、发布会 |
- | `ink` 水墨宣纸 | 宣纸纤维 + 三层洇墨 + 朱红印章色 + 大留白 | 国风、文化、历史 |
- | `watercolor` 水彩晕染 | 棉浆纸 + 湿画法色晕 + 颜料在边缘沉积的深圈 + 衬线标题 | 人文叙事、品牌故事、教育 |
- | `pencil` 铅笔素描 | 素描纸 + 45° 排线 + 双线手绘边框 + 石墨灰阶(几乎不用彩色) | 教程、拆解、草稿感 |
- | `vox` 半调解说 | 奶油底 + 大块饱和色 + 大号无衬线 + 半调网点 + 硬投影 | 知识解释、新闻拆解 |
- | `clay` 黏土立体 | 淡紫灰底 + 圆角厚块 + 上亮下暗渐变 + 内高光 + 落地投影 | 产品发布、SaaS、年轻品牌 |
- | `woodcut` 木刻版画 | 米黄纸 + 木纹 + 实墨块 + 断续白刻线(明暗=线密度)+ 朱红套色错位 | 观点、文化、有力量的海报片 |
- | `glass` 玻璃拟态 | 深色渐变 + 漂移光斑 + 磨砂玻璃面板(1px 亮边 / 内高光 / 透光 / 圆角发光条) | 科技发布、SaaS、硬件参数 |
- 14 种分五个家族,选的时候先定类:**印刷**(riso / woodcut)、**手作**(cutpaper / chalk /
- pencil / clay)、**绘画**(ink / watercolor)、**信息图**(blueprint / isometric / swiss / vox)、
- **数字界面**(synthwave / glass)。`npx html-to-video styles --cat=印刷` 只列一类。
- `--theme` 也吃中文名(`--theme=水墨` / `--theme=玻璃`)。**14 个模板已经全部接上** ——
- 换的不只是配色,背景整层会换成该风格的纸纹 / 网点 / 格网 / 透视地面:
- ```bash
- bash assets/render.sh assets/templates/bar-chart.html --theme=blueprint --duration=6
- bash assets/render.sh assets/templates/explainer.html --theme=riso --duration=18
- ```
- 每种风格的签名元素、禁忌、在代码里怎么调、哪个模板配哪种风格,见
- **[assets/STYLES.md](assets/STYLES.md)**。
- **先看效果,再决定**:
- ```bash
- # 十四宫格:第 k 秒一个风格,出 14 张全屏静帧
- 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,8.5,9.5,10.5,11.5,12.5,13.5
- # 一支 13 秒的风格短片:片头 / 要点 / 数据 / 片尾
- bash assets/render.sh assets/style-film.html --duration=13 --fps=60
- ```
- **一支完整的多风格推广片**:`assets/examples/promo-zh.html` + `promo-zh.story.json`
- 是 12 镜 / 8 风格 / 85 秒的真实案例,镜头表由配音净时长反推,所以解说、字幕、
- 画面天然对轴,不用手工卡秒。它演示了两条很实用的做法:每个镜头单独指定
- `shot.style`(一镜一风格,蒙太奇一镜里还能连切四种),以及把字幕画在所有镜头
- 之上(转场时不闪、不随风格变色)。
- ```bash
- node scripts/storyboard.js assets/examples/promo-zh.html \
- --story=assets/examples/promo-zh.story.json --cols=3
- node scripts/render-video-seek.js assets/examples/promo-zh.html \
- --story=assets/examples/promo-zh.story.json --duration=85.34 --fps=30 \
- --audio=voice.wav --out=promo.mp4
- ```
- ## 先看分镜,再渲全片
- 60 秒 1080p 逐帧渲要 3~10 分钟。渲完才发现「第 4 镜字太小」,改一轮又是几分钟。
- 所以先出一页分镜板:
- ```bash
- node scripts/storyboard.js my.html --cols=3 --theme=riso
- ```
- ```
- my.storyboard/
- ├── shot-01.png … 每镜一张中点静帧(在转场窗口之外,画面稳定)
- ├── storyboard.html 带镜头名/时长/时间码/转场的一页板
- └── storyboard.png 整页截图,贴给别人问「这样行不行」
- ```
- 十几秒出,能看出:镜头时长分配、层级大小、有没有哪一镜是空的、风格跟内容搭不搭。
- 看不出动效手感与转场顺不顺 —— 那些要出片或 `--stills` 抽帧连看。
- ## 安装
- 需要 Node.js >= 18。
- **当普通 Node 工具用**(clone 到哪都行,三条命令):
- ```bash
- 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 能直接调用):
- ```bash
- 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`
- ## 快速开始
- ```bash
- # 1. 拿骨架模板改自己的动画
- cp assets/animation-skeleton.html my-animation.html
- # 2. 冒烟:先截几帧确认画面(别跳过)
- bash assets/smoke.sh my-animation.html
- # 3. 只渲一小段,快速看效果(几秒出片)
- bash assets/render.sh my-animation.html --from=3 --to=5 --fps=30
- # 4. 全量渲染
- bash assets/render.sh my-animation.html --duration=12 --fps=60 --width=1920 --height=1080 --concurrency=4
- # → my-animation.mp4
- # 5. 交付前验收(确定性问题、卡顿、半截字、叠字、字幕带、字体回退,一次全查)
- bash assets/qa.sh my-animation.html --duration=12 --fps=30
- # 6. 成片再过一道(前 2 秒有没有动、黑场、冻结、响度)
- node scripts/qc.js my-animation.mp4
- ```
- 12 秒 60fps = 720 帧,实测约 6~7 分钟(concurrency=4)。
- ### 渲染参数
- | 参数 | 作用 |
- |---|---|
- | `--duration` / `--from` / `--to` | 时长 / 只渲某段(秒)。给了范围时输出 `名.起-止s.mp4`,不会覆盖成品 |
- | `--stills=0.5,2.0` | 只导出这些时刻的 PNG,不编码 |
- | `--fps` / `--width` / `--height` | 帧率与分辨率 |
- | `--preset=<名>` | 按平台预设定尺寸(`douyin` / `xiaohongshu` / `instagram` / `square` / `bilibili` …) |
- | `--presets=a,b,c` | 一条命令出全套比例,每个比例一个成片(自动加 `-比例名` 后缀) |
- | `--concurrency` | 并行 worker 数(每个 worker 一个 Chromium 页面);给 `auto` 按 CPU 与内存自己挑 |
- | `--audio=<file>` | 编码后自动混音;没给 `--duration` 时按音频长度出片 |
- | `--audio-fit=trim\|pad` | 音画长度不一致:`trim` 按音轨收尾(默认)/`pad` 补静音保住视频长度 |
- | `--beats` / `--beats=<json>` | 分析 `--audio` 的拍点(或用预计算文件),注入 `window.__beats` |
- | `--snap=beats` | 总时长吸到下一个拍点 |
- | `--snap-shots` | 镜头表里每个镜头的时长量化到整拍(真正让切点落在拍上) |
- | `--bpm=<数>` / `--offset=<秒>` | 跳过自动估计,手工给 BPM / 首拍(纯配音想硬卡点时用) |
- | `--gop=<秒>` | 关键帧间隔(`--gop=1` 便于后期按秒 seek) |
- | `--keep-frames` | 成功也保留逐帧 PNG(换 CRF 重编码不必重截) |
- | `--tmpdir=<目录>` | 逐帧 PNG 落到哪块盘(默认挨着 HTML)。1080p 一分钟约 2.4 GB,系统盘紧张时指到别的盘 |
- | `--resume` | 上次渲到一半断了?接着渲,已渲好的帧直接复用 |
- | `--alpha` | 透明背景输出(ProRes 4444 `.mov`),叠到实拍 / AI 生成画面上用 |
- | `--srt=<file>` / `--cues=<file>` | 外部字幕时间轴(SRT / VTT / JSON),注入 `window.__cues` |
- | `--cue-log=<file>` | 导出字幕对轴 CSV(`frame,t,cue_index,cue_start,cue_end`) |
- | `--story=<file>` | 镜头表 JSON,注入 `window.__story`,整份换掉剧本 |
- | `--scene-log=<file>` | 导出镜头时间轴 CSV;镜头表总时长与 `--duration` 不一致会告警 |
- | `--gif[=fps,宽]` | 出片后顺手产 GIF(默认 15fps / 宽 960),不重渲 |
- | `--poster=<秒>` | 出片后顺手抽一张封面静帧 `.jpg` |
- | `--batch=<file.json>` | 一串任务按顺序渲,最后打汇总表;单个失败不连坐已渲好的 |
- | `--theme=<名>` | 换主题(`midnight` / `paper` / `neon`),覆盖模板里的 `CFG.theme`;打错名字会告警并回退 |
- | `--camera=<行>` | 镜头:`'dolly in, 6s, slow'` / `auto`(按镜头类型) / `off`(关掉),覆盖 `CFG.camera` |
- | `--out=<文件>` | 指定成片路径(默认同目录同名);一份 HTML 出多套配色时用它,上级目录自动创建 |
- | `--json` | stdout 只输出一行结果 JSON(`output` / `duration` / `frames` / `warnings`),日志走 stderr |
- | `--headed` | 开着浏览器窗口渲(调试用;并发自动降到 1) |
- | `--allow-errors` | 页面报错不判失败(默认有报错就非零退出) |
- | `--readytimeout=8` | 等 `__seek` 就绪的秒数(大字体 / 大数据启动慢时调大) |
- | `--no-serve` | 用 `file://` 加载页面(默认走本地 http server,见下) |
- 渲一次发一堆:
- ```bash
- node scripts/render-video-seek.js explainer.html --duration=17.6 --fps=30 \
- --gif=15,960 --poster=6.0 # 成片 + 动图 + 封面,一次渲染全到位
- node scripts/render-video-seek.js --batch=jobs.json
- # jobs.json = [{ "html":"a.html","duration":6 }, { "html":"b.html","duration":8,"fps":60 }]
- ```
- **渲染结束时如果有页面控制台报错,会非零退出**(成片照样产出,方便核对)。
- 这是刻意的:报错通常意味着黑屏或缺内容,早年的版本会一路说成功,直到你回抽帧才发现。
- ### 断点续渲:渲到 80% 崩了,不用从零开始
- 1800 帧的片子跑到一半被掐掉,最伤的是重来一遍。加 `--resume` 接着渲:
- ```bash
- node scripts/render-video-seek.js animation.html --fps=60 --duration=30 --resume
- # ▸ resume: 已复用 1432 帧,还需渲 368 帧
- ```
- 三条规则都是为了保证**续出来的片子和一次渲完的片子逐像素一致**:
- - 帧先写 `.part` 再改名 —— 被 kill 的那一刻不会留下半张图冒充「已完成」,复用的都是真画完的帧
- - 参数变了直接拒绝(`fps` / 尺寸 / 范围任一项不同)—— 两批不同参数的帧混着编码,片子前后节奏会不一致,
- 而且**不报错**。报错里会打印「上次 vs 这次」,删不删由你决定
- - 编码前按帧号逐个核对连续覆盖 —— 缺一张 ffmpeg 会静默提前收尾,成片莫名变短
- 临时目录固定为 HTML 旁边的 `.seek-tmp-resume/`(不加 `--resume` 时仍是一次性目录,并发渲互不干扰),
- 渲完自动清掉;想留着配 `--keep-frames`。
- ### ESM / fetch 项目直接能渲
- 渲染器默认起一个**只绑 `127.0.0.1` 的本地 http server** 来加载页面(零新依赖,Node 内置 `http`)。
- `file://` 下 `<script type="module">` 和 `fetch()` 会被 CORS 拦死 —— 用 Vite/esbuild 组织的动画、
- 读本地 JSON 的项目根本起不来;走 http 就没这些事,而且是 `file://` 的严格超集。
- 渲染开头会打印这个地址,排障时直接粘到浏览器里看控制台最方便。
- 服务器起不来会自动退回 `file://` 并提示(只警告,不判失败)。
- ## 一条命令上手:`h2v`
- 脚本很多(渲染 / 分析 / 分镜 / 验收),记路径和参数很烦。装好依赖后有一个统一入口:
- ```bash
- npx html-to-video doctor # 环境自检:缺什么、怎么修(只读不改)
- npx html-to-video templates # 列出 14 个模板
- npx html-to-video styles # 列出 14 种风格
- npx html-to-video new my-video --template=quote-card
- npx html-to-video preview my-video.html --duration=6 --open
- npx html-to-video render my-video.html --duration=6 --fps=60
- ```
- 它只是把子命令映射到脚本、参数原样透传 —— 和直接 `node scripts/...` 完全等价。
- ### 改版式不用等渲染:拖时间轴预览
- 逐帧渲染最反直觉的是"改一句文案要等几分钟才看到效果",但页面本身暴露了
- `window.__seek(t)`。`preview` 就是把它当时间机器用:
- ```bash
- npx html-to-video preview my-video.html --duration=6 --fps=60
- # ▸ http://127.0.0.1:41234/tmp/h2v-preview-....html
- ```
- 空格播放 / ←→ 单帧步进 / 拖时间轴,看到的每一帧就是渲染器将要截到的画面。
- 竖屏项目加 `--size=1080x1920`,否则预览框是横的、排版按 16:9 算,容易误判。
- ### 跑不起来先跑 doctor
- ```
- ✓ Node.js 22.13.1
- ✓ Playwright 1.58.0 · ~/.cache/ms-playwright/chromium-1208/...
- ✓ Chromium 启动 无头模式可启动
- ✓ ffmpeg .../linux-x64/ffmpeg · 含 libx264 + ProRes
- ⚠ 中文字体 没检测到中文字体,成片里的汉字会变方块
- → apt-get install -y fonts-noto-cjk
- ```
- 三类最常见的失败(Playwright 版本与浏览器缓存不匹配、ffmpeg 缺 H.264、缺中文字体)
- 都能一次看出来,并给出可执行的修法。加 `--json` 给 CI / Agent 用。
- ## 动画要满足的契约
- 渲染器靠这两个全局钩子驱动,**必须有**:
- ```js
- window.__seek = (t) => { /* 把 t 时刻的画面完整重绘一帧 */ };
- window.__ready = true;
- // 渲染器会注入 window.__seekRender = true,
- // 此时必须冻结自驱时钟,完全由外部 __seek 推帧(保证确定性)
- if (window.__seekRender) { renderAt(0); window.__ready = true; }
- else { /* 浏览器预览:requestAnimationFrame 自驱循环 */ }
- ```
- `assets/animation-skeleton.html` 已实现完整契约,直接从它改。
- **铁律:每一帧 = 时间 t 的纯函数。** 不要用 `Math.random()` / `Date.now()`,
- 不要依赖上一帧的状态——否则同输入不同输出,多 worker 并行会各渲各的(验收里的「确定性」会亮红灯)。
- **画布就是唯一输出**:`<canvas>` 定位在 `left:0; top:0`,body `margin:0`。
- 渲染器截左上角,画布必须正好铺满视口、**不能居中**。
- **别用这些 class 名**(渲染器注入的 CSS 会无条件隐藏它们,元素会凭空消失):
- ```
- .no-record .progress .progress-bar .counter .tCur .phases .phase-label
- .phase .replay .masthead .kicker .title .footer
- ```
- 反过来,想让某块**出现在成片里**,给它加 `data-record-keep="true"` 就能豁免启发式隐藏。
- ## 动效库:assets/lib/motion.js
- 缓动、弹簧、步进、错开、拍号的纯函数库,和「冻结时钟 + `__seek(t)`」天然契合。
- ```html
- <script src="../lib/motion.js"></script>
- <script>
- const p = MO.expoOut(MO.seg(t, 0.3, 1.4)); // 0..1 进度,快出慢停
- const y = MO.lerp(80, 0, p);
- const s = 1 + MO.settle(t - 1.2, 0.06); // 到位后的余振
- const items = MO.stagger(t, 5, { t0: 0.4 }); // 5 项依次入场
- </script>
- ```
- 选缓动:讲解类 `MO.smooth` / `sineInOut`(两端都停稳);发布会 `MO.appleOut` / `MO.snappy`;
- 动态大字 `expoOut` + `MO.springHz`;纸片/拼贴 `MO.step(t, 12)` 一拍二。
- **别让画面「死」掉**:动效做完后若还要停留数秒,加一点持续微动(慢速光扫、呼吸),
- 否则观众会觉得视频卡住。模板里都带了这一手。
- ## 自动化验收:qa.sh
- ```bash
- bash assets/qa.sh my-animation.html --duration=12 --fps=30
- ```
- | 维度 | 量什么 |
- |---|---|
- | 确定性 | 抽 首/中/末 3 个时刻,各做「同页面 seek 回去」+「全新页面重渲」两轮逐像素比对 |
- | 动感 | 运动%、静止帧对比例、**最长连续静止秒数** |
- | 流畅 | 相邻帧差峰值/中位数,报「跳变」时刻 |
- | 框景 | hook `fillText` / `strokeText` / `drawImage`(离屏画布的文字会跟着贴图追到目标画布)+ DOM 文字按视觉行分块 → 半截字 / 叠字 / 进字幕带 / 近空白 |
- | 字体 | 字体是否可用、是否悄悄回退到兜底字体 |
- | 报错 | pageerror / console.error(有则判失败) |
- 产物:`qa/qa.md`、`qa/qa.json`、`qa/<名>.heat.png`(运动热图)。
- 纯 Node 实现,**零额外依赖**(像素运算借 Chromium 自己解码,不引 numpy / sharp)。
- 阈值是经验值不是规则:运动 0.5%–8% 多数好看;最长静止 ≥3s 会提示(有意定格可忽略);
- 跳变 >0 先去看那一帧;框景线索只是「去看一眼」的提示,不会让验收失败。
- **采样间隔要 ≤0.1s**,否则一段快速位移在相邻两帧之间看着就像「跳」——那是采样假象不是穿帮。
- 间隔 >0.15s 时会提示该把 `--samples` 提到多少。
- > 「最长连续静止」超标时,最省事的解法不是加装饰,而是加一点持续运镜
- > (`CAM.breath()`,见上)—— 画面在动,观众就不会觉得视频卡住。
- ## 渲得有多慢:自己量一次
- 不同机器差 3–5 倍,所以这里不写「约几分钟」这种拍脑袋的数字:
- ```bash
- npm run bench # 两个页面 × 两档分辨率 × 两种并发 → bench/bench.md
- ```
- 表里给 `s/帧`(已含并发)与「10s@60fps 预估」。**并发不是越大越好**:超过 CPU 核数之后
- 页面之间抢 CPU,`s/帧` 不降反升,表上能直接看出来。
- ## 配乐与派生格式
- ```bash
- FF="<工作区>/node_modules/@ffmpeg-installer/win32-x64/ffmpeg.exe" # Windows
- # 其它平台:FF="<工作区>/node_modules/@ffmpeg-installer/ffmpeg"
- # 混 BGM(0.8s 淡入 / 1.4s 淡出,视频流不重编码)
- "$FF" -y -i animation.mp4 -i "$BGM" -filter_complex \
- "[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]" \
- -map 0:v -map "[a]" -c:v copy -c:a aac -b:a 192k -shortest -movflags +faststart animation-bgm.mp4
- # GIF(两阶段 palette 优化,否则糊)
- "$FF" -y -i animation.mp4 -vf "fps=15,scale=960:-1:flags=lanczos,palettegen=stats_mode=diff" palette.png
- "$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
- ```
- 也可以直接让渲染器混音:`--audio=bgm.mp3`。
- ## 中文字体与跨机器一致
- 默认用系统字体(`Microsoft YaHei` / `PingFang SC`)。这意味着「确定性」**只在单机成立**——
- 换台没有这款字体的机器,字形就变了。要跨机器复现就内嵌子集字体:
- ```css
- @font-face { font-family: 'MyCJK'; src: url('fonts/subset.woff2') format('woff2'); font-display: block; }
- ```
- 子集化(思源黑体 1.38MB → 约 300KB):装 `fonttools` 后
- ```bash
- pyftsubset 源字体.ttf --text-file=文案.txt --flavor=woff2 --output-file=subset.woff2
- ```
- 只统计会画到画面上的字——把注释里的中文也算进去,子集会胖很多倍。
- `qa.sh` 会检查字体可用性并提示「声明的字体其实没生效(悄悄回退了)」。
- ## 常见问题
- **报 `Executable doesn't exist`**
- Playwright 版本和浏览器缓存 build 号不匹配。跑 `node scripts/detect-env.js` 看该装哪个版本,
- 或干脆重跑 `bash scripts/install-deps.sh`。
- **Playwright 自带的 ffmpeg 不能用**
- `ms-playwright/ffmpeg-*/ffmpeg-win64.exe` 是 `--disable-everything` 编译的,
- 只有 VP8 + webm,**没有 H.264、没有 GIF、连 PNG 解码都没开**。必须用 `@ffmpeg-installer/ffmpeg` 的完整版。
- **chromium 下不下来**
- 某些网络环境会反复中断。此时正确做法是**复用已有缓存**而不是升级——
- `install-deps.sh` 就是为此设计的:它会迁就缓存挑版本。
- **Windows 上路径含撇号(如 `C:\Users\O'Brien\...`)**
- - bash 里别把路径写进 `${VAR:-默认值}`,撇号会被当引号开始 → `bad substitution`。本项目的配置文件机制就是绕这个的。
- - 传给 Node 的路径别用 Git Bash 的 `pwd`(返回 `/c/Users/...`,Node 会解析成 `C:\c\Users\...`)。
- **编码中途失败,帧会丢吗**
- 不会。渲染器会保留 `.seek-tmp-*/` 里的全部 PNG 并打印可直接粘贴的编码命令,不必重截:
- ```bash
- "$FF" -y -framerate 60 -start_number 0 -i .seek-tmp-*/frame-%06d.png -c:v libx264 \
- -pix_fmt yuv420p -crf 18 -preset medium -r 60 -movflags +faststart animation.mp4
- ```
- (`--from` 渲染时把 `-start_number 0` 换成对应的起始帧号。)
- **渲染成功但提示「逐帧目录没能自动删除」**
- 某些沙箱/托管环境给 `fs.rmSync` 套了「批量删除保护」,一次删几十个文件会被拦下。
- 渲染器会提示并给出目录路径,**成片不受影响**,手动删那个目录即可。
- ## 目录结构
- ```
- html-to-video/
- ├── SKILL.md 技能说明(WorkBuddy 读取)
- ├── CHANGELOG.md 更新日志与版本号规则
- ├── package.json 可 npm install;engines: node >= 18
- ├── CONTRIBUTING.md 贡献指南(加模板的四条硬约定在这里)
- ├── bin/h2v.js 统一命令入口(render / preview / beats / doctor / styles …)
- ├── scripts/
- │ ├── render-video-seek.js 渲染器内核:冻结时钟 + 逐帧 seek + ffmpeg 编码 + 报错判定
- │ ├── beats.js 节拍分析:ffmpeg 解码 → 能量通量 → 自相关 → 相位对齐
- │ ├── preview.js 浏览器预览服务器(拖时间轴,调 iframe 的 __seek)
- │ ├── doctor.js 环境自检:Node / Playwright / ffmpeg / 字体 / 磁盘
- │ ├── qa.js 自动化验收:确定性/动感/流畅/框景/字体/报错
- │ ├── bench.js 性能基线:量 s/帧,产出 bench/bench.md
- │ ├── lib/hide-chrome.cjs 隐藏播放控件的共享规则(渲染器与验收器同一份)
- │ ├── lib/local-server.cjs 本地 http 静态服务器(解锁 ESM / fetch,零新依赖)
- │ ├── lib/cues.cjs 字幕时间轴解析(SRT / VTT / JSON)
- │ ├── lib/qa-rules.cjs 验收判据的纯函数(可单测,也可注入页面)
- │ ├── lib/testing.mjs 测试公用件(依赖路径解析 / 子进程 / PSNR 探针)
- │ ├── detect-env.js 探测浏览器缓存,输出该装哪个 playwright 版本
- │ └── install-deps.sh 一键装依赖并写配置
- ├── test/
- │ ├── render-smoke.test.mjs 真渲两段(16:9 / 9:16),验分辨率与尺寸告警
- │ ├── multi-shot.test.mjs 多镜头:镜头表导出一致 / --story 换剧本 / 时长不符告警
- │ ├── output-features.test.mjs --gif / --poster / --batch / --concurrency=auto
- │ ├── scenes.test.mjs 镜头时间轴算术(重叠、局部时间、越界、未知转场报错)
- │ ├── camera.test.mjs 运镜:确定性、幅度上限、衰减、save/restore 成对
- │ ├── lib-draw.test.mjs 素材库:所有图标 / 人物组合不得产生 NaN
- │ ├── resume.test.mjs 断点续渲:复用、参数变脸、帧号断档
- │ ├── qa-clean.test.mjs 正常模板必须 PASS
- │ ├── qa-detects.test.mjs 对照组必须 FAIL(六类缺陷)
- │ ├── qa-offscreen.test.mjs 离屏画布的文字必须被追上
- │ ├── qa-dom-text.test.mjs DOM 文字按行分块,多行段落不误报
- │ ├── qa-rules.test.mjs 判据纯函数的单测
- │ ├── templates-contract.test.mjs 模板契约 + 能力登记表双向校验
- │ ├── beats.test.mjs 节拍:BPM / 拍距 / 相位 / 无节拍音频 / 静音
- │ ├── render-beats.test.mjs --beats 注入时机、--snap 吸附、错误参数明确失败
- │ ├── cli.test.mjs h2v 子命令 / new 拷贝依赖 / doctor --json
- │ ├── preview.test.mjs 预览服务器可访问、注入 __seekRender、清理临时副本
- │ └── fixtures/ 对照组页面(broken / offscreen-text / dom-text / beats-probe)
- ├── .github/workflows/ci.yml PR 自动跑 npm test
- ├── docs/ README 里用的演示动图 / 原片 / 静帧
- │ ├── demo-hero.html 首页那支 10 秒演示片的源文件(447 行,零依赖)
- │ ├── demo-*.gif / demo-*.mp4 模板的演示动图与原片
- │ ├── explainer-shots.csv 讲解片那支的镜头时间轴(--scene-log 导出)
- │ └── preview-*.png 静帧大图
- └── assets/
- ├── render.sh 全量渲染包装器
- ├── qa.sh 验收包装器
- ├── smoke.sh / smoke.cjs 冒烟测试:验证契约 + 试截关键帧
- ├── animation-skeleton.html 动画骨架模板(已实现完整渲染契约)
- ├── lib/motion.js 动效时间库(缓动/弹簧/步进/错开)
- ├── lib/scenes.js 多镜头时间轴 + 8 种转场
- ├── lib/camera.js 运镜(推拉/呼吸/手持/震动)
- ├── lib/shapes.js 40+ 图标 + 卡片/箭头/连接线/背景纹理
- ├── lib/figures.js 参数化人物 + 对话气泡
- └── templates/ 14 个开箱即用模板
- ├── themes.js 三套内置主题(midnight / paper / neon)
- ├── explainer.html 多镜头讲解片(人物 / 图标 / 转场 / 字幕)
- ├── title-card.html 片头标题卡
- ├── bar-chart.html 条形图 / 排名
- ├── line-chart.html 折线趋势
- ├── number-counter.html 大数字 / KPI
- ├── timeline.html 时间线 / 流程
- ├── vertical-card.html 竖屏 9:16 卡片
- ├── compare.html 前后对比
- ├── quote-card.html 引言卡 / 金句
- ├── chapter-card.html 章节卡 / 过渡页
- ├── ui-showcase.html 界面演示(聚光 + 标注)
- ├── flow-steps.html 流程图动画
- ├── subtitle-card.html 逐句解说卡
- └── vertical-subtitle.html 竖屏字幕卡(关键词高亮)
- ```
- ## 开发与测试
- ```bash
- npm install # 装 playwright(ffmpeg 见上面「安装」,必须是完整版)
- npm test # 99 个用例,约 2 分钟
- npm run bench # 量本机渲染速度 → bench/bench.md
- ```
- 测试里有一对**对照组**,这是整个项目最该守住的东西:
- | 用例 | 断言 | 防的是什么 |
- |---|---|---|
- | `qa-clean` | 正常模板必须 PASS | 判据过严 → 天天误报,人就不看了 |
- | `qa-detects` | `test/fixtures/broken.html` 必须 FAIL | 判据过松 → 质量门变成装饰 |
- | `qa-offscreen` | 离屏画布的文字必须被报出来 | 「看不见 = 查不出」的静默漏洞 |
- | `qa-dom-text` | 出界文字要报 / 多行段落不许报 | 修误报时顺手把检查关掉 |
- | `templates-contract` | 模板能力表与源码双向对齐 | 能力被悄悄删掉没人发现 |
- | `scenes` | 转场重叠与局部时间的算术 | 「某个镜头少了半秒」这种肉眼看不见的错 |
- | `camera` | 运镜确定性、幅度上限、save/restore 成对 | NaN 进 transform(画面整帧消失但不报错)、变换逐帧叠加 |
- | `lib-draw` | 所有图标 / 人物组合不得产生 NaN | 同上:素材库的静默失败 |
- 只调松不放对照组,等于把质量门拆了。改 `scripts/qa.js` 时全部跑一遍。
- ## 贡献
- 欢迎 PR。**最需要的是新模板**——尤其是需要和声音 / 数据联动的(波形动画、地图轨迹、真实数据接进来的图表)。
- 加模板的四条硬约定(渲染契约 / 画布跟随视口 / 字幕安全区 / 别定格太久)写在
- [CONTRIBUTING.md](CONTRIBUTING.md),照 `assets/templates/title-card.html` 抄骨架最快。
- 加了模板记得在 `test/templates-contract.test.mjs` 的 `CAPS` 里登记它的能力(主题 / 字幕 / 透明),
- CI 会检查源码和能力表是否对得上。
- 提 Bug 请带上**复现命令**和 `qa/qa.md` —— 比贴截图有用得多。
- ## License
- MIT
- `assets/lib/motion.js`(动效时间库)移植自 [huashu-art-motion](https://github.com/huashu-art-motion) 的
- `scripts/engine/lib/motion.js`(MIT),去掉了对原作者引擎的依赖,改成自包含。感谢原作者。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.