参考素材动态影像制作是做什么的？

影片就是 HTML，其节拍列表就是乐谱。 每个可见事件都会在驱动画面的常量旁注册一个节拍；影片的每一段都根据其用途命名。一个调色板将这些节拍转化为音乐，精准命中每一帧并演绎出故事：在陈述问题时没有节奏，产品工作时进入律动，在产生效果前有一口呼吸，产品故意停止时鼓声消失，标志出现时戛然而止。

可运行示例：examples/claude-code/（可在共享舞台上运行的产品发布、解说和演示影片，每个都有不同的调色板），examples/moments-v2.html（36 秒一镜到底广告），examples/ads/（Moments 广告：鼓乐、管弦乐、小提琴）。Moments 作品需要产品素材和路径调整；它们作为参考，并非可直接渲染的演示。

决定过往影片的规则

贴合第一。 音乐必须符合产品情绪并演绎出画面的流程。在一次盲听 A/B 测试中（KIBO v4.5，30 秒，相同画面，相同响度），产品所有者选择了根据画面创作的配乐，而非一首节拍匹配且在各项机器指标上表现更优的免费电子流行曲目：“第二首不合适”。创作是默认选项；仅当用户指定曲目时才使用库曲目（references/music.md）。
每个节拍都有声音，且精准落在该帧上。 剪辑落在节拍上，文字弹跳在弱拍上，最大的揭秘获得最强的音效。
仅限真实影像和真实输出。 动态图形用于画面构图和解释说明；它们从不伪造功能。在屏幕上标注加速和等待剪辑（“直播 App · 1×”、“⋯ 等待剪辑”、“▶▶ 已加速”），标记合成语音，在每个数字下方注明来源。
语音优先。 当有旁白或对话时，背景音乐需为其让路（references/music.md，“混音”）。
机器门控是必要条件，而非充分条件。 同步、响度和语音转文字（STT）在音乐不贴合时都可能通过检查。由人通过盲听来决定。
先问，再决定。 仅询问请求和代码库无法回答的问题，并首先给出推荐答案；其余部分自行决定并说明。

工作流程

0. 环境检查（在任何操作之前）

逐行报告状态为正常或缺失，并给出修复方法；切勿打印任何密钥的值。

Google Chrome（渲染器使用系统安装的 Chrome：自带的 Chromium 无法解码 H.264），ffmpeg（含 rubberband），Node ≥ 20，并在技能目录中执行 npm ci --prefix engine --ignore-scripts。
Python 3.12，并安装 numpy、scipy、soundfile、pytest（在技能目录中依次执行 uv venv --python 3.12 .venv 和 uv pip install --python .venv/bin/python -r requirements.txt）。
采样库：运行 bash engine/fetch_samples.sh core（VSCO-2-CE CC0 打击乐、铜管、木槌；Pixabay 许可的 SFX），然后运行 bash engine/fetch_samples.sh piano 获取 soft_pulse（Salamander Grand Piano，CC-BY 3.0；使用时需署名）。当缺少采样时，调色板会回退到合成音色，但钢琴回退可能导致段落平衡检查失败；为完整运行测试套件，请同时使用两组采样。
旁白服务商及其凭据，仅当请求了旁白时需要（references/voice.md）。三个可运行示例不需要任何 API 密钥。旁白、转录和 app 录制客户端未捆绑；请根据需要使用可用工具，并在需要时验证所选服务商的当前文档。
可用磁盘：渲染使用管道式帧（无 PNG 转储），但采样库和录制文件需要几 GB 空间。

1. 需求访谈 → 一页简报（规划前需批准）

仅询问请求和仓库未提供的上下文。使用环境的提问工具，若无可用工具则直接对话；将相关问题分组，优先给出推荐选项，并复用已给出的答案：

目的： 影片类型（产品发布、概念解说、演示教程、用例场景、宣言），目标观众，发布平台（YouTube、比赛、社交媒体），期望观众在观看后采取的行动，截止日期以及任何评审标准。
信息和证据： 需要被记住的一句话，三个证据及其来源，绝对不能提及的内容。
格式和声音： 时长和格式（16:9、9:16、缩略版），屏幕文本、字幕和语音的语言；音乐参考链接或情绪（提供下表中适合该目的的调色板，外加“我有参考链接”选项）；是否需要旁白，以及使用哪种声音。
来源和规则： 是否可以录制真实 app（URL、登录信息、演示数据、两台设备），是否会出现真人，品牌资产，比赛规则，第三方知识产权。回读简报并获得确认。将其写入 video/BRIEF.md。

2. 类型和参考素材

在 references/genres.md 中选择类型的节拍模板和量化目标（跨五种类型的 16 个官方参考，包括镜头时长、每张卡片字数、旁白语速、产品和标志出现的时间点）。使用 /watch 观看选定的参考素材；使用 engine/ref-analyze.py 分析其音乐。对于一镜到底的广告，请阅读 references/transitions.md 和 references/youtube-analysis.md。

3. 规划 → `video/PLAN.md`（构建前需批准）

4. 录制真实屏幕

references/capture.md：当需要产品画面时，使用两台设备从真实 app 进行实时录制（使用带墙钟时间戳的 CDP 录屏帧，通过手机麦克风播放合成客户语音，从页面点击获取 AI 回复），转换为恒定帧率的 MP4 并统一时间基准，然后通过时间映射（[[影片时间戳, 录制时间戳], ...]）在影片中播放：等距步长为 1 倍速，平坦运行表示定格，两点间隔 1 毫秒表示剪辑。使用环境中可用的浏览器工具；references/aside-capture.md 提供了 Aside 特定的实现。终端或工具输出：重新排版真实输出（如 Claude Code 示例），切勿捏造。

5. 旁白（可选）

references/voice.md：使用选定的 TTS 服务商或提供的录音，试听录制文件，根据单词准确度和语速选择（英语演示通常从 155-170 字/分钟开始），并在拉伸语音前调整措辞或停顿。在源头进行清理，并将每一行词数控制在对应时段的预算内。

6. 构建影片合成

一个固定的 1920×1080 #stage；所有动画均来自一个暂停的 GSAP 时间线；打字、计数器、英雄圆点和视频片段完全通过 __seek(t) 基于时间计算。严禁使用 CSS 动画、setTimeout 或 requestAnimationFrame 来驱动动画。fromTo 需要设置 immediateRender: false。
引擎约定：window.__duration、__seek(t)、__ready、__cues、__sections、__bpm、__T。从 examples/claude-code/stage.js（节拍、段落、文字弹跳、打字、计数器、终端卡片、英雄圆点）或 examples/moments-v2.html（在真实屏幕上的虚拟摄像机）开始。
在每个导致可见变化的常量旁注册一个节拍；根据用途标记每个段落（见下表）。
字幕：为旁白行预留一个可读区域，并确保其他内容不干扰该区域；标识合成语音及其服务商；当简报要求时添加翻译；并根据相同的字幕列表生成 .srt 文件。
在进行完整渲染前检查静帧：node engine/stills.mjs index.html out/stills 1.7 3.6 ...。

7. 音乐：根据画面创作

node engine/cues.mjs > cues.json                      # duration, bpm, T, cues, sections
python engine/compose.py cues.json score.wav --palette bright_demo [--narr narr.js --narr-root .]

compose.py 创作配乐，以语音优先的方式混音，输出符合 -14 LUFS（真实峰值低于 -1 dBTP）标准的音频，并自动执行同步门控：如果某个节拍在 33 毫秒内没有可听到的起始点，则会添加调色板的强调音并重新混音（最多两次）；报告会列出添加的内容。在选定前进行试听： 使用两到三个合适的调色板渲染同一段 15-30 秒的内容，让使用者盲听选择。详细信息、混音规则和库曲目路径请参考 references/music.md。

8. 渲染

node engine/render.mjs index.html out/film.mp4 --fps 30 --audio score.wav（JPEG q95 帧通过管道传输给 x264：约比 PNG 快 10 倍；YouTube 标记：High profile、GOP 为帧率一半、BT.709 标签、AAC 48 kHz 384 kbps）。草稿可限制短范围：--from 10 --to 16。Chrome 在一页中大约加载 18 个独立视频；对于不动的片段请使用静帧。

9. 门控检查（所有检查均在最终文件上执行）

references/qa.md。在最终 MP4 上检查同步（python engine/synccheck.py out/film.mp4 cues.json：每个节拍偏差在 33 毫秒内，并根据其机率基线进行评估）、响度、真实峰值、静帧、转场，以及使用者的听觉判断。仅当存在相应的功能时，才执行语音、字幕、二维码和修订检查，使用环境中可用的工具；不要将未运行的检查报告为通过。云端理解测试是可选的，需要用户选择将影片发送到该服务。

10. 交付

按简报要求的时长和格式交付，通常是 H.264 MP4，如果有字幕则附带 .srt 文件，并根据要求提供缩略图或缩略版本。内置舞台和渲染器为 1920×1080；其他宽高比需要明确的适配，而非通过渲染器标志实现。报告实际运行的检查及其证据。除非用户已提出要求，否则发布是单独的操作。

按目的划分的段落

类型	适用于画面...	对应的音乐
`intro`	陈述问题，产品尚未行动时	无节奏：仅一个铺垫，听起来只有节拍音效
`tease`	唤醒产品，首次出现时	稀疏的律动（无后拍、上层打击乐或旋律）
`build`	即将展示结果；重新进入前的填充	渐强至段落结束
`groove`	展示产品运行时（`energy` 0.5-1.2）	能量为 `e` 的完整律动
`light`	承载密集的台词或充满文字的卡片时	去掉旋律音的律动
`muffled`	陈述严肃事实、统计数据或问题时	低通滤波后的律动，逐渐打开进入下一段落
`breath`	在揭秘前停顿一拍时	近乎静音；仅英雄对象的声音响起
`stop`	展示产品故意不动作时（安全停止、限制）	鼓声消失，保留一个铺垫音
`end`	结尾卡片时	静音
`riser`（叠加）	上升并准备落地时	一个在段落结束时结束的上扬音效

每个调色板都会处理的节拍类型：drop（揭秘时刻）、reentry、final（标志出现，然后戛然而止）、break（开始停止）、cut（big 用于章节切换）、tap、tapTouch、pop、word、chip、node、num、count、fill、bar、key（打字）、dot（英雄对象自身的声音）。

调色板（`engine/palettes/`）

调色板	适合场景	声音	来源
`bright_demo`	演示教程、友好的消费者或SaaS应用、语音主导	F大调流行风格，100 BPM：有力的底鼓、拍手和响指、沙锤和铃鼓、马林巴（VSCO采样或合成）、拨弦贝司、空灵铺垫、水滴般英雄音效	KIBO v4.5 (A2-bright)，使用者选择；赢得盲听A/B测试
`drums_launch`	发布影片和广告、产品揭晓、音乐主导	D小调现场套鼓风格，100 BPM：VSCO底鼓、军鼓及幽灵音、镲片、康加鼓、牛铃、切分贝司、闷音吉他、小号和铜管断奏	Moments 50秒鼓乐广告（受Apple MacBook Air M5影片启发），使用者偏好的风格
`soft_pulse`	概念解说、图表、旁白密集的影片	C大调，96 BPM：采样钢琴、调谐的马林巴节拍音、轻柔套鼓、贝司和铺垫；随着能量增加而加入层次，节拍音符随图表构建而上升	用于 `examples/claude-code/explainer`

以下为独立的脚本，待移植到调色板接口：钢琴和钟声（engine/score.py，Moments v2）、乐队（engine/score_band.py，一个B2B推广）、管弦乐和独奏小提琴（examples/ads/orch、examples/ads/violin）。要添加一个调色板，请遵循 engine/palettes/__init__.py 的格式，并将其名称添加到 tests/test_compose.py：测试可以证明它能表现段落语法（intro 段无底鼓、呼吸段和结尾卡片保持静音、stop 段鼓声消失、每个节拍都能听到、-14 LUFS）。

文件

engine/：render.mjs、cues.mjs、stills.mjs、compose.py + palettes/、audio.py（总线、采样器、空间感）、synccheck.py、beatmap.py 和 bedmix.py（库曲目路径）、ref-analyze.py、music-analyze.py、fetch_samples.sh。
references/：genres.md、music.md、voice.md、capture.md、qa.md、transitions.md、youtube-analysis.md、aside-capture.md、ads/。
tests/：python -m pytest -q tests/（节拍图、库混音、同步门控、每个调色板的段落语法）。

简报和交付约束

使用要求的时长、语言、宽高比和目标平台。如果是比赛，请阅读其实际规则并使用 ffprobe 验证时长；不要沿用以往比赛的限制条件。
显示真实产品画面或真实输出来支持功能声称，并尊重用户的品牌和资产权限。像 Claude Code 示例一样，标识关于其他产品的非官方示例。
首先准备本地交付物。只有在用户授权了目标平台和可见性之后才进行上传。

参考素材动态影像制作