Skip to content

threerocks/article2media / skills/explainer-video

explainer-video

Verified

口播视频:把一篇文章做成 1080×1920 竖屏讲解视频——你当导演写分镜脚本 video.json(黄金 5 秒钩子、每镜一个意思、回收要点),脚本完成配音(本地 VoxCPM2 / edge-tts / 系统语音,6 款公开音色)、逐字对齐、数字滚动和清单逐条出现等动画、主题样式字幕、封面、混音和自动审片。输入是文章(原文、译文、逐字稿),已有改写稿 content.json 时参考它的事实和结构。可以单独用,也可以接在抓取、视频转文字、改写后面。Use when the user wants a 口播视频, 短视频, 讲解视频, 视频号 / 抖音竖屏视频, 文字转视频, text-to-video or "把这篇文章做成视频".

FileKindSize
SKILL.mdskill md3.3 KB
agents/openai.yamlconfig234 B
references/video-guide.mdmarkdown20.6 KB
scripts/video.mjsexecutablescript809 B

references/video-guide.md

View on GitHub
# 口播视频指南(video.mjs)

把文章做成 1080×1920 竖屏讲解视频:封面 → 黄金 5 秒钩子 → 每镜一个意思 → 回收要点。
**你是导演**:先读懂内容、决定讲什么和怎么讲,再写 `video.json`;脚本负责配音、对齐、动画、混音和审片。

和同类「图文成片」工具最大的区别,也是你必须守住的三条:
1. **画面就是内容**:每一镜都用文章自己的数字、结构和原话(数字滚动、清单逐条出现、对比打勾),不用无关的素材图。
2. **说到哪、亮到哪**:每个元素在口播说到它的那个字时出现(逐字时间戳),观众的眼睛和耳朵始终在同一处。
3. **前 5 秒给出看下去的理由**:首句就是结果、冲突或问题,画面同时给出证据。

## 1. 先检查能力,再决定怎么跟用户说

```bash
node ${CLAUDE_SKILL_DIR}/scripts/video.mjs doctor
```

| 能力 | 有 | 没有时 |
|---|---|---|
| 配音 | 本地 VoxCPM2(48 kHz、可克隆、可加情绪指令)> edge-tts(免费、联网)> macOS 系统语音 | 只有系统语音时**先问用户**:照常出(声音偏机械),还是先装 uv 用 edge-tts(一条命令,免费) |
| 逐字对齐 | 本地 Whisper | 用 edge-tts 的词边界;都没有就按字数估算,交付时说明 |
| 插画 | Codex CLI(用 ChatGPT 登录)> OpenAI > Gemini(需付费层) | 不影响出片:封面只用排版,**不要问**,交付时提一句"装了 Codex CLI 可以自动配封面插画" |

原则:**能默认的不问**(音色、主题由你按内容选,交付时说明并告诉用户怎么换);只有结果明显变差、而用户可能想先改环境时才问。

## 2. 导演流程

### 2.1 一句话定调
写进 `director`(只是设计记录,不影响渲染,但要写,便于审片和修改):
- `audience`:谁会看,他们卡在哪。
- `core`:看完能带走的一句话。
- `hook_strategy`:从下表选一种主策略,必要时加一种辅助。
- `rehooks`:每 15–20 秒一个重新抓注意力的点(转折、"第 N 件事"、"最重要的是")。
- `payoff`:哪几镜兑现开头的承诺。

| 开场策略 | 用在 | 首句示例 | 首镜画面 |
|---|---|---|---|
| 结果前置 | 有可展示的成果、数字 | "从零开始,三个月涨到 1 万粉,她只做对了一件事。" | 数字滚动 + 证据截图 |
| 反常识 | 有证据支持的反差结论 | "多数人越休息越累,问题不在睡得少。" | 预期 vs 实际 |
| 痛点提问 | 观众有明确困扰 | "发了几百条帖,流量还是个位数?" | 卡住的处境 |
| 数字承诺 | 内容确有 N 条做法 | "三件事,决定你的账号能不能起来。" | 3 个编号,逐个点亮 |
| 身份共鸣 | 一类人的共同处境 | "下班后想做副业、又不会剪辑的人," | 身份标签 |
| 悬念缺口 | 有值得解释的原因 | "他差点在第三个月放弃,是什么留住了他?" | 已知事实 + 问号 |

不编造"常识",不夸大结果,不截断句子造悬念;数字必须来自原文。

### 2.2 结构(60 秒左右的模板)

| 段落 | 时长 | 任务 |
|---|---|---|
| 封面 | 0–0.75 s | 0.5 s 静止 + 0.25 s 渐隐。≤ 14 字标题,和首句说同一件事,关键词或数字用 `**…**` |
| 钩子 | 0.75–5 s | 首句 ≤ 19 字,**5 秒内说完**;画面给出证据。说不完就删字,绝不靠加快语速 |
| 承诺 | 5–10 s | 说清看完能得到什么(N 件事 / 一个答案) |
| 正文 | 10–50 s | 每镜一个意思,4–9 秒一镜;每 15–20 秒一个重新抓注意力的点 |
| 回收 | 最后 6–8 s | 清单回顾 + 一句可执行的行动号召(≤ 3 秒) |

口播 220–330 字,总长 50–80 秒最稳;超过 90 秒就删。

**语速:解说最忌急。** 目标约 4.5 字/秒(约 270 字/分钟,和平时认真讲话差不多),单段超过 5.2 字/秒判为偏快。内容多了就删内容,不要让旁白赶。具体做法:
- VoxCPM2 会照着参考音频的节奏读,所以公开音色的参考都控制在 4–5 字/秒。导入参考快于 5 字/秒会提示。
- 配音时每段都测语速,偏快的段换种子重新生成;用尽重试仍偏快的,保持音高放慢到约 4.8 字/秒(最多放慢 15%)。
- 句间停顿 0.34 s,镜头之间 0.5 s 起,画面需要时再加长。
- 审片会报「旁白语速」。

### 2.3 写口播(lines)
- **写给耳朵听**:短句,一句不超过 20 字;口语,但不用"家人们""绝绝子";不寒暄。
- 每镜 1–2 行(`lines` 每项是一行);一行说一个完整意思。
- 数字直接写阿拉伯数字(字幕更好认):脚本会自动读成中文(`2380 元` → 两千三百八十元,`20+` → 二十多,`2026年` → 二零二六年)。特殊读法用 `say`:`"say": {"X": "X", "GPT": "G P T"}`。
- 少用英文:常用词换中文说法;必须保留的产品名先试听。
- 用 `**关键词**` 标出这一句最该被记住的词:字幕里会变成主色。每行最多 1–2 处。
- **字幕**:
  - 单行,最多 13 字。同一句里的短语自动合并,句内逗号显示成空格,所以字幕大约 1.5–2.5 秒才换一次;超宽会缩小字号,不换行。
  - 换字幕是硬切,没有弹跳和缩放;短停顿里字幕一直留着,只有真正停下来(超过 1.4 s)才淡出。
  - 样式跟主题走,在 `themes/caption-styles.json` 里,共 7 种:
    - pill:卡片;
    - sticker:白字粗描边,例如多巴胺、波普、Y2K;
    - block:硬框,例如大字报、瑞士、像素、拼贴;
    - ink:无框墨字,例如杂志、静线、山水、大地、云舞、国潮印章;
    - marker:荧光笔,例如备忘录、手帐、孔版;
    - cinema:电影字幕;
    - glass:毛玻璃。
  - 个别视频要换样式,在 video.json 里写 `"captions": {"style": "ink"}`。
- 忠于原文:事实、数字、人名照原文;编者归纳的框架(比如"归纳起来就三件事")要说成归纳,别说成原话。高风险内容(擦边、违规做法、未核实的收益承诺)不进视频。

### 2.4 选镜头(type)

每个镜头都有 `id`、`type`、`lines`;元素用 `cue` 指定"说到哪个字时出现"(必须是这一镜口播里的原文片段,写错会退回估算并在 check 里提示)。

| type | 用在 | 关键字段 |
|---|---|---|
| `number` | 一个要记住的大数字、前后对比 | `label`、`start_text`(起点,如"零粉丝")、`from`、`to`、`prefix`/`suffix`、`count_cue`、`badge`+`badge_cue`、`image`(证据截图:`src`、`cue`、`note`) |
| `list` | N 件事、N 个原因 | `tags`(被划掉的标签,如"不会剪辑")、`title`+`title_cue`、`items[{text, cue, delay}]` |
| `timeline` | 经历、阶段、转折 | `title`、`points[{label, note, cue, low}]`(`low: true` 是低谷,红点脉冲) |
| `merge` | 几个因素合成一个结果 | `title`、`sources[{text, cue}]`、`target`、`target_cue`(带上升小折线) |
| `compare` | 对 vs 错、这样做 vs 别这样 | `chip`、`title`、`left/right{title, items[{text, cue, delay}]}` |
| `stats` | 两三个并列的量 | `chip`、`title`、`items[{value, prefix, suffix, label, cue}]`、`note`+`note_cue` |
| `quote` | 一句有力的原话 | `quote`(可含 `\n`)、`quote_line`(哪一行在念它,逐字点亮)、`by` |
| `checklist` | 收尾回顾 | `title`、`items[{text, cue}]`、`cta`+`cta_cue` |
| `title` | 一个判断、一个转场 | `title`(`**词**` 说到时划荧光)、`sub`、`image` |
| `image` | 原文配图、截图 | `src`(网络地址,或相对 video.json 的本地路径)、`title`、`caption`、`cue` |

镜头的通用字段:`chip`(左上角小标题,如"第 1 件事";含数字时背景会出现大号数字作章节感)、`deco`(自定义背景大字)、`hold`(这一镜结束后额外停顿秒数,通常不用写,脚本会自动保证最后一个元素出现后至少停留 1.1 秒)、`illustration`(这一镜要 AI 插画时写画面描述;有出图能力时生成并放进画面,没有就跳过,镜头照常)、`illustration_place`(`top`:内容上方的一张图,`title`、`quote`、`number` 镜头默认;`bottom`:字幕下方的通栏画面,其余镜头默认。不写就按默认)、`clip`(原视频片段)和 `transition`(转场),见 2.7。

**节奏原则**:
- 每 2–4 秒画面要有变化(新元素、数字滚动、打勾、高亮);审片会报"最长画面静止"。
- 一镜里的元素按口播顺序出现;同时出现的多个元素用 `delay` 错开 0.3 秒。
- 标题在镜头开始时就在(不留空屏),说到标题时再强调一下。
- 结论性的画面(清单全部出现、数字滚完)要留时间看清:脚本会自动加停顿。

### 2.5 封面
```json
"cover": { "kicker": "副业 · 3 个月", "title": "从零开始\n涨到 **1 万粉**", "illustration": "画面描述(可选,英文更稳)" }
```
- 第一帧就是封面:平台缩略图、小红书 3:4 裁切(`cover-3x4.jpg`)都用它,主要内容会落在中间 1080×1440 里。
- 标题 2 行、每行 ≤ 8 字最醒目,和首句说同一件事。
- 有出图能力时写 `illustration`:画一个具体场景,画风按主题自动加;人物用泛指("一个年轻人"),按原文写对性别、年龄,不画真实人物。

### 2.6 音色

**两个音色库(版权优先):**

| 库 | 位置 | 收什么 | 能否公开 |
|---|---|---|---|
| 公开音色 | `assets/voices/`(随 skill 分发) | VoxCPM2 仅凭文字描述设计、不对应任何具体的人(`designed`),或本人 / 已授权且同意公开的声音 | 可以 |
| 本机个人音色库 | `~/.local/share/article2media/voices/` | 用国民音色、平台 TTS、影视原声、网上片段等作参考克隆的声音(`personal` / `self` / `authorized`) | 不随 skill 分发、不进仓库 |

用参考音频克隆出来的声音,不论再怎么重新合成,只要一般听众能听出是谁,就仍然涉及原声音权人的权利(《民法典》第 1023 条;北京互联网法院 2024 年 AI 声音侵权案)。所以克隆音色一律只进本机库,公开音色只用文字描述设计。

- **默认用公开音色**,按内容选:`news-man` 资讯播报男声(默认;资讯、财经、科技、自媒体干货)、`sweet-woman` 甜美知性女声(生活、情感、知识)、`lively-promo` 活力种草女声(种草、探店)、`documentary-man` 纪录片旁白男声(历史人文、深度)、`northeast-guy` 东北热情大哥(搞笑、接地气)、`gentle-tw-accent` 台湾口音温柔女声(情感、闲聊)。`video.mjs voices` 查看全部。
- **本机个人音色**只在用户明确指定时用(`voice.id` 或 `--voice`);审片和 post.md 会提醒公开发布前确认授权。
- 导入参考:`video.mjs voice-import <音频> --id <id> --name <名称> --rights personal --source "来源"`。会切出 6–15 秒、在停顿处起止的片段,转 48 kHz,自动出逐字稿(要人工核对,高保真克隆要求一字不差),并检查削波、背景音(停顿深度)、原始采样率和码率。
- 设计公开音色:`video.mjs voice-design --id <id> --name <名称> --prompt "声音特征描述"`。描述只写年龄、音色、语速、情绪、口音、用途,不能点名任何人或平台音色(会被拒绝)。会生成多个候选,排序依据是:
  - 是否通过检查:错字率、音高与性别一致、语速 3.6–5 字/秒;
  - 语速离 4.5 字/秒多近;
  - 错字率;
  - 停顿深度。

  用户听过后 `voice-import … --rights designed --public` 转正。注意:纯文字设计控制不住语速,描述里写「语速偏慢」也常常偏快。
- 改造已有音色:`video.mjs voice-design --id <id> --from <已有音色> --prompt "语速放慢,平稳从容"`。保留原音色、只改语气或语速:用原参考做可控克隆,音高偏离原音色超过 12% 的候选判为变了声。改造后的音色权利与原音色相同,个人音色改完仍只进本机库。

**情绪与方言(可控克隆):** 在某一行口播前加括号指令,例如 `"(极度愤怒,东北话)注意看!这个男人叫小壮!"`、`"(哽咽,带哭腔)那三个月,几乎没人看。"`。括号里的字不进字幕;这一行改用「参考音频 + 指令」模式(VoxCPM2 的高保真模式会忽略指令)。少用:一条视频里情绪句太多会让音色在两种模式之间来回切换。

**音质与稳定:**
- VoxCPM2 原生输出 48 kHz,全程保持 48 kHz,成片 AAC 256 kbps。克隆质量受参考限制:参考是 24 kHz、低码率 MP3 时导入会提示。
- **长文本漂移**:口播按句切成不超过 90 字的段,每段都用同一条固定参考生成(不让误差累积);每段测音高,偏离参考超过 22% 判为漂移并换种子重生(带情绪指令的句子不查音高)。
- **中英混读**:每段的英文词必须出现在识别结果里,否则换种子重试(最多 5 次)。先用 `video.mjs probe --voice <id> "Claude Code" "GPT"` 试读,读不准的在 `say` 里写读法(`"Claude": "克劳德"`、`"GPT": "G P T"`),或改用中文说法。

- 默认**没有背景音乐**:只有配音和镜头切换时很轻的转场音。用户给了音乐文件才加(见 2.7);没给就请用户在平台 App 里选。

### 2.7 片段、配乐、转场(都是可选的,不写就和以前一样)

这三样用来让视频不像“会动的幻灯片”。都只用用户手里已有的本地文件:脚本不下载、不生成、不自带任何视频和音乐。

**原视频片段 `clip`**(写在镜头里)

```json
{ "id": "demo", "type": "title", "lines": ["…"], "title": "…",
  "clip": { "src": "../src-videos/v1.mp4", "start": 12.5, "end": 18, "place": "top", "audio": false } }
```

| 字段 | 说明 |
|---|---|
| `src` | 本地视频,路径相对 video.json 所在目录,或绝对路径。也可以写 `meta.json` 的 `videos[]` 里的视频地址,但文件必须已经下载到 `<目录>/videos/`:没下载时 check 会给出 curl / yt-dlp 命令,由用户决定要不要下载 |
| `start` / `end` | 取片段的哪一段(秒)。`start` 默认 0,`end` 默认播到镜头结束 |
| `place` | `top`(默认):内容上方的一张画面,适合 `title`、`quote`、`number`;`bottom`:字幕下方的通栏;`full`:铺满整屏、压在内容后面,上面盖一层页面底色的遮罩,文字和字幕照常清楚 |
| `audio` | 默认 `false`(静音)。`true`:片段原声轻轻垫在旁白下面(约比旁白低 14 dB,`volume` 可调,0–1) |
| `scrim` | 只对 `full` 有效:遮罩浓度 0–0.95,默认 0.66。画面太花、字不清楚就加到 0.8 |

什么时候用:
- 文章讲的就是这段视频里的东西(产品演示、操作录屏、原作者出镜、帖子附带的视频),而且口播这一句正在说它。画面要是证据,不是装饰。
- 一条视频里 1–3 镜就够;其余镜头照常用数字、清单、对比。
- 内容多的镜头(`list`、`compare`、`stats`、`checklist`)用 `bottom` 或 `full`,别用 `top`(会把内容挤小)。
- 片段比镜头短时停在最后一帧(渲染时会提示):把 `start` / `end` 取得和这一镜差不多长,一般 4–8 秒。
- 片段按槽位居中裁切:横屏片段放 `top` 最合适,竖屏片段放 `full`。
- 片段里不加任何字;要说明的话写在镜头的标题或字幕里。同一镜写了 `clip` 就不再生成 `illustration`。
- 只用用户有权使用的视频;交付时说明用了哪段、来自哪里。

**背景音乐 `music`**(写在顶层)

```json
"music": { "src": "../music/bed.mp3", "volume": 0.15, "duck": true }
```

- `src`:用户提供的本地音频。没有就不写,不要找、不要下载、不要生成。
- `volume`:相对旁白的响度(先把音乐量到和旁白一样响,再乘这个数),默认 0.15,0.1 很轻,0.3 已经明显。
- `duck`:默认 `true`,旁白说话时再压低一半,短停顿里不回升(不会忽大忽小),封面和最后一句说完后回到原音量;`false` 全程同一音量;也可以写 0–1 的压低比例。
- 音乐比视频短会循环(接缝处交叉淡化),比视频长就截断;开头淡入、结尾淡出。
- 旁白的响度不受影响:音乐是在旁白定好响度之后才垫进去的。
- 什么时候用:用户明确给了音乐文件,或要求成片自带配乐。选没有人声的纯音乐;有人声的歌会和旁白打架。交付时提醒用户确认音乐可以公开使用。

**转场 `transition`**(顶层写一个作为全片默认,或写在某一镜里,表示“这一镜怎么进来”)

| 值 | 效果 | 用在 |
|---|---|---|
| `rise` | 上一镜上移淡出,这一镜从下方升入(默认,不写就是它) | 通用 |
| `cut` | 硬切,没有转场音 | 快节奏、连续举例、带片段的镜头之间 |
| `fade` | 交叉淡化 0.4 秒 | 语气放缓、进入结论或金句 |
| `slide` | 上一镜向左淡出,这一镜从右滑入 | 并列的几条(第 1 条 → 第 2 条) |
| `push` | 这一镜把上一镜整屏向左推出去 | 换话题、进入新的一段;配 `full` 片段最明显 |

- 全片以一种为主,只在段落转折处换一种;每镜都换会显得花。
- 转场不改变时间轴:镜头时长、字幕、口播对齐都和不写时一样。

## 3. 命令

```bash
node ${CLAUDE_SKILL_DIR}/scripts/video.mjs check  <目录>/video/video.json   # 校验:首句长度、cue、字幕长度、预计时长
node ${CLAUDE_SKILL_DIR}/scripts/video.mjs make   <目录>/video/video.json   # 配音 → 插画 → 渲染 → 审片
node ${CLAUDE_SKILL_DIR}/scripts/video.mjs render <目录>/video/video.json --theme brutal   # 换主题重渲(配音复用)
```
- 配音按句缓存:只改了某一镜的口播,只会重新生成那几句。
- 输出在 `<目录>/video/<主题>/`:`video.mp4`、`cover.png`、`cover-3x4.jpg`、`captions.srt`、`post.md`(发布文案和 AI 声明)、`contact-sheet.jpg`(审片总览)、`review.json`。

## 4. 审片(必须做)

1. 看 `contact-sheet.jpg`:封面、渐隐、1.6 s、3.2 s、5 s 前,以及每一镜的开始和结尾。
   - 前 5 秒:只看画面,能不能知道这条视频和"我"有什么关系、能得到什么?
   - 每一镜:画面是不是在说口播正在说的事?有没有空屏、挤成一团、元素压到字幕?
2. 看命令输出的检查项(也在 `review.json`):
   - 首句说完 ≤ 5.2 s;第一个画面信息 ≤ 2.5 s;最长画面静止 ≤ 5 s;旁白语速 ≤ 5 字/秒;字幕没有闪断(<0.6 s 的空档)、平均停留 ≥ 1.3 s;字幕丢帧 0 帧(逐帧检查成片,该有字幕的帧不能是空的);配音质检无问题。配音质检报的错字如果只是同音字(往上 → 网上、俯仰 → 抚养),音频没有问题,交付时说明即可。
   - 字幕丢帧是渲染缺陷,会记成 ✗ 并让命令以非零码退出;其余检查项是 ⚠ 提示,由你判断后修改脚本。旁白语速按“字”计:英文单词按音节算(约 3 个字母 1 字,GPT 这类缩写按字母算),不会因为句子里有英文就被判成语速过快。
   - ✗ 超出安全区:缩短文字或减少项目。安全区是成片里 x 60–936、y 240–1324 像素(舞台 CSS 坐标 x 30–468、y 120–662):上面留给平台的标题栏,下面留给字幕、按钮和简介。
   - 用了片段:在 contact-sheet 里确认片段出现在对的位置、标题和字幕压在上面仍然清楚(`full` 不清楚就调高 `scrim`);`full` 镜头的字幕丢帧量不出来,不做逐帧检查。「片段比镜头短」是提示,嫌定格太久就改 `start` / `end`。
   - 用了配乐:检查项会报音乐在空档和旁白下的响度,以及加配乐后的成片响度和峰值。
3. 改 `video.json` 后重新 `make`,最多 2 轮。听感(音色)你听不到:交付时如实说明,请用户听一遍。

## 5. 交付

告诉用户:
- `video.mp4` 路径、时长;封面路径;一句话的镜头大纲。
- 用了哪个音色(公开音色还是本机个人音色),以及怎么换:`--voice sweet-woman`;用了本机个人音色时,提醒公开发布前确认授权。
- 用了哪些能力、缺了什么(例如"没有出图能力,封面只用了排版")。
- 发布前提醒:在平台勾选「AI 生成」声明(视频首帧和元数据已标注);没加配乐时说明视频没有背景音乐,需要的话在平台 App 里加。
- 用了片段或配乐:说明用的是哪个文件、哪一段,提醒确认有权公开使用(`post.md` 里也写了)。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall