promo-video（宣传视频）
一部影片分六个阶段制作。每个阶段都以人工检查作为结束。 请勿超前执行： 昂贵阶段（构建阶段）只有在前期阶段确定好后才是便宜的，因为每个画面事件 都要与音乐和旁白对齐。
在开始时向人工一次性陈述计划（README.md 包含面向人工的版本），然后按顺序运行
各阶段。使用他们的语言进行交流。将所有项目文件保存在一个目录中（<project>/：audio/、
vo/、PLAN.md、elevenlabs.md，以及 video/ 中的 Remotion 项目）。
| # | 阶段 | 你做 | 人工做 | 参考文档 |
|---|---|---|---|---|
| 1 | 音乐 | 分析音轨，找到真实速度和关键标记点 | 在 Epidemic Sound 上挑选音轨，使用创建剪辑确定长度，将文件交给你 | references/01-music.md |
| 2 | 分镜 | 提出引导性问题，编写 PLAN.md（与音乐对应的镜头时间表） | 回答问题，批准 | references/02-storyboard.md |
| 3 | 旁白脚本 | 撰写台词 + 带标签的 ElevenLabs 录音内容 | 在 ElevenLabs 中生成录音，发送文件 | references/03-voiceover.md |
| 4 | 剪辑旁白 | 对录音文件运行 cut_ui.py，然后拆分、调整电平、放置每一句台词 | 在浏览器页面中在台词之间点击，按“完成”；检查放置表 | references/03-voiceover.md |
| 5 | 构建 | 从 template/ 开始的 Remotion 项目，逐场景构建，每帧进行检查 | 审查静态帧 / 草稿渲染结果 | references/04-build.md |
| 6 | 审阅与打磨 | 渲染、响度检查、对渲染结果运行 review_ui.py、阅读注记和帧标记、修复、重新渲染 | 在审阅页面观看，在画面上留下注记，选择“已批准”或“需要修改” | references/05-review.md |
浏览器自动化：提供选项，但绝不假定
第 1 和第 3 阶段在网站上进行（Epidemic Sound、ElevenLabs）。如果存在浏览器自动化技能或工具
（例如 ego-browser、Playwright 环境、浏览器 MCP），主动提出代替人工完成这些部分，并在征求同意之前明确说明
所涉及的内容：
- 账号：两个站点都需要账户（Epidemic Sound 是付费订阅，有试用期；ElevenLabs 有免费套餐，但每月有字符限制）。如果人工没有账户，他们自己注册：你不得创建账户。
- 费用：ElevenLabs 按字符计费；一部 40–60 秒的影片大约 600–1000 个字符，每次重新生成都会再次收费。Epidemic 的下载次数计入套餐。告知人工预期花费并先征询意见。
- 登录和支付由人工负责：将浏览器控制权交给人工（在 ego-browser 中使用
task.handOff()）以处理登录、2FA、验证码及任何支付页面；在人工告知完成后继续执行。绝不输入人工的密码，绝不输入或存储银行卡信息，绝不将人工的 API 密钥粘贴到页面或文件中。 - 获得同意后你可以做的事：按商定的情绪和 BPM 搜索/筛选音轨，并打开候选音轨供人工试听（由人工选择）；使用目标长度点击“创建剪辑”并下载结果；粘贴
elevenlabs.md录音内容，应用人工选择的配音和设置，生成一次，下载 mp3。 - 如果没有此类工具，或人工拒绝使用：提供准确的步骤（第 1 和 3 阶段的文档），等待文件。
选择权始终属于人工：音轨和配音永远不会由你代选。
基本原则（从实践中获得的教训）
- 所有展示的内容都是真实的。 真实的示例网格（对实际 CAD/STEP 文件进行三角剖分）、代码面板中的真实代码和 API、根据产品自身前端组件重建的 UI。虚假内容是观众唯一会注意到的问题。如果你无法获取真实内容，请说明情况并询问——不要凭空编造。
- 音乐就是时钟。 测量真实速度（
scripts/music_analyze.py进行拟合；如果猜测的 BPM 偏差超过 1.2 %，则拼接点会偏差三分之一节拍，人类会感觉到明显的顿挫感）。所有时间数据存放在src/marks.ts中；场景从中导入，绝不硬编码秒数。 - 确认对外或昂贵的步骤：音乐文件和旁白由人工选择；你绝不代选。绝不打印在拍摄产品中出现的 API 密钥或登录令牌。
- 用静态帧检查画面，而非仅凭信任：渲染标记点（节拍点、剪辑点、标志出现时刻）处的帧，并在完整渲染之前进行检查。完整渲染需要数分钟；静态帧只需数秒。
- 保留旧版本。 当人工要求精简或变体版本时，复制项目目录并在副本中编辑（
cp -R video video_short，创建符号链接node_modules）。 - 像编辑一样报告：说明更改了什么、文件路径、需要听/看的内容以及具体在哪一秒。
本技能中的工具
所有 Python 脚本使用 uv run 运行（依赖项已在每个文件中声明；无需另行安装）。
| 脚本 | 用途 |
|---|---|
scripts/music_analyze.py track.wav --out beats.json | 真实 BPM（拟合值）、节拍/小节网格、段落结构、重音点、静音间隙 |
scripts/music_splice.py track.wav out.wav --beats beats.json --keep a:b --keep c:d | 通过按小节对齐的交叉淡入跳转缩短音轨；验证连接点 |
scripts/cut_ui.py take.mp3 --mode cuts --script elevenlabs.md --out vo/cuts.json | 浏览器剪辑页面（波形图、逐行显示的脚本、语音与停顿区分、缩放、撤销/重做）：人工播放并在台词结束处点击，按“完成”，标签页关闭，cuts.json 为你准备就绪。--mode marks --beats beats.json 在节拍网格上标记音乐的重音/强拍/间奏部分 |
scripts/vo_cut.py take.mp3 --regions vo/cuts.json --out vo/ | 将 ElevenLabs 录音拆分为经过电平调整的片段 + clips.json（如果人工更倾向于输入时间，也可使用 --lines N --ends t1,...） |
scripts/review_ui.py out/promo.mp4 --out review/review.json [--overlay overlay.json] | 浏览器审阅页面：上方为监控画面，下方为时间轴条（胶片条 + 已完成混音的波形 + 可选的节拍/标记/旁白线）。人工可在某个时刻或某个范围内留下注记；每条注记携带精确帧号；最终选择“已批准”或“需要修改”，review.json 为你准备就绪 |
scripts/new_project.sh <dir> [--link-modules path] | 从 template/ 创建 Remotion 项目（金属舞台、节拍时钟、旁白混音、虚拟摄像机） |
template/tools/mesh.py | STEP/OCC 形状 -> 适用于 three.js 的紧凑网格 + B-rep 边线 |
template/tools/refold.py | 清空 OCC 无法读取的巨大 STEP 元数据字符串 |
template/tools/variants.py、stages.py | 网格参数变体 / CAD 笔记本的每个中间实体（用于“拖动滑块，模型随之变化”和“逐个单元”的场景） |
需要：ffmpeg、node 20+、uv。对于无头 Chrome 中的 three.js：需安装 Playwright 的 chrome-headless-shell
（new_project.sh 会自动安装）。