YouTube 字幕翻訳ツール
YouTube動画をダウンロードし、字幕を抽出・処理(校正+句読点付与+翻訳)した後、動画に焼き付けます。自動生成キャプションと手動アップロードの両方を処理し、字幕がない場合はASRにフォールバックします。
厳格なルール
- 字幕チャンク処理には最大3つの同時サブエージェントを使用します。チャンクが3つを超える場合は、波状に実行し、1つのサブエージェントが完了した後に次のチャンクを起動します。
- チャンク数は同時実行数ではありません。10チャンクに分割しても、10個のCodexプロセス/サブエージェントを一度に起動してはいけません。常に最大3つのアクティブワーカーのみを実行します。
- 常にソース字幕トラックのみをダウンロードします。利用可能な場合は英語、そうでなければ動画の元の言語です。YouTubeの自動翻訳されたターゲット言語のキャプションはダウンロードせず、ソース字幕から翻訳します。
- 長い動画の場合でも、また
automatic_captionsにzh-Hansや他のターゲット言語がリストされている場合でも、YouTubeが提供するターゲット言語のキャプショントラックをショートカットとして決して使用しないでください。 - 動画のデフォルト解像度は1080pです。1080pが利用できない場合は、1080p未満で利用可能な最良のバージョンをダウンロードします。
- 翻訳は、チャンクファイルに対してサブエージェントによって実行される必要があります。翻訳にローカルモデルヘルパーを使用しないでください。
- SRT/ASSを書き込む前に、テキストから不正な字幕文字、特に動画内で目に見えて表示される不正なバックスラッシュ(
\)を取り除きます。
ワークフロー概要
フェーズ1: ダウンロード → 動画情報を取得、動画をダウンロード、字幕を抽出
フェーズ2: 準備 → 字幕がない場合: 音声を抽出 → ASRを実行
フェーズ3: 処理 → チャンクに分割 → 並列エージェントによる校正 + 翻訳
フェーズ4: マージ → チャンクを結合 → SRT/ASSファイルを生成
フェーズ5: レンダリング → ffmpegを使用して字幕を動画に焼き付け
フェーズ1: ダウンロード
1.1 動画情報を取得
YouTube MCPツールを使用してメタデータを取得します。
youtube_get_video_info(videoId="...", detail="standard")
記録する項目: タイトル、再生時間、チャンネル、字幕の有無。
1.2 出力ディレクトリを作成
ディレクトリ名は動画タイトルに基づきます。ファイルシステム用にサニタイズします。
mkdir -p "/output/path/<動画のタイトル>"
1.3 動画をダウンロード
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
yt-dlp を使用する場合は、1080pを優先し、1080p未満の最良のフォーマットにフォールバックします。
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 ソース字幕のみを抽出
youtube_get_transcript(videoId="...", language="<ソース言語>")
結果がトークン制限を超える場合は、ツール結果ファイルに保存されるため、チャンク単位で読み取ります。
これは譲歩できないソース字幕ポリシーです。
- 可能な限り英語字幕/キャプションを優先します。
- 英語が利用できない場合は、動画の元の音声言語を使用します。
- YouTubeが表示する
zh-Hans、zh-Hant、およびその他すべてのターゲット言語トラック(自動翻訳トラックを含む)は無視します。 - YouTubeが提供するターゲット言語キャプショントラックを要求、再試行、マージ、またはレンダリングしないでください。
- ターゲット言語の字幕は、ソース字幕からのサブエージェント翻訳によってのみ生成される必要があります。
ツールが en-orig, zh-Hans などのリストを返す場合は、en-orig のみを選択します。ダウンロードコマンドに zh-Hans を含めないでください。
yt-dlp を使用する場合は、ソース字幕のみを書き込みます。
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
間違い(実行しないこと):
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
英語/元の字幕のダウンロードは成功したが、ターゲット言語のリクエストがHTTP 429で失敗した場合、ターゲット言語のリクエストを再試行しないでください。そのリクエストは本来行われるべきではなかったものです。ソース字幕から続行し、フェーズ3で翻訳します。
字幕が存在する場合: 生のセグメントをJSONとして保存し、フェーズ3に進みます。 字幕がない場合 (404/エラー): フェーズ2 (ASRフォールバック) に進みます。
生データを保存:
raw_segments.json— すべてのセグメント(テキスト/オフセット/再生時間を含む)raw_subtitles.srt— 初期SRT変換
フェーズ2: ASRフォールバック(字幕がない場合)
動画にキャプション/トランスクリプトがない場合:
-
ffmpegを使用して動画から音声を抽出:
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
ASRを実行 — ユーザー指定の qwen3-asr ですが、whisper互換モデルであればどれでも動作します:
qwen3-asr audio.wav --output-format srt > raw_subtitles.srtまたは、hyperframes-media スキルの transcribe コマンドを介した組み込みアプローチを使用します。
-
SRT出力を解析して、フェーズ3で期待されるセグメントJSON形式に戻します。
フェーズ3: 並列校正と翻訳
これは長い動画の場合に最も時間のかかるステップです。戦略: チャンクに分割し、サブエージェントで処理します。ただし、同時サブエージェントは最大3つまでという厳格な制限があります。
非常に長い動画でもこのフェーズを実行します。長さは、YouTubeのターゲット言語自動キャプションをダウンロードまたは使用する理由にはなりません。長い動画に対する正しいショートカットは、チャンク分割と3方向サブエージェントの同時実行であり、ターゲットキャプションの再利用ではありません。
3.1 セグメントをチャンクに分割
scripts/merge-chunks.py の逆ロジックを使用して、raw_segments.json をN個のチャンクファイルに分割します。
# レビュー/翻訳に適したサイズに分割。
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
chunk_00.json、chunk_01.json などとして保存します。各ファイルには {"chunk_id", "start_idx", "end_idx", "segments": [...]} が含まれます。
3.2 並列エージェントを起動
各チャンクに対して、バックグラウンドサブエージェントを起動します。最大3つのサブエージェントを同時に起動します。チャンクが10個ある場合は、最初にチャンク 00、01、02 を開始し、1つが完了したら次の保留中のチャンクを開始します。一度に10個すべてのチャンクを開始しないでください。各エージェントに以下を提供します。
chunk_XX.jsonへのパス- 完全な仕様については references/subtitle-proofreading.md を読むように指示
- 出力パス: 同じディレクトリ内の
result_XX.json
エージェントは以下を実行する必要があります。
- チャンク内のすべてのセグメントを読む
- 英語を校正する(ASRエラーを修正、句読点を追加)
- 自然な簡体字中国語に翻訳する(技術用語は英語のままにする)
- セグメントごとに
{index, start, end, en, zh}を含むJSON配列として保存する enおよびzhから不正な字幕文字、特に不正なバックスラッシュ (\)、制御文字、生のASSオーバーライドブレースを取り除く
重要: 最大同時実行数は3サブエージェント/プロセスです。チャンクが3つを超える場合は、波状に実行します。10チャンクに対して10個のCodex子プロセスを起動しないでください。
3.3 完了を待機
どの result_XX.json ファイルが出現するかを監視します。すべてのチャンクが完了するまで先に進みません。
フェーズ4: マージと出力ファイルの生成
マージスクリプトを実行します。
python3 scripts/merge-chunks.py <output_dir>
これにより、すべての result_*.json ファイルが自動検出され、以下のファイルが生成されます。
| ファイル | 内容 |
|---|---|
final_subtitles.json | マージされたJSON、タイムスタンプでソート |
subtitles_bilingual.srt | 英語 + 中国語の行 |
subtitles_zh.srt | 中国語のみ |
subtitles_en.srt | 英語のみ |
4.2 データ品質の検証
レンダリング前に、常にマージされたデータを検証します。 並列エージェント処理により、タイムスタンプが破損する可能性があります。
# 異常な再生時間(>120秒 = ほぼ確実に破損)をチェック
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
print(f'Abnormal durations: {len(bad)} / {len(segs)}')
for s in bad: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}s)')
"
見つかった場合は修正し(end を start + 6 に制限)、SRT/ASSを再生成します。merge-chunks.py と srt-to-ass.py はどちらも、この問題の自動検出と自動修正を含んでいます。
出力を確認します。最初と最後のいくつかのエントリに正しいタイムスタンプと読み取り可能なテキストがあることを確認します。
また、テキストのサニタイズを確認します。
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'Backslash artifacts: {len(bad)}')
for s in bad[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
フェーズ5: 動画に字幕をレンダリング
ここからが難しいところです。システムのffmpegを直接使用しないでください — 以下の落とし穴を参照してください。
5.1 レンダリングスクリプトを実行
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
スクリプトはすべてを処理します。
- libassサポート付きのARM64ネイティブffmpegを検出/ビルド
- 適切なCJKフォント設定でSRT → ASSに変換
- 特殊文字パスの問題を避けるためにファイルを/tmpにコピー
- ffmpegのassフィルタでレンダリング
- 出力を検証
5.2 出力を確認
以下を確認します。
- 出力ファイルが存在し、10MB以上ある(音声のみではない)
- 再生時間が元の動画と一致する(ffprobeを使用)
- 最初と最後の1分間を再生し、字幕が表示されることを確認する
落とし穴と学んだ教訓
これらは実際の使用から得られた貴重な教訓です。これらに従って、何時間もの無駄を避けてください。
ffmpeg アーキテクチャの不一致 (重要)
問題: macOS Homebrew の ffmpeg は libass、libfreetype、fontconfig なしでコンパイルされています。ass、subtitles、drawtext フィルタは単に存在しません。
さらに悪いことに: evermeet.cx の静的ffmpegビルドは x86_64 (Intel) バイナリです。Apple Silicon Macでは、Rosetta 2エミュレーションを介して約8〜10倍遅く実行されます。1.5時間の動画には2時間以上かかりました。
解決策: scripts/ensure-ffmpeg.sh を使用します。これはこれらの問題を検出し、必要なすべてのライブラリを使用してARM64ネイティブffmpegをソースからコンパイルします。初回ビルドは約5分かかります。その後のリビルドは瞬時に行われます(オブジェクトファイルがキャッシュされます)。
字幕サポートを完全にするための必要な設定フラグ:
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
AV1 デコードがない
問題: 最近の多くのYouTube動画はAV1(codec_name: av1)でエンコードされています。--enable-libdav1d なしでビルドされたffmpegは、デコード中に「Function not implemented」エラーで失敗し、68MBの音声のみのファイルを生成します。
解決策: ffmpegをビルドするときに常に --enable-libdav1d を含めます。
パスの特殊文字がffmpegフィルタを壊す
問題: 動画または字幕のパスにemダッシュ (—)、スマート引用符、または非ASCII文字が含まれている場合、ffmpegのフィルタパーサーが「No option name near...」エラーで停止します。これは適切なシェル引用符を使用しても発生します。
解決策: ffmpegに渡す前に、字幕ファイルを /tmp/subs_<pid>.ass にコピーします。レンダリングスクリプトはこれを自動的に行います。
moviepy TextClip API の競合 (避けること)
問題: moviepy 2.x の TextClip は、位置引数とキーワード引数の間にパラメータの競合があります(font が内部的に2回出現します)。複数のエラーバリエーションがあり、エラーメッセージからは明確ではありません。
推奨: 本番の字幕レンダリングにmoviepyを使用しないでください。代わりにffmpegのassフィルタを使用してください。より高速で信頼性が高く、libass/fontconfigを介してCJKフォントを適切に処理します。
ffmpeg における SRT と ASS
問題: SRTを直接読み取るffmpegの subtitles フィルタも、一部のビルドでパス解析の問題が発生します。ass フィルタの方が信頼性が高くなります。
解決策: 最初に scripts/srt-to-ass.py を使用してSRTをASSに変換し、次に ass フィルタを使用します。ASS形式は、フォント、サイズ、配置、スタイルを細かく制御することもできます。
不正な字幕文字
問題: 未加工または翻訳された字幕テキストに、不正なバックスラッシュ (\) やASSオーバーライド文字が含まれる可能性があります。ASSレンダリングでは、リテラルのバックスラッシュが画面に表示されたり、誤ってASSエスケープ構文と相互作用したりする可能性があります。
解決策: SRT/ASSを書き込む前に字幕テキストをサニタイズします。
- ユーザーから見える字幕テキストからバックスラッシュを削除する
- 通常の空白以外の制御文字を削除する
- 字幕テキストから生の
{および}ブレースを取り除く srt-to-ass.pyに、バイリンガル行間の\Nなど、所有するASS制御シーケンスのみを追加させる
並列エージェント処理による異常な字幕再生時間
問題: 字幕を並列チャンク(フェーズ3)で処理する場合、個々のエージェントが破損したタイムスタンプを持つエントリを生成する可能性があります。具体的には、start よりもはるかに大きい end 値(例: 再生時間が約6秒ではなく2600秒または4800秒)です。これにより、これらの字幕行が動画の大部分の間画面に表示され続け、他のすべてのコンテンツと重なります。
根本原因: エージェントがチャンク境界を越えて断片化されたASRセグメントを統合するときに、終了時刻を誤って割り当てることがあります。これはデータレベルの問題であり、レンダリングの問題ではないため、ffmpegエラーでは検出されません。
解決策: 3層の防御:
scripts/srt-to-ass.pyは、再生時間が120秒を超えるエントリを自動検出し、警告付きで6秒に制限します- フェーズ4の検証: チャンクをマージした後、
(end - start) > 120秒のエントリを常にスキャンします - レンダリング前チェック: ffmpegを実行する前に、ASSファイル内の不審な長いDialogue行をgrepで検索します
# クイックレンダリング前チェック: 2分以上続く字幕を検索
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
if bad: print(f'WARNING: {len(bad)} abnormal durations found!'); sys.exit(1)
else: print('Duration check passed')
"
フォントサイズの調整
問題: デフォルトのフォントサイズ(16-20px)は、特に小さな画面や離れて見る場合、高解像度1080p以上の動画では小さすぎる可能性があります。
解決策: --font-size フラグを使用して調整します。推奨ベースラインサイズ:
- 1080p動画:
--font-size 24(バイリンガル)または--font-size 28(単一言語) - 4K動画:
--font-size 36以上 render-subtitles.shスクリプトはこれをsrt-to-ass.pyに渡します
依存関係
- YouTube MCPツール:
mcp__plugin_youtube_youtube__*(動画ダウンロード、トランスクリプト、情報) - ffmpeg:
scripts/ensure-ffmpeg.shによって自動ビルドされます