🎬 视频字幕合成技能 V3.7

> 固定程序模式 — AI 对话式引导，自动配置，一键执行。无需用户手动操作。

🔔 首次加载指引

加载本技能后，必须立即向用户推送以下信息：

🎬 视频字幕合成 V3.7 已就绪！

只需告诉我：
  • 源视频文件路径
  • 字幕模板文件路径（.md 格式）

其他一切交给我——环境检测、引擎配置、TTS配音、字幕注入，全自动完成。

💡 制作字幕模板？推荐使用「字幕模板编辑器」：
  用浏览器打开 tools/subtitle-editor.html → 拖入视频 → 粘贴字幕文案 → 按 F 键拍板标记 → 导出 .md

📂 技能文件

<本技能目录>/
├── SKILL.md
├── scripts/                  ← AI 从这里复制程序到用户项目
│   ├── env_check.py
│   ├── step01_check.py
│   ├── step02_cut.py
│   ├── step03_tts.py
│   ├── step04_align.py
│   ├── step05_merge.py
│   ├── step06_finalize.py
│   ├── pipeline.py
│   ├── copy_template.py
│   └── script_template.md
├── tools/                    ← 辅助工具
│   └── subtitle-editor.html  ← 字幕模板编辑器（按键拍板式）
└── references/
    └── DESIGN.md

🤖 AI 对话交互流程（核心）

阶段 1：接收用户请求

用户说"帮我合成视频"或类似请求。AI 必须确认两个路径：

请提供：
1. 源视频路径（如 D:/视频/demo.mp4 或 /home/user/video/demo.mp4）
2. 配音模板路径（如 D:/视频/script.md 或 /home/user/video/script.md）

> 如果用户没有模板：AI 必须执行以下操作：

> ```bash

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

> ```

> 执行后告知用户："📝 模板已复制到 <用户项目目录>/script_template.md，请打开填写时间点和文案，完成后告诉我路径即可合成。"

阶段 1.5：AI 展示模板格式（用户有模板时也执行）

当用户提供了模板路径，但 AI 需要在对话中展示格式参考时：

python <本技能目录>/scripts/copy_template.py --chat

读取 stdout 输出，向用户展示模板格式说明。

阶段 2：环境检测（AI 自动执行）

AI 自行执行，无需用户干预：

复制程序：在用户项目目录下创建 _scripts/ 子目录，将本技能 scripts/ 目录下的所有 .py 文件复制进去。

AI 已知本技能的安装路径（加载时系统会告知）
用文件操作工具复制，不要写死绝对路径
重要：程序文件放入 _scripts/ 子目录，不要和视频/模板文件混在同一目录。目录结构：

```

用户项目目录/

├── 视频文件.mp4 ← 用户的素材

├── 模板文件.md ← 用户的模板

├── _scripts/ ← 程序文件（AI 创建）

│ ├── env_check.py

│ ├── step01_check.py

│ └── ...（共 9 个 .py 文件）

├── env.json ← 环境检测输出

├── tts_config.json ← 讯飞凭证（如适用）

└── output/ ← pipeline 自动创建

```

Windows/Linux 均使用各自系统的文件 API

运行环境检测：

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

读 env.json，按情况处理：

env.json 状态	AI 行为
-------------	---------
`missing` 含 `ffmpeg`	告知用户："📦 需要安装 ffmpeg。下载地址：https://www.gyan.dev/ffmpeg/builds/ → 下载 `essentials_build` → 解压到任意目录 → 告诉我路径"
`missing` 含 `websocket-client`	AI 自行执行：`pip install websocket-client==1.8.0`，失败则加国内镜像 `-i https://pypi.tuna.tsinghua.edu.cn/simple`
全部通过	进入阶段 3

阶段 3：TTS 引擎选择（AI 提问 + 用户选择）

AI 必须主动提问，原文如下：

🔊 请选择 TTS 配音引擎：

1. 讯飞超拟人（推荐）— 音质最佳，需讯飞账号凭证
2. edge-tts（免费备用）— 微软服务，无需配置

请输入 1 或 2：

用户选 1（讯飞）：

AI 追问凭证：

请提供讯飞凭证（在 https://console.xfyun.cn 获取）：
  • APPID：
  • APIKey：
  • APISecret：
  • WS URL（在 https://console.xfyun.cn 获取超拟人端点）

（凭证仅保存在本地的 tts_config.json，不会上传）

> 安全提醒：凭证写入 tts_config.json 后，提醒用户将此文件加入 .gitignore。

用户提供凭证后，AI 问音色：

🎤 请选择讯飞音色：

1. 聆小糖（女，活泼流畅）— 默认，适合通用教学
2. 聆小璇（女，柔美自然）
3. 聆飞逸（男，稳重有力）
4. 聆小玥（女，清晰明亮）
5. 聆玉昭（女，自然亲切）

请输入 1-5（默认 1）：

根据用户选择，映射为 vcn：

1 → x5_lingxiaotang_flow
2 → x5_lingxiaoxuan_flow
3 → x5_lingfeiyi_flow
4 → x5_lingxiaoyue_flow
5 → x5_lingyuzhao_flow

AI 创建 tts_config.json：

{
  "spark": {
    "app_id": "<用户提供>",
    "api_key": "<用户提供>",
    "api_secret": "<用户提供>",
    "ws_url": "<用户提供>",
    "default_voice": "<用户选择的vcn>"
  }
}

用户选 2（edge-tts）：

AI 问音色：

🎤 请选择 edge-tts 音色：

1. 晓晓（女，温柔）— 默认
2. 云希（男，正式）
3. 晓伊（女，活泼）

请输入 1-3（默认 1）：

根据选择映射：

1 → zh-CN-XiaoxiaoNeural
2 → zh-CN-YunxiNeural
3 → zh-CN-XiaoyiNeural

不需要 tts_config.json，跳过创建。

用户说"没有讯飞 key"：

AI 直接走 edge-tts 流程，不追问。

阶段 4：AI 自动生成 job.yaml

AI 根据已收集的信息，自动创建 job.yaml：

video: "<用户在阶段1给出的视频路径>"
template: "<用户在阶段1给出的模板路径>"
voice: "<阶段3选择的音色>"
engine: "<spark 或 edge>"
output_root: "output"
env_file: "env.json"
tts_config: "tts_config.json"
# template_fps: 30  # 高级：手动指定模板帧率（程序默认自动检测，通常无需设置）

> 如果 engine=edge，不写 tts_config 这一行，或写 tts_config: ""。

阶段 5：AI 一键执行（不是让用户执行）

AI 自行执行以下命令，并在对话中报告进度：

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

将 pipeline.py 的标准输出实时展示给用户。每完成一步报告一次：

✅ 01_check  → 10段解析完成
✅ 02_cut    → 10段切分完成
✅ 03_tts    → 10段配音完成（讯飞spark）
✅ 04_align  → 对齐完成（含 filler/加速/冻结/静音决策）
✅ 05_merge  → 声画合成完成
✅ 06_finalize → 逐句字幕注入完成

🎉 成品：output/{task_id}/06_final/final_with_subs_xxx.mp4

阶段 6：容错处理

如果某步骤失败，pipeline.py 会输出 resume 命令。AI 必须：

读错误信息，判断原因
常见情况：

错误	处理
------	------
讯飞某段 TTS 超时	直接执行 resume 命令重试
ffmpeg 命令失败	检查路径/权限，告知用户
模板解析失败	分析 report.json，提示用户修改模板

执行 resume：

python _scripts/pipeline.py --job job.yaml --resume-from <失败的步骤>

📋 配置清单（AI 记住）

文件	谁创建	何时创建	内容
------	--------	----------	------
`env.json`	AI 自动	阶段 2	环境检测结果
`tts_config.json`	AI 自动	阶段 3（仅 spark）	讯飞凭证
`job.yaml`	AI 自动	阶段 4	任务配置
`output/`	pipeline 自动	阶段 5	所有输出

用户不需要手动创建或编辑任何文件。一切由 AI 对话引导完成。

🎤 音色速查（供 AI 参考）

讯飞 spark

#	名称	vcn	风格
---	------	-----	------
1	聆小糖	`x5_lingxiaotang_flow`	女，活泼流畅（默认）
2	聆小璇	`x5_lingxiaoxuan_flow`	女，柔美自然
3	聆飞逸	`x5_lingfeiyi_flow`	男，稳重有力
4	聆小玥	`x5_lingxiaoyue_flow`	女，清晰明亮
5	聆玉昭	`x5_lingyuzhao_flow`	女，自然亲切

edge-tts

#	名称	voice	风格
---	------	-------	------
1	晓晓	`zh-CN-XiaoxiaoNeural`	女，温柔（默认）
2	云希	`zh-CN-YunxiNeural`	男，正式
3	晓伊	`zh-CN-XiaoyiNeural`	女，活泼

⚠️ 环境缺失处理指南

缺失项	AI 必须告知用户
--------	---------------
ffmpeg	"请安装 ffmpeg。Windows: https://www.gyan.dev/ffmpeg/builds/ → 下载 `essentials_build` → 解压 → 把 `bin/` 路径告诉我。Linux: `sudo apt install ffmpeg` 或 `brew install ffmpeg`"
Python	"需要 Python 3.7+：https://www.python.org/downloads/"
websocket-client	AI 自动执行：`pip install websocket-client==1.8.0`。如失败，尝试国内镜像：`pip install websocket-client==1.8.0 -i https://pypi.tuna.tsinghua.edu.cn/simple`
edge-tts（选了 edge 引擎时）	AI 自动执行：`pip install edge-tts==7.2.8`。如失败，尝试国内镜像：`pip install edge-tts==7.2.8 -i https://pypi.tuna.tsinghua.edu.cn/simple`。注意：这是 Python 包，不是微软商店的 EdgeTTS 应用。

> 重要：edge-tts==7.2.8 是 Python 包（pip install edge-tts==7.2.8），利用微软 Edge 浏览器的免费 TTS 服务。不是微软商店的 EdgeTTS 应用。不需要用户去微软商店下载。国内网络如 pip 直连失败，AI 自动追加 -i https://pypi.tuna.tsinghua.edu.cn/simple 重试。

🖱️ 字幕模板编辑器（"按键拍板" — 推荐制模方式）V3.5.6

目的：解决老师对照视频手动写时间码的痛点。

工具路径：<本技能目录>/tools/subtitle-editor.html

工作流

准备字幕文案 → 设工作目录 → 拖入视频 → 粘贴文案 → 播放视频 → 按F键拍板 → ⚡一键生成提示词

步骤	操作	说明
------	------	------
1	编写文案	用记事本写好字幕，按 001/002/003 编号
2	打开工具	双击 `subtitle-editor.html`，浏览器打开
3	设工作目录	工具栏输入项目绝对路径（如 D:\项目\视频），点击设置
4	拖入视频	把视频文件拖到浏览器窗口
5	粘贴字幕	点击「粘贴字幕」，把序号文案粘贴进去
6	按键拍板	播放视频，每到一个切换点按 F 键；← → 精调（单击1帧，按住8x快进）
7	一键生成	点击 ⚡ 一键生成提示词 → 自动下载.md + 复制提示词到剪贴板

核心机制

F 键 = 拍板标记：每次按下，当前视频时间自动对应到当前字幕的结束时间
自动衔接：上一段结束时间 = 下一段开始时间（无缝连续）
精确逐帧：单击 ← → 精确走 1 帧；长按 → 8x 高速播放（playbackRate，丝滑不卡）
Ctrl+Z 撤销：按错了随时撤销上一个标记
自动缓存：所有标记 + 工作目录自动保存到 localStorage，关闭浏览器也不丢
一键生成提示词：⚡ 自动下载 .md + 构建完整提示词 + 复制到剪贴板，直接粘贴给 AI
路径校验：工作目录 3 层校验（无效字符/非绝对路径/像文件名），防止误存

AI 引导话术

当用户不知道如何制作模板时，AI 应主动推荐：

建议使用「字幕模板编辑器」制作模板，比手动写快很多：

1. 先用记事本写好每段字幕文案（按顺序编号）
2. 用浏览器打开 tools/subtitle-editor.html
3. 设置工作目录 → 拖入视频 → 粘贴字幕 → 播放视频
4. 每到画面切换点，按 F 键标记；← → 精调位置
5. 全部标记完成 → 点击 ⚡ 一键生成提示词
6. 把生成的提示词粘贴给我即可

📝 模板格式（供用户参考）

| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:02 | 本视频将讲解如何制作进阶笔筒。 |
| 00:02 | 00:03,17 | 首先制作底座，选取圆柱体。 |

时间 MM:SS，帧数后缀 MM:SS,FF
SMPTE 时间码：逗号后为帧编号（如 00:12,19 = 12 + 19/fps 秒），非小数点
自动适配：程序检测到 MM:SS,FF 逗号格式时，自动按 30fps（剪映默认帧率）解析，用户无需任何配置
也支持小数点格式 MM:SS.mmm
数学符号自动口语化：-5 → 朗读"负5"、5+3 → "5加3"、× → "乘"、÷ → "除以"（无需手动改写）
文件编码 UTF-8 / GBK 均支持

!ScreenShot_2026-05-14_114914_820.png

📋 变更日志

版本	日期	变更
------	------	------
3.7.3	2026-05-21	紧急修复 edge-tts "念网址"异常：`step03_tts.py` 的 `normalize_polyphone()` 对 edge-tts 引擎不再生成 SSML，改为直接剥离多音字标注。根因：CLI `--text` 将 SSML XML 标签+命名空间 URL（`http://www.w3.org/...`）当作正文朗读，导致 TTS 听感异常。修复后 edge-tts 依赖自身模型推测发音，不再尝试 SSML 控制。
3.7	2026-05-16	逐短句 SRT + filler 段 + 视频加速：`step06_finalize.py` 新增 `split_text_into_phrases()` 按中文标点拆短句 + `load_words_timestamps()` 加载词级时间戳 + `align_phrases_to_timestamps()` 按字数比例分配时间 → SRT 字幕"读一句显示一句"不超出画面。`step04_align.py` 新增 filler 段检测（空白行→保留原音）+ `speedup_video()` 视频加速（setpts 滤镜）。`step05_merge.py` 新增三段式分支（filler/静音/正常）。`pipeline.py` 新增 `--speedup` 和 `--audio` 参数传递。`subtitle-editor.html` V3.7：自动编号、空白行→filler、间隔级联。
3.6	2026-05-15	多音字标注功能：`step03_tts.py` 新增 `normalize_polyphone()` 和 `pinyin_to_sapi()` 函数——用户可在模板中用 `{拼音+声调}` 标记多音字正确读音（如 `倒{dao3}角`），标注不出现在字幕中；edge-tts 通过 SSML 精确控制发音；讯飞 spark 去除标注依赖模型上下文。`script_template.md` 新增多音字标注文档。

363→| 3.5 | 2026-05-14 | TTS韵律优化 + 字幕编辑器 V3.5.6：step03_tts.py 新增 normalize_prosody() 自动韵律预处理——用户可在模板中用 | 标记强制断句（不出现在字幕中），第X步 后自动插入逗号换气；script_template.md 新增 | 标记文档。字幕编辑器方向键双模式重构、路径校验、一键提示词。 |

3.3	2026-05-13	模板文档完善：`script_template.md` 重写，新增三种时间格式对照表（`MM:SS` / `MM:SS,FF` / `MM:SS.mmm`），重点标注逗号=帧分隔符非小数点，增加帧号示例和剪映查看指引。
3.2	2026-05-13	修复视频切分帧偏移问题（根因）：`step01_check.py` 的 `parse_time_cn()` / `parse_time()` 将 SMPTE 时间码的逗号从"小数点"改为"帧编号"语义（如 `00:12,19` = 12+19/fps 秒，而非 12.19s）；`parse_template()` 新增 fps 参数传递。`step02_cut.py` 的 `-ss` 移至 `-i` 之前（单次关键帧定位），配合正确时间戳后切分准确可靠。
3.1	2026-05-13	新增 `copy_template.py` 模板分发程序；step03_tts.py 新增数学符号口语化预处理（`-`→负/减、`+`→加、`×`→乘、`÷`→除以）；step02_cut.py 修复切分偏移（保证最小1帧输出）
3.0	2026-05-09	固定程序模式。完整的 AI 对话交互流程。讯飞超拟人主力 + edge备用。

🔒 分享前检查清单

> 当用户要求「创建分享副本」「发布技能」「脱敏分享」时，AI 必须逐项执行以下检查，不得跳过。

必须清除的敏感信息

检查项	关键词/模式	替换为	检查位置
--------	------------	--------	----------
讯飞 APPID	`"app_id": "数字"`	`"app_id": "<你的APPID>"`	`references/DESIGN.md`、`SKILL.md`
讯飞 APIKey	`"api_key": "十六进制"`	`"api_key": "<你的APIKey>"`	`references/DESIGN.md`
讯飞 APISecret	`"api_secret": "十六进制"`	`"api_secret": "<你的APISecret>"`	`references/DESIGN.md`
私有 WS 端点	`wss://.xf-yun.com/.private/.*`	`<你的讯飞超拟人WS端点>`	`references/DESIGN.md`、`SKILL.md`
`__pycache__/`	编译缓存目录	删除	`scripts/__pycache__/`

执行步骤

复制整个技能目录到分享位置（如 D:\minimax\zmrobo\video-tutorial-v2-share/）
逐文件搜索真实凭证片段（app_id 数字值、api_key 值、api_secret 值、私有端点路径），用 grep 确认全部命中位置
替换所有命中为占位符
删除 __pycache__/ 目录
再次 grep 验证零残留
告知用户：「分享副本已就绪，无凭证泄露」

不做的事

不修改原始工作区技能文件（C盘 ~/.workbuddy/skills/ 的版本保留凭证，仅用户本人使用）
只操作分享副本

版本历史

共 21 个版本

v1.0.20 Initial release 当前

2026-05-22 09:55 安全安全
v1.0.19 Initial release

2026-05-22 07:40 安全安全
v1.0.18 Initial release

2026-05-21 15:12 安全安全
v1.0.17 Initial release

2026-05-21 14:00 安全安全
v1.0.16 Initial release

2026-05-21 13:26 安全安全
v1.0.15 多音字标注

2026-05-15 11:42 安全安全
v1.0.14 Initial release

2026-05-14 14:44 安全
v1.0.13 Initial release

2026-05-14 11:53 安全安全
v1.0.12 字幕生成工具

2026-05-14 07:29 安全安全
v1.0.11 V3.4 改动总结：特性说明 SMPTE 自动适配检测到逗号格式 → 自动按 30fps 解析，用户零配置 template_fps 降级为高级手动覆盖（job.yaml 可选字段）验证明细表 step01 输出 SMPTE 解析对照，透明可查智能提示自动适配/一致/手动覆盖三种状态区分明确

2026-05-13 16:59 安全安全
v1.0.10 三种格式对照表 — MM:SS / MM:SS,FF / MM:SS.mmm，一目了然红框警告 — "逗号是帧分隔符，不是小数点"，附带计算示例 00:12,19 = 12.633s 剪映指引 — "在剪映中查看帧号，时间线右上角可切换显示格式" 帧号计算示例 — 30fps 下 00:03,15 = 3.5s、00:06,04 = 6.133s

2026-05-13 15:24 安全安全
v1.0.9 解决数据符号读音问题

2026-05-13 09:07 安全安全
v1.0.8 更新模版推送

2026-05-12 11:19 安全安全
v1.0.7 1更新图标

2026-05-10 00:48 安全安全
v1.0.6 更新图标

2026-05-10 00:40 安全安全
v1.0.5 对话交互流程：自动环境检测 → 提问引擎/音色选择 → 自动生成配置 → 一键执行 → 容错续跑。讯飞超拟人主力 + edge备用。 |

2026-05-10 00:12 安全安全
v1.0.4 视频对齐，字幕语音对齐。

2026-05-08 16:12 安全安全
v1.0.3 变速问题

2026-05-08 14:13 安全安全
v1.0.2 修复丢帧问题

2026-05-08 09:29 安全安全
v1.0.1 Initial release

2026-05-07 20:17 安全安全
v1.0.0 Initial release

2026-05-07 20:11 安全安全

教学视频配音字幕合成

概述