前言¶
教学视频、操作演示类成片，常见痛点是：旁白要按画面切段、语速要和镜头对齐、字幕不能一整屏堆满字，还要在「AI 配音」和「保留原声演示」之间切换。单靠剪辑软件手工对轨，步骤多、返工也多。
下面介绍 SkillHub 上的 灵声工坊视频配音（smart-dubbing-studio）。它以通用 SKILL.md 约定工作流：由 Agent 对话收集素材路径、检测本机环境、选择 TTS 引擎，再一键执行 pipeline.py 输出带字幕的成品视频。SkillHub 分类为 design-media；社区侧可见评分约 98768、下载约 782 次（以 SkillHub 展示为准）。Skill 包版本为 1.0.7，Skill 页作者标注为 盛通教育-张维。
这是什么¶
灵声工坊视频配音是面向「源视频 + 时间轴配音模板」的智能配音与字幕同步 Skill。官方简介概括为：支持 TTS 语音生成、语速自适应加速、自动识别并填充静音段、逐句精校字幕，一键输出成品视频。
维护与分发在 SkillHub；技能标识在商店检索中为 @indiv-zhangwei/smart-dubbing-studio（部分页面链接仍使用 user_a5827f21 路径）。说明文档内流水线自称为视频字幕合成 V3.7.x，与 SkillHub 包版本号 1.0.7 并存，以各自字段为准即可。
核心功能¶
以下能力均来自技能包内 SKILL.md 与 scripts/ 流水线，可按步骤复现。
固定程序 + 对话引导¶
加载技能后，Agent 按文档要求向用户确认 源视频路径 与 字幕/配音模板路径（.md）。无模板时可复制内置模板：
python <本技能目录>/scripts/copy_template.py --to-dir <用户项目目录>
六步流水线¶
Agent 将 scripts/ 复制到用户项目的 _scripts/，生成 job.yaml 后执行：
python _scripts/pipeline.py --job job.yaml
顺序为：01_check 解析模板 → 02_cut 切分视频 → 03_tts 配音 → 04_align 对齐（含填充静音、必要时视频加速）→ 05_merge 声画合成 → 06_finalize 注入字幕。失败时可：
python _scripts/pipeline.py --job job.yaml --resume-from <步骤名>
仅重做字幕时：
python _scripts/pipeline.py --job job.yaml --resume-from 06_finalize
TTS 引擎¶
- 讯飞超拟人（spark）：需
APPID、APIKey、APISecret、超拟人WS URL，写入本地tts_config.json（文档建议加入.gitignore）。 - edge-tts：免费备用，
pip install edge-tts==7.2.8；可选音色如zh-CN-XiaoxiaoNeural等。
模板与段类型¶
模板为 Markdown 表格：| 开始时间 | 结束时间 | 文案内容 |，时间支持 MM:SS、MM:SS,FF（SMPTE 帧）、MM:SS.mmm。
- 正常文案：AI TTS 配音。
- 空白行：
filler，保留原视频音频。 (静音)/[静音]/（静音）：filler_silent，生成静音。
支持反引号 ` 控制 TTS 断句、{tts:...} 覆盖朗读文本而不改字幕显示；讯飞路径下可配合逐短句 SRT（依赖词级时间戳）。
字幕模板编辑器¶
技能自带 tools/subtitle-editor.html：浏览器中拖入视频、粘贴编号文案，用 F 键拍板时间轴，一键导出 .md 模板，适合不想手写时间码的场景。
环境依赖¶
env_check.py 会检查 ffmpeg、Python 3.7+ 等；选讯飞时需 websocket-client==1.8.0。缺失项的处理方式见 SKILL.md 中的对照表。
安装与启用¶
安装前请阅读 SkillHub 官方说明：skillhub.cn/install/skillhub.md。
1、安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可执行完整安装脚本（文档推荐）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2、安装本 Skill¶
必须使用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能无法被识别。
skillhub search smart-dubbing
skillhub install smart-dubbing-studio --namespace indiv-zhangwei --dir <skills 目录>
常见路径示例（以你实际使用的客户端为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下.agents/skills/
SkillHub 页面亦提供「发给 AI 的安装提示」：按 skillhub.cn/install/skillhub.md 安装 @user_a5827f21/smart-dubbing-studio。若网页显示 Skill 已下线，可仍以 CLI 搜索到的 @indiv-zhangwei/smart-dubbing-studio 为准安装（2026-10-21 经 skillhub install 可正常拉取）。
安装完成后重启或重新加载 Agent，使 SKILL.md 生效。
典型用法¶
经过上面的安装，在对话中可直接按技能文档操作。下面是一条可复现的主路径（由 Agent 执行命令，用户主要提供路径与 TTS 选择）。
- 用户提供源视频与模板，例如
demo.mp4与script.md。 - Agent 运行环境检测：
python _scripts/env_check.py --output env.json
- 用户选择引擎与音色后，Agent 生成
job.yaml（示例结构）：
video: "/path/to/demo.mp4"
template: "/path/to/script.md"
voice: "x5_lingxiaotang_flow"
engine: "spark"
output_root: "output"
env_file: "env.json"
tts_config: "tts_config.json"
若使用 edge-tts，将 engine 设为 edge，并省略或清空 tts_config。
- Agent 执行流水线并汇报进度；成品路径形如：
output/{task_id}/06_final/final_with_subs_xxx.mp4
模板表格示例（摘自技能文档）：
| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:02 | 本视频将讲解如何制作进阶笔筒。 |
| 00:02 | 00:03,17 | 首先制作底座，选取圆柱体。 |
适用场景与注意¶
适合谁：需要批量做中文讲解视频、微课、操作演示配音的团队或个人；希望由 Agent 代跑 ffmpeg + TTS 脚本、减少手工对轨的人。
限制与注意：
- 依赖本机 ffmpeg 与 Python 环境；讯飞方案需自行在 console.xfyun.cn 开通并保管凭证。
tts_config.json含密钥，勿提交到公开仓库。- edge-tts 下「逐短句 SRT」可能回退为整段字幕（文档说明词级时间戳主要来自讯飞）。
- 官方 API 页
https://api.skillhub.cn/user_a5827f21/smart-dubbing-studio对 GET 返回 405；SkillHub 部分 Web 详情页可能显示「已下线」，安装与文档以 CLI 拉取的包内SKILL.md为准。
结尾¶
灵声工坊视频配音把「切分、TTS、对齐、合成、字幕」收成一条 Agent 可执行的流水线，并附带拍板式模板编辑器，适合把重复劳动交给对话式自动化。需要查看商店条目或安装指引时，可访问 SkillHub 官方地址：https://api.skillhub.cn/user_a5827f21/smart-dubbing-studio，并配合 https://skillhub.cn/install/skillhub.md 完成安装。
