Demo Narrator(演示旁白师)
流程:提取帧 → 理解内容 → 起草脚本 → 用户审批环节 → 生成音效及语音合成 → 渲染 → 验证。
输出:output_final.mp4(H.264/AAC,-16 LUFS,内嵌字幕)+ subtitles.srt。
SKILL="<包含此 SKILL.md 的目录的绝对路径>" # e.g. ~/.claude/skills/demo-narrator 或 ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
在开始时解析一次 SKILL(取决于技能安装位置),之后一直使用绝对路径。
0. 准备工作
- 如果
$PY不存在,告知用户安装需要安装 ffmpeg + espeak-ng(Homebrew/apt)、Python 3.12 虚拟环境、PyTorch 以及约 400 MB 的模型权重;获得用户同意后,运行bash "$SKILL/setup.sh"(需要几分钟时间;在后台运行)。 - 在视频文件旁边选择一个工作目录:
WORK="<视频目录>/demo-narrator-work/<视频文件名>"。切勿向技能目录写入任何内容。 - 询问(一次提问,仅询问未知信息):产品名称及功能、目标观众、语气(默认:友好、自信、简洁)、语音偏好(默认为
af_heart),以及必须提及的内容(如行动号召、网址)。如果用户已表示“直接执行”,则从视频帧中推断这些信息,无需额外提问。
1. 提取帧 + 检查时长
"$PY" "$SKILL/scripts/extract_frames.py" "<视频>" --out "$WORK"
- 打印时长/分辨率,每 2 秒采样 1 帧,检测场景变化,生成 3×3 联系表。
- 拒绝时长小于 3 秒或超过 15 分钟的视频(可使用
--force/--max-duration覆盖;长视频可使用--interval 4)。 - 首先查看
$WORK/sheets/*.jpg(每张均标注有时间戳)。仅在需要细节时(如小字 UI 文本、点击发生的精确时刻)才打开$WORK/frames/*.jpg中的单个帧。 $WORK/frames.json包含duration、scene_changes(使用嗖声的最佳位置)以及帧列表。
构建一个节拍列表:每个时刻屏幕上显示的内容、发生的动作(点击、键入、页面切换、成功状态)以及观众应获得的要点。
2. 起草 $WORK/script.json
{
"video": "/abs/path/to/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Meet Relay, the fastest way to turn customer calls into tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Drop in a recording, and Relay pulls out every bug, request, and follow-up for you."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
时间规则
- 每段的字数预算 ≈
(结束时间 - 开始时间) × 2.5字(Kokoro 在速度 1.0 时约 150 词/分钟)。应保持在此预算内。 - 段落之间留出 ≥ 0.3 秒的间隔;第一句在约 0.3–0.8 秒处开始;在重要时刻后让视频自然停顿。
- 将
start锚定在被描述内容出现的时刻,而非之前。旁白可以领先动作约 0.3 秒。 - 段落不得超出视频时长;最后一段应在视频结束前 ≥ 1 秒结束。
面向听觉的写作
- 采用口语化风格、第二人称(“你”)、缩写、主动动词。每个段落只表达一个想法。
- 描述正在发生的事件的价值,而非像素画面。切勿使用“这里我们看到……”、“正如您所看到的……”。
- 按照口头表达的方式拼写:“两倍快”、“A-P-I”(仅当需要逐字母读出时)、“点 com”。避免使用符号、表情符号、带有斜杠的网址及括号。
- 使用短句。如果用户提供了行动号召,则以清晰的行动号召结尾。
音效(whoosh、whoosh_soft、pop、click、ding)—— at 为绝对视频时间。
whoosh用于页面/画面切换时(利用scene_changes),whoosh_soft用于面板/模态框滑动,pop用于元素/提示出现,click用于关键按钮按下,ding用于成功/完成。- 克制使用:最多约每 4–6 秒一个音效。音效之间不得在 0.3 秒内叠加。默认音量比语音低 −9 dB;可通过设置
gain_db(例如 −14)使音效更柔和。
语音(Kokoro):af_heart(温暖美式女声,默认)、af_bella、am_michael / am_fenrir(美式男声)、bf_emma(英式女声)、bm_george(英式男声)。其他语音在首次使用时自动下载。
3. ⛔ 脚本审批环节 — 强制要求
在用户明确批准脚本之前,不得生成任何音频。
-
以表格形式呈现脚本,然后停止:
# 时间 字数/预算 旁白内容 音效 1 0:00.4–0:04.6 11 / 10 ⚠ Meet Relay, … — 用 ⚠ 标记超出预算的段落。提及使用的语音及旁白总时长。最后询问: “请批准此脚本,或告诉我需要修改什么。”
-
结束你的回合并等待。 静默、“看起来不错?”或对之前版本的认可均不视为对当前版本的批准。
-
收到修改意见后:更新
script.json,重新呈现修改过的行,再次等待。 -
只有在用户对当前文本明确表示同意(“approve”、“yes”、“go”、“ship it”)后,才执行审批命令:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approve该命令会为旁白文本生成一个摘要哈希值。
generate_tts.py和render_video.py拒绝在未加盖审批戳记的脚本上运行,或脚本文本在加盖后发生更改——你必须重新走审批流程。切勿手动设置approved/approved_digest。时间(start/end)和音效(sfx)的修改无需重新审批。
4. 生成音效 + 旁白
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS 生成
$WORK/audio/seg_###.wav以及tts.json。引擎:Kokoro,自动回退到 Piper(使用--engine piper强制使用)。 - 每个音频片段被调整至其时间槽内(直到下一段开始);超出的部分会以更快的速度重新合成(最高
--max-speed 1.25)。 - 如果表格仍显示
OVER,则优先移动start/end或后续段落(无需重新审批)。如果必须缩短文本,则属于文本修改→返回审批环节。 - 重新生成单个段落:
--only 3 5。不同音效变体:--seed 7。
5. 渲染
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- 将音频片段放置在其
start时间点,绝不重叠;轻微超时部分会进行保持音高的atempo压缩(≤ 1.12×),剩余部分后移后续片段(打印为漂移量)。如果旁白时长超出视频,则保持最后一帧画面。 - 混合语音和音效,将响度标准化至 −16 LUFS,内嵌字幕(使用 Pillow 渲染字幕卡片 + FFmpeg
overlay,无需 libass),生成$WORK/output_final.mp4和subtitles.srt。 - 可选背景音乐(原创、本地合成、无需许可):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <视频秒数> --out "$WORK/bgm.wav"(风格:positive(默认)= 原声吉他十六分音符拨弦,带开放的泛音,每拍温暖的和弦击弦,底鼓四分音符,切分音拍手/拍击,弱拍贝斯,柔和的拨弦主旋律,111 BPM,中间有间奏,基于 B2B 演示参考;demo-bright/demo-dorian= SaaS 演示节奏,基于标准产品演示曲目:110 BPM,温暖的和弦以八分音符脉动并带有轻柔底鼓的泵感,第二拍和第四拍拍手,八分音符踩镲,和弦根音贝斯,持续的顶部线条,轻柔的拨弦旋律,前奏 → 节奏 → 中间八小节间奏 → 节奏 → 干净结尾;uke、marimba、pluck、kalimba= 明亮软件演示背景音,一个拨弦/木琴主题搭配简单的轻柔底鼓+响指/拍手+沙锤节奏及一点贝斯,100–112 BPM,大调;lofi(默认)= 带有鼓点的悠闲摇摆节奏;keys= 电钢琴;upbeat= 四分音符底鼓 + 琶音;ambient= 仅氛围音垫。--bpm、--key(明亮风格)、--mood(其他风格)、--seed N可用于生成变体)。先制作 30–40 秒的预览(--duration 40),让用户通过听觉挑选,然后使用--bgm "$WORK/bgm.wav"进行完整渲染。--bgm也可以接受用户提供的曲目(mp3/m4a/wav):它会自动调整至相同参考响度,如果曲目短于视频则带 2.5 秒交叉淡入淡出循环播放,并在结尾淡出。请用户确认他们拥有所提供曲目的使用权利。音乐在语音下方自动闪避;可通过--bgm-db(默认 -2.5)和--duck-db(默认 -5)进行调整。 - 常用参数:
--out <路径>、--orig-volume 0.15(安静地保留原始音频)、--sfx-gain-db -12、--no-subs(仍会生成subtitles.srt;当视频底部已有屏幕字幕时使用)、--font <ttf>、--font-scale 0.05、--crf 20。
6. 报告前验证
- 检查渲染输出:漂移列接近 0,无保持帧警告(或解释原因)。
- 抽样检查字幕:在 2–3 个段落中点处运行
ffmpeg -ss <时间> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<时间>.jpg",然后查看图像——字幕可读且未覆盖关键 UI 元素。如果覆盖了重要内容,考虑使用--font-scale或告知用户。 - 报告:输出路径、时长、使用的引擎/语音、被加速或移动的段落,以及修改方法(编辑
script.json→ 重新运行步骤 4–5;文本修改需重新经过审批环节)。
故障排除
| 症状 | 修复方法 |
|---|---|
kokoro unavailable … trying fallback | 重新运行 setup.sh;检查 .venv 中的 Python 版本是否为 3.10–3.12。Piper 输出可用但不够自然。 |
| 单词/名称发音错误 | 在 text 中按语音重新拼写(例如 “Kubernetes” → “koo-ber-net-eez”),获得审批后使用 --only 重新生成该段落。 |
| 旁白语速过快 | 将 speed 降低至 0.95,加宽段落时间窗口,或精简单词。 |
| 字幕太小/太大 | 调整 --font-scale 0.035–0.06。 |
| 颜色错误或 VFR 抖动 | 添加 --fps 30。 |
| 视频中含有您想保留的音乐 | 使用 --orig-volume 0.12–0.2。 |
所有操作在一次性模型下载后均可离线运行。许可证:Kokoro-82M Apache-2.0、Piper GPL-3.0(piper-tts ≥1.3)、语音模型按模型卡说明、FFmpeg LGPL/GPL。