前言¶

录完教学视频后，常见流程是：按画面切分片段、逐段 TTS、对齐音画、再烧录字幕。步骤多、工具杂，时间码手写还容易和帧率对不齐。若希望由 Agent 按固定流程代劳——先检测环境、再选引擎与音色、生成配置并执行流水线，失败还能从断点续跑——SkillHub 上的「教学视频配音字幕合成」面向的就是这类需求。它与「从零写脚本拍片」不同，假定你已有源视频和带时间点的配音模板，重点在配音合成与字幕注入。

这是什么¶

「教学视频配音字幕合成」是 SkillHub 分类 design-media 下的 Agent Skill（包名在 CLI 中为 @indiv-zhangwei/video-tutorial-v2-publish，当前版本 1.0.20）。技能文档（SKILL.md）将其定位为固定程序模式：通过对话收集路径与 TTS 选项，由 AI 复制脚本、生成 job.yaml 并执行 pipeline.py，用户无需手改配置文件。

公开页 https://www.skillhub.cn/skills/user_a5827f21/video-tutorial-v2-publish 访问时可能显示 Skill 已下线；安装与内容仍以 SkillHub CLI 拉取为准。任务线索中的 API 地址 https://api.skillhub.cn/user_a5827f21/video-tutorial-v2-publish 对 GET 返回 405，不能当作文档页使用。

核心功能¶

下面介绍技能文档中已写明、且本地包内脚本对应的能力。

1. 对话式流程：确认源视频路径与字幕模板（.md）→ 自动环境检测 → 选择 TTS 引擎与音色 → 生成 job.yaml → AI 执行流水线并在对话中汇报进度。
2. 双 TTS 引擎：默认推荐讯飞超拟人（需本地 tts_config.json 凭证）；无密钥或用户选择时回退 edge-tts（免费，无需讯飞账号）。
3. 六步流水线（pipeline.py）：01_check 解析模板 → 02_cut 按时间切分视频 → 03_tts 配音 → 04_align 对齐（含 filler、加速、静音等决策）→ 05_merge 声画合成 → 06_finalize 逐句字幕注入成品 MP4。
4. 容错续跑：步骤失败时按文档执行 python _scripts/pipeline.py --job job.yaml --resume-from <步骤>。
5. 字幕模板工具：tools/subtitle-editor.html 支持浏览器内拖入视频、按 F 键拍板标记时间点，导出 .md 模板；也可用 copy_template.py 复制 script_template.md 手写时间码。
6. 模板能力：支持 MM:SS、MM:SS,FF（SMPTE 帧）、MM:SS.mmm；数学符号可自动口语化；可选多音字 {拼音+声调} 标注（讯飞）；| 可标记断句等（详见技能内 script_template.md）。

SkillHub 侧统计（任务线索）：评分 99136，下载约 1013 次。

安装与启用¶

先做 CLI 是否可用的检查，再把 Skill 装到当前 Agent 的 skills 目录（未指定 --dir 时默认 ./skills/，Agent 可能无法加载）。

command -v skillhub && skillhub --version

未安装 CLI 时，可按 SkillHub 安装说明执行完整安装或仅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安装本 Skill（与 skillhub search video-tutorial-v2-publish 结果一致）：

skillhub install video-tutorial-v2-publish --namespace indiv-zhangwei --dir <你的 Agent skills 目录>

常见 skills 目录示例（来自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下 .agents/skills/

也可在对话中让 AI 按官方提示安装（文档写法为引用 https://skillhub.cn/install/skillhub.md 并安装对应包名）。安装后需让 Agent 重新加载 skills 目录中的技能。

运行依赖（由 env_check.py 检测，技能文档摘要）：Python 3.7+、ffmpeg；选讯飞时需 websocket-client==1.8.0；选 edge 时需 edge-tts==7.2.8（Python 包，非微软商店应用）。

典型用法¶

经过上面的安装，在已启用该 Skill 的 Agent 中，可按技能规定的阶段操作。下面是可以复现的主路径。

1、提供素材路径

向 Agent 说明要合成视频，并提供：

• 源视频路径（如 /home/user/video/demo.mp4）
• 配音模板路径（如 /home/user/video/script.md）

若无模板，Agent 应执行（路径中的 <本技能目录> 换为安装后的技能根目录）：

python <本技能目录>/scripts/copy_template.py --to-dir <用户项目目录>

用户在 script_template.md 中填写时间点后继续。

2、环境检测（Agent 自动）

在用户项目下创建 _scripts/ 并复制技能内 scripts/*.py，然后：

python _scripts/env_check.py --output env.json

缺 ffmpeg 时按文档指引安装；缺 Python 包时 Agent 可执行例如：

pip install websocket-client==1.8.0
pip install edge-tts==7.2.8

3、选择引擎与音色

• 选 1（讯飞）：提供 APPID、APIKey、APISecret、WS URL（https://console.xfyun.cn），并选音色（如默认聆小糖 x5_lingxiaotang_flow），生成 tts_config.json。
• 选 2（edge-tts）：选晓晓 / 云希 / 晓伊 等 Neural 音色，无需 tts_config.json。

4、执行任务

Agent 生成 job.yaml 后自行运行：

python _scripts/pipeline.py --job job.yaml

成功时成品路径形如：output/{task_id}/06_final/final_with_subs_xxx.mp4。

5、用字幕编辑器制模板（可选）

用浏览器打开技能目录下的 tools/subtitle-editor.html，设置工作目录、拖入视频、粘贴编号文案，播放时按 F 标记切换点，再导出 .md 交给 Agent。

适用场景与注意¶

适合：已有画面教学视频、需要按时间点批量配音并烧录字幕的团队或个人；希望由 Agent 代跑 ffmpeg + TTS 流水线、减少手工拼命令的场景。

注意：

• 讯飞凭证只应写在本地 tts_config.json，技能文档要求提醒用户加入 .gitignore，勿提交仓库。
• 模板时间码与帧率：逗号格式按文档默认 30fps 解析；切分与对齐逻辑在 changelog 中多次修订，复杂模板建议先看 report.json 与技能 changelog。
• 同一作者另有「灵声工坊视频配音」（smart-dubbing-studio）等 Skill，能力侧重不同；本文仅描述 video-tutorial-v2-publish 包内行为。
• 若仅依赖网页详情，可能遇到「Skill 未找到」；以 CLI 安装到的 SKILL.md 与脚本为准。

结尾¶

「教学视频配音字幕合成」把环境检测、引擎选择、任务配置和六步合成收敛成 Agent 可执行的固定流程，并附带拍板式模板编辑器，降低教学片后期配音与字幕注入的门槛。安装与检索入口：

• SkillHub 安装说明：https://skillhub.cn/install/skillhub.md
• 任务线索中的 Skill 地址：https://api.skillhub.cn/user_a5827f21/video-tutorial-v2-publish（文档 GET 不可用；安装请用 skillhub install video-tutorial-v2-publish --namespace indiv-zhangwei）