MKT AI 影片 — 從 MP3 提取 SRT 與時間軸分段
將一段旁白 MP3 轉錄為短影片生產流程中使用的兩個檔案：
<主檔名>.srt— 標準 SRT 字幕（片段級時間戳記，用於標題/CC）<主檔名>_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_parent>/<主檔名>.srt<mp3_parent>/<主檔名>_segments.json
若要將輸出寫到其他位置，請加上 --output-dir <path>。
範例 — 針對 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欄位套用相同的校正。逐字條目可保留原樣，除非你有可靠的逐字對齊方式——讓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
Segments 數量: N
總時長: X.Xs
然後讓使用者（或呼叫端技能）決定下一步——通常是用 plan-short-video-edit 進行生產規劃，或直接由 heygen-remotion-short-video-editor 使用。