MKT AI 视频 — 从MP3提取SRT+片段
将配音MP3转录为短视频制作流水线中使用的两个文件：
<主干名>.srt— 标准SRT字幕（片段级时间戳，用于字幕展示）<主干名>_segments.json— 词级时间戳（用于精确音效放置、逐字字幕动画和下游片段分类）
默认情况下，两个文件都写入MP3所在目录。文件名遵循MP3主干名——例如 voiceover.mp3 → voiceover.srt + voiceover_segments.json。
何时使用此技能
- 用户提供MP3配音并要求生成SRT/转录/片段
- 下游技能（
plan-short-video-edit、heygen-remotion-short-video-editor、字幕渲染）需要词级时间戳但尚未生成 - 需要为现有配音重新生成片段（例如重新录制后）
如果两个输出文件已存在且比MP3更新，优先重用它们而不是重新运行Whisper。
输入
| 参数 | 必需 | 默认值 | 说明 |
|---|---|---|---|
mp3_path | 是 | — | MP3文件的绝对路径 |
language | 否 | vi | Whisper语言代码。越南语配音用vi，英语用en |
model | 否 | base | Whisper模型大小：tiny / base / small / medium / large。base适合大多数清晰配音；small在越南语上准确度明显更高，但成本约增加两倍 |
output_dir | 否 | MP3所在父文件夹 | SRT和JSON的输出目录 |
步骤1 — 运行转录脚本
重用heygen-short-video技能中已有的Whisper脚本——它已经实现了完全相同的行为，因此我们不再重复代码：
uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py "<mp3_path>" --language vi --model base
这将生成：
<mp3父目录>/<主干名>.srt<mp3父目录>/<主干名>_segments.json
要将输出写入其他位置，追加--output-dir <路径>。
示例 — 对于 workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3：
uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py \
"workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3" \
--language vi --model base
输出：
workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.srtworkspace/content/2026-04-09/video-short/learn-claude-code/voiceover_segments.json
步骤2 — 检查输出
脚本运行完毕后，确认两个文件都存在且内容非空：
ls -lh "<output_dir>/<主干名>.srt" "<output_dir>/<主干名>_segments.json"
head -20 "<output_dir>/<主干名>.srt"
预期：
- SRT以
1\n00:00:00,000 --> 00:00:0X,XXX\n<文本>\n\n开头 - JSON是一个对象数组，每个对象包含
id、start、end、text以及一个words数组（元素为{word, start, end}）
如果任一文件缺失或为空，说明运行失败——重新阅读步骤1的stderr并将错误展示给用户，而不是静默继续。
输出格式参考
voiceover.srt
1
00:00:00,000 --> 00:00:05,139
Đây là tài liệu học Claude Code tốt nhất mình từng thấy…
2
00:00:05,139 --> 00:00:07,299
Nếu bạn mới bắt đầu tìm hiểu Claude Code,
voiceover_segments.json
[
{
"id": 0,
"start": 0.0,
"end": 5.14,
"text": "Đây là tài liệu học Claude Code tốt nhất…",
"words": [
{ "word": "Đây", "start": 0.0, "end": 0.34 },
{ "word": "là", "start": 0.94, "end": 1.12 }
]
}
]
词级时间戳正是让这个JSON有价值的原因——下游技能利用它们进行逐字字幕动画、按词音效提示和精确片段边界检测。在后处理时不要丢弃 words 数组。
步骤3 — 基于脚本的文本校正（当脚本可用时必需）
Whisper经常错误识别混合了英语技术术语的越南语（例如 "Claude Code" → "Clocot"，"MCP Servers" → "MCP Service"，"prompt" → "PromGtt"）。始终在原始脚本可用时（在视频流水线中几乎总是可用）执行此校正。校正SRT/JSON的文本，同时保留所有时间戳：
- 读取生成的SRT和JSON（保持每个
start/end不变）。 - 将每个SRT条目按位置与原始脚本的对应片段对齐。
- 将该片段的脚本文本替换Whisper文本。
- 在
voiceover_segments.json的片段级text字段中镜像相同的校正。词级条目可以保留Whisper生成的内容，除非有可靠的词对齐——保留words[].word不变是可以的，因为下游技能主要使用词的时间信息，而不是词字符串本身。 - 将两个文件写回原位。
原因：SRT文本用于渲染的字幕。错误的文本 = 错误的字幕。Whisper的时间戳是可靠的，但文本不可靠。
仅在用户明确未提供脚本时跳过此步骤。在完整的视频流水线（mkt-full-ai-video）中，脚本始终可用——因此始终执行此校正。
提示与陷阱
- 模型选择：
base能处理大多数清晰的配音。对于嘈杂录音或重口音，升级到small或medium。超出small后成本迅速增加，对于短视频内容来说很少物有所值。 - 语言：对于越南语，始终显式传递
--language vi。自动检测有时会在短视频片段上回退到其他语言。 - 重复运行：对于相同的模型+音频，Whisper是确定性的，因此只有更改模型或修复音频时重复运行才有意义。不要期望相同模型大小下通过重复运行得到更好结果。
- 路径引用：始终用引号括住MP3路径——工作区文件夹通常包含连字符、日期和斜杠，会破坏未引用的shell扩展。
- 不重复：此技能故意不自带脚本。如果发现自己准备编写新的转录脚本，请停下来——使用
heygen-short-video/scripts/transcribe_mp3.py。如果该脚本需要更改，请在那里编辑，以便所有使用者受益。
交接
两个文件保存并验证后，报告：
SRT: <绝对路径>.srt
Segments: <绝对路径>_segments.json
片段数量: N
总时长: X.Xs
然后让用户（或调用技能）决定下一步——通常是 plan-short-video-edit 用于制作规划，或由 heygen-remotion-short-video-editor 直接消费。