YouTube Bilingual Hardburn
外国語の動画を中国語-英語のハードサブ動画に変換します。決定的なステップはスクリプトで行われ、翻訳ステップはエージェント(LLM)が担当し、ここにすべてのリスクが存在します。
鉄則: 英語の1行につき中国語は1行。絶対に英語の1行を中国語の2行に分割したり(または2行を1行に結合したり)しないでください。翻訳バッチごとに verify_align.py を実行してください。1行ずれるだけで後続のすべての字幕が同期しなくなり、バーンが完了するまで気づきません。
ソースに句読点がある場合とない場合
- YouTubeの自動キャプション(およびほとんどのASR)にはほぼ句読点がありません → 「
.!?で分割する」アプローチは失敗します(すべてが1つのキューにまとまります)。このスキルでは、文字数制限までフレーズを結合することでこの問題を解決します。これがデフォルトのパスです。 - ソースにすでにきれいな句読点付きの字幕がある場合でも、同じパイプラインが機能します。
前提条件
yt-dlp(ダウンロード)、ffmpeg(ハードバーン)、python3(スクリプト)。Pythonパッケージは不要です。- CJK対応フォントがインストールされていること。macOS:
PingFang SC(デフォルト)。Linux:--font "Noto Sans CJK SC"を指定。Windows:--font "Microsoft YaHei"を指定。 SCRIPTS=このスキルのscripts/ディレクトリへの絶対パス。一度設定して再利用します。
ワークフロー
バイリンガルハードバーンの進行状況:
- [ ] ステップ1: 動画とキャプションを取得 ⚠️ 必須
- [ ] ステップ2: キャプションを抽出し、読みやすい行に再セグメント化
- [ ] ステップ3: 各行を翻訳(1:1) — 注意が必要な部分 ⚠️ 必須
- [ ] ステップ4: verify_align.py == OK ⛔ ブロッキング(合格するまで次に進めません)
- [ ] ステップ5: バイリンガル .ass をビルドし、1つのテストフレームでスタイルを確認 ⚠️ 必須
- [ ] ステップ6: フル動画をハードバーン(長時間エンコード)+ スポットチェック
ステップ1: 動画 + キャプションを取得 ⚠️ 必須
yt-dlp -o "%(upload_date)s_%(title)s.%(ext)s" \
-f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/best[height<=1080]/best" \
--merge-output-format mp4 --write-subs --write-auto-subs --sub-langs "en" \
--no-mtime "<URL>"
--write-auto-subsでキャプションファイルが生成されない場合(キャプションがない動画もあります)、まず音声を文字起こし(例: whisper)して.vtt/.srtを作成し、その後続行します。- 2つの出力ファイルに注意:
VIDEO.mp4とVIDEO.en.vtt。
ステップ2: 抽出 + 再セグメント化 ⚠️
python3 "$SCRIPTS/extract_phrases.py" "VIDEO.en.vtt" > phrases.json
python3 "$SCRIPTS/merge_lines.py" phrases.json lines.json # --max-chars 95 --gap 12
これにより lines.json([{start,end,en}])と lines_en.txt(番号付き idx<TAB>English ファイル)が生成されます。lines_en.txt を翻訳します。 必要に応じて後で調整:
- 字幕が画面に長く表示されすぎる場合 →
--max-charsを下げる(例: 70) - 自然なポーズで区切りたい場合 →
--gapを下げる(例: 2.5) — より多くの短い行が生成されます
ステップ3: 各行を翻訳(1:1) ⚠️ 必須 — 注意が必要な部分
lines_en.txt(0..N-1 の番号付き)を読みます。プレーンテキストの中国語ファイルを生成します: 英語の各行に対して中国語の行を1行だけ、同じ順序で。 改行区切りのテキスト(JSON ではない — 中国語の引用符は JSON のエスケープを壊します)を書き込みます。
鉄則違反を防ぐルール:
- 1行入力 → 1行出力。 英語の行を独立した単位として翻訳します。行が文の途中で切れていても(ASRではよくあることです)、中国語も同じ場所で切ります。行をまたいで「修正」しようとしないでください。
- 約120〜150行のバッチで作業します。各バッチの後にファイルを書き込み、すぐに累積結果に対して
verify_align.pyを実行します。 - 固有名詞は正しい形式(ChatGPT、OpenAI、Claude、Gemini、Grok、DeepSeek…)を維持します。ASRはそれらを歪めます(「chpd」→ChatGPT、「grock」→Grok、「ha cou」→haiku) — 実際の名前に修正します。
- 堅苦しい翻訳ではなく、自然な話し言葉の中国語。話者の語調に合わせます。
すべてのバッチファイルを連結して1つの zh.txt にします(EN行ごとに1つのZH行、順番通り)。
ステップ4: verify_align.py ⛔ ブロッキング
python3 "$SCRIPTS/verify_align.py" lines.json zh.txt
OKと表示されたら → 次に進みます。MISMATCH+ サイドバイサイドの表が表示されたら → ENとZHの意味が一致しなくなった行を見つけます。その行が分割(1つのEN行が2つのZH行になった)または結合です。修正し(2つのZH行を1つに戻す、または1つを2つに分割)、再実行します。OKになるまで次に進まないでください。
ステップ5: .ass をビルド + 1つのテストフレームで確認 ⚠️ 必須
python3 "$SCRIPTS/build_bilingual_ass.py" lines.json zh.txt styled.ass
# 中国語が上(白44px)+ 英語が下(灰色30px)、下部中央。
# Linux/Windows: --font "Noto Sans CJK SC" / --font "Microsoft YaHei" を追加
字幕がある既知のタイムスタンプで1つのフレームをレンダリングし、長時間エンコードの前に確認します:
ffmpeg -ss 60 -i "VIDEO.mp4" -copyts -vf "ass=styled.ass" -frames:v 1 -y test_frame.png
ユーザーと確認: 中国語がレンダリングされているか(豆腐ボックス □□□ がない)、2段レイアウトが適切か、サイズ/位置が許容範囲か。必要に応じて --zh-size/--en-size/--margin/--font を調整し再ビルドします。テストフレームが正しく見えるまでフルエンコードを開始しないでください。
ステップ6: フル動画をハードバーン + スポットチェック
ffmpeg -y -i "VIDEO.mp4" -vf "ass=styled.ass" \
-c:v libx264 -preset fast -crf 22 -c:a copy -sn "VIDEO_中英双语.mp4"
2時間の1080p動画は約15〜40分かかります — バックグラウンドで実行します。完了したら、開始、中間、終盤のフレームを取得して、字幕が全体を通して同期していることを確認します:
for t in 600 3900 7200; do ffmpeg -ss $t -i "VIDEO_中英双语.mp4" -frames:v 1 -y "chk_$t.png"; done
フレームがずれているように見える場合は、バグを疑う前に、同じタイムスタンプのキューが lines.json+zh.txt で同じソース行であることを再確認します(低解像度フレームは誤読しやすいです)。
アンチパターン
- 翻訳中に行を分割/結合すること — 全動画の同期ずれの最大の原因。常に1つのEN行 = 1つのZH行。
- 翻訳をJSONとして書き込むこと — 中国語の引用符「 ” 」や「 」はJSONの解析を静かに破壊します。改行区切りのプレーンテキストを使用してください。
- 字幕の終了時間で順序付けを信頼すること — ローリングキャプションの終了時間は重なります。
merge_lines.pyは開始時間のみで順序付けします。終了時間で並べ替えないでください。 - テストフレームをスキップすること — 2時間かけてバーンした後に豆腐ボックスや間違ったフォントを発見すると、エンコード全体が無駄になります。
- オーディオを再エンコードすること —
-c:a copyを使用してください。ビデオトラックのみが変更されます。 - 動画ダウンロードスキルの古い
build_bilingual.pyを自動キャプションに使用すること — 句読点で分割し、トランスクリプト全体を1つのキューにまとめます。このスキルはそれを置き換えます。
納品前チェックリスト
-
verify_align.pyがOKを表示した(EN数 == ZH数) .ass ビルド前 - テストフレームを確認: 中国語がレンダリングされている、□ボックスなし、レイアウト/サイズが正しい
- 最終mp4の開始/中間/終了フレームをスポットチェック — 字幕が同期している
- 出力ファイル名が明確(例:
<タイトル>_中英双语.mp4); 元の動画はそのまま - 固有名詞が修正されている(中国語に「chpd」/「grock」/「ha cou」が残っていない)
クロスプラットフォーム(OpenAI Codexなど)
すべてのスクリプトは純粋な python3 + ffmpeg/yt-dlp — Claude固有の依存関係はありません。このワークフローをCodex(またはシェル対応エージェント)で実行するには、references/codex-usage.md を読み込んでください。