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

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

🔔 首次加载指引

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

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

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

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

🆕 V3.7 新功能：空白行→保留原音 / 逐短句字幕 / 视频加速 / 字幕编辑器自动编号+间隔级联
🔧 V3.7.3 修复：edge-tts "念网址"异常 / 断句标记改为反引号 / 主动重做字幕支持

📂 技能文件

<本技能目录>/
├── 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 自行执行，无需用户干预：

1. 复制程序：在用户项目目录下创建 _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

1. 运行环境检测：

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

读 env.json，按情况处理：

阶段 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  → 3段填充 + 7段冻结扩展
✅ 05_merge  → 10段声画合成完成
✅ 06_finalize → 字幕注入完成

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

阶段 6：容错处理

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

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

1. 执行 resume：

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

主动重做字幕（非错误，用户要求）

用户可能要求对已经生成过的视频重新合成字幕（如切换硬烧录、改字幕样式、修正错字）。此时无需重跑 TTS/切分等耗时步骤，只需重跑最后一步：

python _scripts/pipeline.py --job job.yaml --resume-from 06_finalize

工作原理：自动找到最新任务目录，保留 01-05 步全部产物，仅删除并重建 06_final/。

用户可能说的触发语（AI 听到后直接执行，无需追问）：

• "重新合成字幕" / "重新生成字幕"
• "给视频重新加字幕" / "重做字幕"
• "之前视频的字幕看不到，重弄一下"
• "换个字幕样式" / "字幕改成硬编码"
• "只重新跑最后一步" / "只重新生成字幕文件"

📋 配置清单（AI 记住）

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

🎤 音色速查（供 AI 参考）

讯飞 spark

edge-tts

⚠️ 环境缺失处理指南

> 重要：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.7

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

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

工作流

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

核心机制

• F 键 = 拍板标记：每次按下，标记当前字幕段结束时间（连续模式：下段起点 = 当前结束点）
• G 键 = 间隙标记（V3.7.2）：仅标记当前段结束，不设下段起点（制造时间间隙，间隙视频将被丢弃）
• 自动衔接：上一段结束时间 = 下一段开始时间（F 键模式）
• 精确逐帧：单击 ← → 精确走 1 帧；长按 → 8x 高速播放（playbackRate，丝滑不卡）
• Ctrl+Z 撤销：按错了随时撤销上一个标记
• 自动缓存：所有标记 + 工作目录自动保存到 localStorage，关闭浏览器也不丢
• 一键生成提示词：⚡ 自动下载 .md + 复制简洁提示词（仅视频路径 + 模板路径），弹窗提醒移动文件
• 路径校验：工作目录 3 层校验（无效字符/非绝对路径/像文件名），防止误存
• 粘贴追加模式（V3.7.2）：首次粘贴后如已标记时间，再次粘贴可选「追加到末尾」保留已有标记，新字幕追加到末尾
• G 键间隙标记（V3.7.2）：独立 G 键按钮替代不稳定组合键，一键标记间隙
• 粘贴智能识别（V3.7.2）：
• 空白行 → filler 段（连续空行自动合并）
• 纯编号行（如 005 无文案）→ filler 段（每条独立，不合并）
• (静音) / [静音] / （静音） → filler_silent 段
• F 键首段保护（V3.7.2）：首段标记时检测视频是否已播放，未播放则提示；通用结束时间>开始时间校验，防止 0→0 误标记
• startTime 编辑（V3.7.2）：编辑模态框支持手动修改开始时间，制造视频间隙（间隙部分自动丢弃）
• 间隙可视化（V3.7.2）：字幕列表中检测到时间间隙时，显示黄色 ⏭ 跳过指示器

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 均支持

🏷️ V3.7 特殊段标记

视频中有些段落不需要 AI 配音，比如操作演示、过渡画面。用以下方式标记：

1. Filler 段（保留原音） — 空白行

> 标记方式：文案内容留空（什么都不写）

> 效果：跳过 TTS 配音，保留视频原始音频。适用于操作演示、原声讲解等不需要 AI 配音的段落。

| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:05 | 大家好，今天来学习笔筒制作。 |
| 00:05 | 00:12 |                            |  ← 空白=保留原音，这里保留视频自带的操作演示声音
| 00:12 | 00:18 | 接下去我们调整笔筒的高度。  |

> 表格中空白行（| 00:05 | 00:12 | |）会被自动识别为 filler 段。

2. 静音段（需要时使用）

> 标记方式：文案内容写 (静音) / [静音] / （静音）（三种括号均可）

> 效果：跳过 TTS，生成静音音频。适用于纯画面展示、不需要任何声音的段落。

| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:05 | 大家好，今天来学习笔筒制作。 |
| 00:05 | 00:12 | [静音]                     |  ← 纯画面展示，无声（也可写 (静音) 或 （静音））
| 00:12 | 00:18 | 接下去我们调整笔筒的高度。  |

> 括号说明：英文半角 (静音)、英文方括号 [静音]、中文全角 （静音） 均被识别。模板解析时全角括号会被自动归一化，粘贴字幕时正则同时匹配三种写法。

三种段类型速查

3. 字幕编辑器中的 filler

用 subtitle-editor.html 粘贴文案时：

001 大家好，今天来学习笔筒制作。
                         ← 空白行 = filler 段
003 接下去我们调整笔筒的高度。

• 粘贴时：识别空白行 → 自动创建 filler 段，列表显示 [保留原音]
• 编辑时：清空文案 → 自动转为 filler；重新填入文案 → 恢复为普通段
• F 键标记：filler 段同样需要按 F 键标记结束时间（和普通段操作一致）
• 导出模板：filler 段导出的文案为空（| 00:05 | 00:12 | |）

!ScreenShot_2026-05-14_114914_820.png

4. TTS 朗读断句（` `` 手动分词）

> 问题：TTS 引擎偶尔会把相邻的词连读，或在不该停顿的地方一口气读完（如"第三步设置前凸"→ 读成"第三步设置前凸"不换气）。

> 解决：在文案中插入 ` `（反引号）标记，程序自动替换为中文逗号 ，`（仅发送给 TTS，最终字幕中不出现）。

示例：

| 开始时间 | 结束时间 | 文案内容 |
|----------|----------|----------|
| 00:00 | 00:03 | 第三步`设置前凸         |  ← TTS 朗读"第三步，设置前凸"，字幕显示"第三步设置前凸"
| 00:03 | 00:06 | 内凹`通过拖拽面来实现 |  ← TTS 朗读"内凹，通过拖拽面来实现"

规则：

• ` ` → TTS 朗读时自动替换为 ，`（逗号停顿），字幕中不显示
• 放在需要换气/停顿的位置，如"操作步骤` `具体动作"、"概念名称 ``解释说明"
• 多个 ` ` 可以在一行中多次使用（如 "选中拖拽设置高度" → "选中，拖拽，设置高度"`）
• 连续逗号会自动合并，不会出现 ，， 的情况

额外自动优化：即使不用 ` `，程序也会自动检测 第X步 并在其后加逗号换气。含数字的括号（如（3.5，5）`）会自动剥离为逗号分隔，防止 edge-tts 误读为数学区间。

5. TTS 手动覆盖（{tts:...} 整段替换）

> 问题：有些读音错误自动修复搞不定（如数字括号被持续误读为"开区间"）。

> 解决：在文案末尾加 {tts:替代全文}，整段 TTS 朗读文本完全替换，字幕保持原文。

示例：

| 00:00 | 00:05 | 宽度（3.5）毫米{tts:宽度为三点五毫米} |
  → 字幕显示: 宽度（3.5）毫米
  → TTS 朗读: 宽度为三点五毫米

规则：

• {tts:...} 必须写在整段文案末尾，替代全文（不存在"只替换前半句"的歧义）
• 替代文本仍会经过韵律优化（反引号断句、第X步换气），无需在替代文本中重复标注
• {tts:...} 不会出现在字幕中
• 此标注是手动兜底——95% 的情况自动修复已够用，只有边缘情况才需要用到

🎯 V3.7 核心技术升级

📐 逐短句 SRT 字幕（V3.7）

> 问题：以前一段配音对应一条 SRT 字幕，5 秒画面一口气显示 40 个字 —— 超出画面、观众跟不上。

> 解决：程序自动按中文标点（。，！？；：、）把文案拆成短句，配合词级时间戳按字数比例分配起止时间，实现「读一句显示一句」。

以前（整段一字幕）：
  00:00:00.000 → 00:00:05.000
  字幕: "本视频将讲解如何制作进阶笔筒首先制作底座选取圆柱体"
  ❌ 画面挤爆

现在（逐短句拆分）：
  00:00:00.000 → 00:00:02.150  字幕: "本视频将讲解如何制作进阶笔筒。"
  00:00:02.150 → 00:00:03.800  字幕: "首先制作底座，"
  00:00:03.800 → 00:00:05.000  字幕: "选取圆柱体。"
  ✅ 每次只显示一句，跟着语音节奏走

• 无需手动标记：程序自动拆分，用户照常写文案即可
• 跳过 filler 段：保留原音的段落不生成 SRT 字幕
• 正常工作前提：需要词级时间戳（讯飞 spark 引擎返回），edge-tts 默认回退到整段字幕

⏩ 视频加速（V3.7）

> 场景：AI 配音比原视频短，比如原视频有 8 秒操作画面但配音只需 5 秒。

• 自动检测：step04_align.py 比较音视频时长，当音频 < 视频时自动判断是否需要加速
• 触发阈值：raw_factor > 1.02（配音比视频短 2% 以上）
• 加速上限：默认 1.5x，可在 job.yaml 中配置 speedup 字段（如 speedup: 2）
• 算法：ffmpeg setpts=PTS/{factor} 视频滤镜 + atempo 音频滤镜，保持音画同步

# job.yaml 中可选配置（不写则默认禁用）
speedup: "1.5"

📋 变更日志

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

🔒 分享前检查清单

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

必须清除的敏感信息

执行步骤

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

不做的事

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

3.0	2026-05-09	固定程序模式。完整的 AI 对话交互流程。讯飞超拟人主力 + edge备用。