MKT AI Video — MP3からSRT + セグメントを抽出
音声MP3を文字起こしし、ショート動画制作パイプライン全体で使用される2つのファイルを生成します。
<stem>.srt— 標準のSRT字幕（セグメントレベルのタイムスタンプ、キャプションに使用）<stem>_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 は約2倍のコストで顕著に精度向上 |
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>/<stem>.srt<mp3_parent>/<stem>_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>/<stem>.srt" "<output_dir>/<stem>_segments.json"
head -20 "<output_dir>/<stem>.srt"
期待される内容：
- SRTは
1\n00:00:00,000 --> 00:00:0X,XXX\n<テキスト>\n\nで始まる - JSONはオブジェクトの配列で、各オブジェクトは
id、start、end、text、および{word, start, end}のwords配列を持つ
どちらかのファイルが存在しないか空の場合、実行は失敗しています。ステップ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パスは常に引用符で囲んでください。ワークスペースフォルダにはハイフン、日付、スラッシュが含まれることが多く、引用符なしのシェル展開で問題が発生します。
- 重複禁止：このスキルは意図的に独自のスクリプトを提供しません。新しい文字起こしスクリプトを書きそうになった場合は、停止して
heygen-short-video/scripts/transcribe_mp3.pyを使用してください。そのスクリプトに変更が必要な場合は、そこで編集することで全ての利用者が恩恵を受けられます。
引き継ぎ
両方のファイルが保存され、検証されたら、以下を報告します。
SRT: <絶対パス>.srt
Segments: <絶対パス>_segments.json
セグメント数: N
合計時間: X.Xs
その後、ユーザー（または呼び出し元スキル）が次のステップを決定します。通常は plan-short-video-edit による制作計画、または heygen-remotion-short-video-editor による直接消費です。