---
name: audio-driven-video
description: Turn a voiceover audio file, SRT subtitles, and transcript text into a single-file dynamic web video whose visuals are driven by the audio clock. Use when the user wants a high-impact HTML video, kinetic webpage short, narrated video page, synchronized subtitles, or screen-recordable web video. The only preserved invariant is audio-clock synchronization. CRITICAL: this skill must design fresh, content-specific shots for each project. The case-library samples and template demo scenes are illustrations of method, NOT a menu to copy from.
---

# Audio-Driven Video

从以下素材构建一个自包含的 HTML 视频页：口播音频（mp3/wav）、SRT 字幕时间轴、作为权威文字的逐字稿、可选 BGM。
输出是单个 HTML，用于浏览器全屏播放与录屏。

---

## 这个 skill 最重要的一件事（先读）

**这个 skill 的能力是"把口播做成贴合内容的动态视频"，不是"套用某一期的镜头"。**

`references/case-library/` 里的案例和 `assets/template.html` 里的 3 个示范 scene，存在目的是教你"镜头怎么写""什么叫贴合内容"，**禁止直接搬用**。

每做一期新内容，你必须**为这期内容重新设计镜头**——就像那些案例的作者当初为自己的主题做的那样。
照搬案例镜头（高塔、火车、水池、数字滚动……）到无关内容上，就会产生八股、不应景的视频。**这是本 skill 要避免的头号失败模式。**

---

## 不可变的约束（这些写死，不许变）

1. **音频是唯一主时钟。** 字幕、镜头切换、进度、BGM 淡入淡出、运动状态，全部从 `audio.currentTime` 派生。不准用独立的 `setTimeout`/`setInterval` 驱动画面。
2. **逐字稿 > SRT 文字。** SRT 给时间，逐字稿给措辞。填 `CUES` 前先用逐字稿订正 SRT 的识别错误。
3. **输出一个 HTML 文件。** 内联 CSS/JS。音频用相对路径引用，除非用户明确要求内嵌。
4. **录屏干净。** 成品里不准有可见的播放控件、调试面板、校准UI、作者工具。只允许"点击开始"遮罩。
5. **每屏只有一个视觉重点。** 关键信息不准被动画盖住。字幕必须和音频同步。

## 你来决定的部分（每期都不同，必须自己想）

- 这期用什么镜头、每个镜头长什么样 —— 由内容决定，见 Step 0。
- 配色、字体、风格基调 —— 让它服从内容的情绪（见 `references/STYLE.md`）。
- 用哪些手法（入场动画/高亮/闪切）—— 按需取用，不必全用，也不限于示范里的几个。

---

## Step 0 — 分镜意图表（必做，先于一切代码）

在打开 template、写任何 HTML 之前，先逐句过一遍逐字稿，为每一句产出一行：

| # | 句子 | 功能(钩子/铺垫/反转/数据/结论) | 观众此刻的情绪 | 这句的核心意象 | 拟用视觉 + 为什么 |

**填表规则（这几条直接决定能不能去八股）：**

- **视觉必须从"核心意象"推导**，不许写"沿用上期"或"模板里有这个"。"上一期这么做"不是合法理由。
- **没有数字的句子，不准用数字滚动；没有对比关系的句子，不准用左右并置。** 手法要对得上内容。
- 想不出意象的句子，就用**干净大字 + 关键词高亮**，宁可朴素，不要硬塞不相关的炫技动画。
- **先把这张表输出给用户确认，再开始写代码。**

这一步的唯一目的：强迫先理解内容、再设计画面。它一旦做扎实，八股基本就消失了。

---

## Workflow

1. **做 Step 0 的分镜意图表**，发给用户确认。
2. 读 `references/STYLE.md`，理解"镜头如何贴合内容"的原则与正反案例。
3. 读 `references/PIPELINE.md`，处理真实素材、BGM、字幕订正、校准、录屏导出。
4. 从 `assets/template.html` 取**技术骨架**（主时钟/cqh单位/闪切/canvas/HUD/字幕系统）。
5. **根据意图表，在 template 的 SCENE 区新建本期需要的镜头。** 示范的 3 个 scene 只作参考；复用它们仅当本期内容确实需要那个效果。
6. 把镜头切换对齐口播的自然停顿。约 2.5–6 秒每镜头，按语义调整。
7. 校验：

```bash
node skills/audio-driven-video/scripts/validate_html.js path/to/output.html
```

8. **渲染自检（validator 查不到、但最容易翻车的视觉/技术点，做完逐条过一遍）：**
   - **背景画布是否真的铺满**：`<canvas>` 是替换元素，默认 300×150，只写 `inset:0` 撑不开，必须显式 `width:100%;height:100%`。否则背景只在左上角一小块（template 已修，自定义新层时同理）。
   - **大号展示字是否被裁**：`line-height<1` 在小字号没事，但放大到 ≥18cqh 或换衬线/中文时会切掉字顶。大字一律 `line-height≥1.0` 并留 `padding` 余量。
   - **全屏录制错位**：监听 `fullscreenchange` 重算画布尺寸（template 已内置）。
   - **嵌入的图片/外部资源**：相对路径，且与音频放同一目录，录屏前确认能加载。
   - **音量关系**：口播与 BGM 分别用独立变量控制（如 `VOICE_VOLUME` / `BGM_BASE_VOLUME`），方便按需求调比例；信息类口播默认 BGM 远低于人声。

## 数据结构速查

`template.html` 顶部注入三个数组：

- `CUES = [{s, e, h}]` — 字幕 cue。`s`/`e` 为秒，`h` 为内联 HTML，用 `<span class="sub-key">` 标红关键词，每条 ≤32 汉字。
- `CHAPTER_NAMES = [string]` — HUD 章节名，与 SCENES 等长。
- `SCENES = [{id, t, fn: functionRef, cut:'red'|'blue'|'white', ...内容字段}]`
  - `t` = 开始时间（秒），由 `audio.currentTime` 决定当前 scene。
  - `fn` = 你自己在 SCENE 区写的函数（接收 scene 对象，返回 HTML string）。
  - 内容字段（如 `title`, `sub`, `left`, `right`）在 `fn` 里用 `text(c.field, '')` 读取。
  - **函数体内禁止写死长中文句（≥8字）**；文字必须来自 cue 字段，这样结构才能复用、镜头才不绑死内容。

**新增镜头** = 在 SCENE 区写 CSS + 在 EDIT ZONE 写 `function scene你的名字(c){...}` + 在 SCENES 数组加条目。

## Optional Generator

生成结构草稿（镜头内容仍需手动设计）：

```bash
node skills/audio-driven-video/scripts/create_project.js \
  --title "项目标题" \
  --audio "../input/voice.mp3" \
  --srt examples/minimal/input/demo.srt \
  --text examples/minimal/input/transcript.txt \
  --out examples/minimal/output/demo.html \
  --no-bgm
```

生成器只搭结构骨架，镜头内容全部为空。强劲的成品仍需根据 Step 0 意图表手动设计镜头。

## File Map

```text
skills/audio-driven-video/
├─ SKILL.md
├─ agents/openai.yaml
├─ assets/template.html              # 技术骨架 + 3个示范scene（★不是菜单★）
├─ references/
│  ├─ STYLE.md                       # 视觉原则 + 正反案例（去八股核心）
│  ├─ PIPELINE.md                    # 真实素材/校准/录屏导出
│  ├─ CLAUDE_CODE_PROMPTS.md
│  └─ case-library/                  # 优秀案例（审美参考，禁止抄镜头）
│     ├─ README.md
│     ├─ copy_driven_visual_short (33).html
│     ├─ porridge_truth_微信单文件版.html
│     ├─ 地球就是一个巨大的陌生人社交游戏-动态短片.html
│     └─ 动态视频网页素材.html
└─ scripts/
   ├─ create_project.js              # 生成结构草稿（镜头仍需手设计）
   ├─ create_demo_audio.js
   ├─ validate_html.js
   └─ validate_skill.js
```
