Source To Video
用途
把给定的原始素材（通常是单个 HTML 页面，如个人待办工作台、产品落地页、后台管理界面）转化为一段带口播和动效的宣传短视频。默认输出 1920×1080 @ 30fps、约 30 秒，使用 Hyperframes 合成、本地清晰中文配音。
视频的画面元素严格复用原始素材自身的设计语言（配色、字体、卡片、按钮、图表、横幅），而不是套用通用模板——这是本技能的核心要求。
何时使用
- 用户给了某个 HTML 文件并要求"生成视频 / 宣传片 / 短视频 / 做成动图视频"
- 用户提到 Hyperframes，或要求"用视频展示这个页面 / 把工作台录成片"
- 用户想把手头的产品、工具、页面、功能录制成可分享的短视频（含口播解说）
- 触发形式通常是
@/path/to/page.html 做一个 30 秒宣传视频之类
核心工作流（6 步）
1. 理解素材并提取设计令牌
读取原始 HTML，明确两件事：
- 功能点：页面能做什么（列出 5-7 个值得在视频里展示的核心能力）
- 设计系统：<style> 里的 :root CSS 变量（背景色、主色、状态色、圆角、阴影）、字体栈、以及组件类名（.app-header、.task-card、.reminder-banner、.stat-card 等）
提取出的设计令牌和组件类将直接搬进合成文件，不要凭印象重写近似颜色。方法见 references/style-extraction.md。
2. 写口播脚本，交用户审核
按目标时长落字：30 秒 ≈ 120–140 字中文（留呼吸停顿）。结构用 Hook（痛点/共鸣）→ Story（核心卖点分场景展示）→ Proof（信任锚点）→ CTA（关注/引导）。
先输出口播脚本给用户审核，确认后再生成视频（避免返工）。脚本按场景拆分（如 7 个场景），每场景标注画面意图与口播文字。
3. 搭建 Hyperframes 环境
参考 references/hyperframes-setup.md：
- 安装 hyperframes CLI 到受管 node 工作区；用 node node_modules/hyperframes/bin/hyperframes.mjs 调用
- 确认 hyperframes doctor 报告 Chrome、FFmpeg 就绪
- 网络受限时：GSAP 的 CDN 会被挡，需 npm install gsap@3.14.2 拷贝 dist/gsap.min.js 到项目 libs/，用 <script src="libs/gsap.min.js">；@font-face 的 url 必须带 fonts/ 前缀
4. 写合成文件 index.html
- 复用第 1 步的设计令牌 + 组件类搭建 7 个场景（scene1..scene7）
- 用 GSAP 时间轴，场景触发点定义为常量
S1..S7（相对定位S + offset），切换动画（推拉/缩放/模糊淡入） - 7 段口播用
<audio id="voN" data-start="..." src="audio/sN.wav">绑定 - 场景入场动画避免从同一方向大距离飞入（重叠检测会报 content_overlap）；改用保持各自 Y 轴的横向滑入
5. 生成清晰中文配音
这是最容易踩坑的环节，务必先看 references/tts-chinese.md。 一句话结论：
- ✅ 女声 / macOS / 离线：优先用 macOS 本地 say -v Tingting（神经网络中文语音，清晰离线）
- ✅ 男声 / 更自然 / 非 macOS：优先用 Edge-TTS（微软神经网络语音，跨平台，需联网），男声推荐 zh-CN-YunxiNeural
- ❌ 不要用 Kokoro 的 espeak cmn 后端做成品配音——能跑但中文机械、字间粘连、听不清
- 统一生成脚本：python scripts/gen_tts_say.py（默认 say/Tingting）；加 --engine edge --voice zh-CN-YunxiNeural 即可切换男声/自然语音
生成后必须实测每段 wav 时长用于下一步时间轴对齐。
6. 校验并渲染
hyperframes check（= lint + 运行时校验 + 布局 inspect）：目标是 0 错误。剩余对比度警告若来自原 App 自身 gray 文字，属忠实复现，非缺陷- 按实测配音时长重排时间轴（见
references/timeline-design.md）：data-start与S常量一一对应，动画不晚于声音、场景动画不被中途打断 - 自然男声通常比 Tingting 女声慢：同样 120-140 字口播可能从 30s 涨到 ~38-40s。不要为硬凑 30s 把语速压到 unnatural（如 +35%），宁可延长
data-duration到 40s 并同步调整S1..S7 hyperframes render -o out.mp4 --browser-timeout=90（加PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS=60000防首次加载超时）- 渲染后抽 5-7 帧关键画面目检，确认元素严格使用原素材样式、口播与画面同步，再用
present_files交付
关键原则
- 画面严格复刻原素材：搬设计令牌与组件类，不手写近似色。
- 口播先于渲染：脚本经用户确认再生成，避免返工。
- 中文配音要清晰：女声离线选 Tingting，男声/自然/跨平台选 Edge-TTS（Yunxi/Yunyang），保底才用 Kokoro-cmn；生成后实测时长。
- 时间轴自适配：动画基于
S常量相对定位，改常量即可整体微调，不碰动画细节。
Resources
references/hyperframes-setup.md— Hyperframes 安装、依赖检测、网络受限下的 gsap 本地化与字体坑、check/render 命令references/tts-chinese.md— 中文清晰配音方案：macOS say Tingting（女声离线）、Edge-TTS 男声/自然语音（跨平台联网）、Kokoro-cmn 仅退守references/timeline-design.md— 口播时长实测 → data-start 与 S 常量自适配重排方法references/style-extraction.md— 从原 HTML 提取设计令牌并严格复刻组件样式的要点scripts/gen_tts_say.py— 统一 TTS 生成器：默认 macOS Tingting，支持--engine edge --voice zh-CN-YunxiNeural一键切换男声/自然语音
