spiritual-dev/explainer-short

explainer-short 是做什么的？

制作一个短竖屏解说视频：演讲者在底部，动态图形在上方，中间是大号字幕字卡。一个视频只讲一个想法。主题令牌控制颜色、字体、圆角和动效，使同一脚本可以呈现温暖、单色、高对比或趣味等不同风格。

何时使用

• 8-30秒的竖屏教学或产品解说视频
• 可复用的HTML/Canvas管线，能导出MP4
• 无需重写场景代码即可更换视觉主题

布局

+---------------------------+
|   动画 / 卡片 (1080)      |
|                           |
|---------------------------|  <- 在分界处显示字幕字卡
|   演讲者裁切 (960)        |
|                           |
+---------------------------+
         1080 x 1920

主题系统

主题文件位于 template/themes/*.json（以及供演示用的 sample/themes/）。 活动主题是项目文件夹中的 theme.json。

bash template/scripts/use-theme.sh warm          # 或 mono | high-contrast | playful
# 或者从复制的项目中运行：
bash scripts/use-theme.sh mono

令牌（在 loadTheme 后变为CSS变量）：

令牌	作用
--ink --mute	文字
--bg --bg-hi --bg-lo	背景底色
--surface --surface-2	卡片
--accent --accent-2 --accent-3	强调色
--chip-bg --chip-fg	字幕字卡
--radius-card --radius-chip --chip-size	形状
--headline-weight	标题字重
--font-sans --font-mono	字体（OFL协议woff2位于 fonts/）

预设：warm（默认）、mono、high-contrast、playful。

编辑JSON文件，重新运行 use-theme.sh，然后刷新。主题本身无需构建步骤。

字体替换

1. 将一款开放许可的woff2文件放到 fonts/ 中，并在其旁边保留许可证文件。
2. 在主题JSON中设置 fonts.sans / fonts.sans_file（以及 mono）。
3. 如果字体家族名称有变化，请在 index.html 中指向新文件更新 @font-face。
4. 重新渲染一帧中间帧并确认效果。

内置默认字体：Inter + JetBrains Mono（SIL OFL协议）。许可证文本随 fonts/ 提供。

快速开始（主题演示，无需拍摄演讲者）

npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# 输出： sample/out/<预设>/<预设>.mp4 + 单帧图片

需要：Node 18+、系统已安装Chrome或Chromium、ffmpeg。

完整项目管线（独立使用）

1. 将 template/ 复制到一个新的项目文件夹中（或在 sample/ 内工作）。
2. 在 main.js 中编写场景，调用 window.render(t) 并使用主题中的CSS变量。
3. 可选演讲者拍摄：放入一段拍摄视频，填写 src/edit.json，运行 python3 src/edit.py（需要numpy + soundfile），然后运行 python3 src/captions.py。
4. 在技能根目录下（完成 npm install 后）：

PRESET=warm bash template/build.sh
# 或者，对于已复制的项目：
SKILL_ROOT=/path/to/explainer-short PRESET=mono bash build.sh
# 或直接调用渲染器：
node scripts/render.mjs --dir path/to/project --preset warm --out path/to/project/out/video.mp4

5. 如果有 out/voice.wav，运行 python3 mix.py 将其响度归一化到约 -14 LUFS / -1 dBTP，然后 build.sh 会将其混入视频。

template/scripts/render.mjs 也会被复制到模板旁边，以便项目保留本地副本。

设计规则

1. 一个想法。 一个对象，一个承诺，在结束前完成交付。
2. 一臂之遥清晰可读。 大字号、高对比度、屏幕上文字少。
3. 字幕字卡是声音。 保持提示词简短；在最后一个词上稍作停顿。
4. 使用主题，不要硬编码。 颜色、圆角和字卡尺寸都来自令牌。
5. 品味中立的默认值。 暖色是默认值；由用户选择预设。

发布前检查

对每个维度打分 0-3。只有平均分不低于 2.3 时才能发布。 独立审查员测量主文件。

维度	检查项
冻结	最后一条字幕停留约0.3-0.5秒；不在单词中间切出
响度	约-14 LUFS 综合响度（用 ffmpeg loudnorm 测量）
真实峰值	<= -1 dBTP
封面	结束帧或缩略图偏移帧是清晰的标题卡片
主题	使用了令牌；没有残留的硬编码品牌色
清晰度	陌生人无需音频也能理解要点

完整评分标准：references/review-rubric.md。安全区域：references/cover.md。

文件

路径	作用
package.json	声明 playwright-core
template/	入门项目（HTML、主题、字体、build.sh）
template/themes/	预设JSON文件
template/theme.js	loadTheme() -> 在 :root 上设置CSS变量
sample/	独立的12秒主题演示
scripts/render.mjs	无头帧渲染 + ffmpeg 封装
scripts/render_sample.mjs	用于示例预设的便捷封装
references/	结构、主题、评分标准、封面、完成
docs/	来自已验证运行的预览帧

代理检查清单

• 在技能根目录下执行了 npm install
• 已选择主题预设（或使用默认的暖色）
• theme.json 与预设匹配
• 场景使用CSS变量，而非硬编码的品牌色
• 示例或完整构建生成了MP4
• ffprobe 确认分辨率为1080x1920，时长符合预期
• 中间帧在预设风格下看起来符合品牌调性
• 有音频时，响度约 -14 LUFS，真实峰值 <= -1 dBTP
• 审查评分平均分 >= 2.3
• 项目中无残留的个人或第三方品牌元素