Communitygithub.com

演示旁白师

将静默的产品演示或屏幕录制转化为带有自然人声旁白、清新 UI 音效(嗖声、爆破音、咔嗒声、叮当声)、可选背景音乐和字幕(内嵌或 .srt 文件)的解说视频。包含脚本审批环节,100% 本地免费运行。

演示旁白师 是什么?

Demo Narrator 是一个完全本地运行且免费的 AI 技能,能将无声的产品演示或屏幕录制转化为专业的、附带旁白的解说视频。它采用流水线式处理:从视频中提取关键帧,生成脚本草稿,然后强制进入一个“人工审批”环节——在生成任何音频前,用户必须明确批准脚本。批准后,系统利用 Kokoro-82M TTS(语音合成)引擎生成自然的人声旁白,并配合切换页面时的嗖声、点击时的咔嗒声等 UI 音效。还支持生成或导入背景音乐,并能自动将字幕(SRT 格式)或原生字幕渲染到视频中。该技能完全依赖 FFmpeg、Kokoro、Piper、numpy 和 scipy 等工具,无需任何 API 密钥或付费服务。它支持在 Cursor、Claude Code、Codex 等兼容开发环境中使用,用户可以用自然语言描述需求(如“为这个演示添加旁白和字幕”),然后 AI 会引导完成整个制作流程。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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. 准备工作

  1. 如果 $PY 不存在,告知用户安装需要安装 ffmpeg + espeak-ng(Homebrew/apt)、Python 3.12 虚拟环境、PyTorch 以及约 400 MB 的模型权重;获得用户同意后,运行 bash "$SKILL/setup.sh"(需要几分钟时间;在后台运行)。
  2. 在视频文件旁边选择一个工作目录:WORK="<视频目录>/demo-narrator-work/<视频文件名>"。切勿向技能目录写入任何内容。
  3. 询问(一次提问,仅询问未知信息):产品名称及功能、目标观众、语气(默认:友好、自信、简洁)、语音偏好(默认为 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. 以表格形式呈现脚本,然后停止:

    #时间字数/预算旁白内容音效
    10:00.4–0:04.611 / 10 ⚠Meet Relay, …—

    用 ⚠ 标记超出预算的段落。提及使用的语音及旁白总时长。最后询问: “请批准此脚本,或告诉我需要修改什么。”

  2. 结束你的回合并等待。 静默、“看起来不错?”或对之前版本的认可均不视为对当前版本的批准。

  3. 收到修改意见后:更新 script.json,重新呈现修改过的行,再次等待。

  4. 只有在用户对当前文本明确表示同意(“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. 报告前验证

  1. 检查渲染输出:漂移列接近 0,无保持帧警告(或解释原因)。
  2. 抽样检查字幕:在 2–3 个段落中点处运行 ffmpeg -ss <时间> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<时间>.jpg",然后查看图像——字幕可读且未覆盖关键 UI 元素。如果覆盖了重要内容,考虑使用 --font-scale 或告知用户。
  3. 报告:输出路径、时长、使用的引擎/语音、被加速或移动的段落,以及修改方法(编辑 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。

相关技能