Video to Chinese Dub（動画の中国語吹き替え）

同梱のPythonパイプラインを使用して、完全な中国語吹き替え動画を生成します。ユーザーがURLを指定し、完成品の成果物を要求した場合に、単にワークフローを提案するだけではなく、ターミナル実行が可能でユーザーが必要なネットワーク/ダウンロード操作を許可している場合は、パイプラインを実行してください。

必要なもの: Python 3.10以上、FFmpeg/ffprobe、URLダウンロードのためのネットワークアクセス、およびローカルのfaster-whisperモデル。オンライン翻訳と音声合成はオプションです。有料の音声APIを使わずに自然な中国語が必要な場合は、ローカルのCosyVoiceバックエンドを使用してください。

<skill-root> は、この SKILL.md を含むディレクトリとして解決してください。呼び出し元のカレントワーキングディレクトリをスキルディレクトリと見なさないでください。仮想環境が存在する場合は、macOS/Linuxでは <skill-root>/.venv/bin/python、Windowsでは <skill-root>/.venv\Scripts\python.exe を優先的に使用し、それ以外の場合はアクティブなPythonインタプリタを使用してください。以下のコマンドは、カレントディレクトリが <skill-root> に変更されていることを前提としています。

クイックスタート

前提条件を確認:
```
python3 scripts/check_environment.py
```
FFmpegとPythonの依存関係をインストールします。macOS、Windows、Linuxの各コマンドについては README.md を参照してください。
有料APIを使わずに自然な翻訳を行うには、すでにインストールされているOllamaモデルを --translation-provider ollama --ollama-model MODEL で使用します。パイプラインはこれをローカルで2パス実行し、すべてのセグメントIDを検証します。納品前に専門用語とタイミングを確認してください。ローカルモデルが利用できない場合は、オンラインのドラフトとして --translation-provider google を許可がある場合にのみ使用し、タイムスタンプ付きセグメントを手動で修正するか、レビュー済みのJSONを --segments-file で渡します。OPENAI_API_KEY または DEEPSEEK_API_KEY は明示的に許可された場合にのみ使用し、許可されていないAPIに切り替えないでください。
動画URL（Bilibili、YouTube、またはyt-dlpがサポートする任意のサイト）を変換:
```
python3 scripts/translate_video.py "https://www.youtube.com/watch?v=VIDEO_ID" \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output
```
BilibiliのURLには ?p=2 のようなパートパラメータを含めることができます。完全なターゲットURLを渡してください。

またはローカル動画を処理:

python3 scripts/translate_video.py ./input.mp4 \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output

デフォルトとオプション

ソース言語のデフォルトは英語です (--source-language en)。自動検出するには auto を使用します。
中国語音声のデフォルトは zh-CN-XiaoxiaoNeural です。若い男性の声には --voice zh-CN-YunxiNeural、男性ナレーションの声には --voice zh-CN-YunyangNeural を使用します。
通話料がかからない自然な音声合成には、明示的に許可された参照クリップと正確なトランスクリプトが利用可能な場合、zero-shot モードのローカルインストール済み Fun-CosyVoice3-0.5B を優先します。それ以外の場合は、内蔵スピーカー（例：中文女）を使用して CosyVoice-300M-SFT を使用します。許可なく声をクローンしないでください。モデルはすべてのセグメントに対して一度だけロードされ、PCM16 WAVクリップを書き込み、進捗状況をチェックポイントします。フラグについては README.md を参照してください。
Edge TTSに到達できない場合は、DASHSCOPE_API_KEY を設定し、--tts-provider dashscope --voice Cherry を使用してQwen3 TTSを利用します。翻訳されたトランスクリプトテキストがDashScopeに送信されます。
翻訳のデフォルトは auto で、明示的に設定されたローカルの OLLAMA_MODEL のみを使用し、それ以外の場合は翻訳前に停止します。トランスクリプトを外部の翻訳サービスに送信する前に、--translation-provider openai または google を明示的に選択してください。Ollamaにはローカルサービスとインストール済みモデルが必要です。このスキルはモデルを自動的にダウンロードしません。ファイル名から主題が明確に特定できない場合は、--translation-context "動画のトピックとキーワード" を使用してください。それ以外の場合はタイトルまたはファイル名が使用されます。
--audio-mode replace はソース音声を中国語音声に置き換えます（デフォルト、信頼性が高い）。--audio-mode mix は元のトラックを低音量で保持し、その上に中国語音声を重ねます。--audio-mode background はオプションのDemucsを使用して元のボーカルを分離しようとし、残りの背景音に中国語音声をミックスします。Demucsが利用できないか失敗した場合、スクリプトは問題を報告し、安全に音声置き換えにフォールバックします。
--subtitle-mode soft はMP4に選択可能な中国語字幕を埋め込み、外部SRTも書き出します（デフォルト）。最初にソースフレームを確認してください。キャプションがすでに画像に焼き付けられている場合は、重複するテキストを避けるために soft を維持してください。burn は字幕を画像に焼き付け、subtitles/libassフィルタと使用可能な中国語フォントを持つFFmpegビルドが必要です。none はMP4から字幕を省略しますが、確認用のSRTサイドカーは書き出します。
ASRを調整するには、--model small（バランスの取れたデフォルト）、--model medium、または --model large-v3 を使用します。モデルが大きいほど、より多くのメモリと時間を必要とします。初回実行時に選択したモデルがダウンロードされます。
--cookies-from-browser chrome は、ログインしており、サイトがユーザー自身のブラウザセッションを必要とする場合にのみ使用してください。これはローカルブラウザのクッキーを読み取ります。デフォルトでは有効になっていません。
--keep-intermediates を使用すると、ダウンロードしたソース音声、WAVファイル、生成された音声クリップをトラブルシューティング用に保持します。
--segments-file path/to/translated.segments.json を使用すると、TTS障害後に認識と翻訳を繰り返すことなく、レビュー済みの翻訳を再利用できます。
--reuse-tts-dir path/to/tts_segments を既存の生成クリップセットとともに使用すると、音声サービスを再度呼び出すことなく、タイミングを調整して再レンダリングできます。

必要な出力チェック

スクリプトは、MP4が存在し、空でなく、ビデオストリームとオーディオストリームを持ち、入力に近い長さであることを確認する必要があります。最終MP4の隣に、SRT、翻訳済みセグメントJSON、および処理レポートを出力します。いずれかのステージが失敗した場合、パイプラインを停止し、出力が完了したふりをするのではなく、有用なエラーを提供する必要があります。

納品前に、翻訳されたJSON/SRTを調べて、誤って書き写された名前や用語、不自然な直訳調の表現、スピードアップまたはトリミングされたセグメントがないか確認してください。レンダリングされたフレームも確認してください。欠落グリフのボックス、画面外のキャプション、重複した焼き込み字幕を拒否してください。CosyVoiceの場合は、長い動画をレンダリングする前に短いサンプルを試聴してください。小数、コード名、英語の用語の実際の発音を、書かれたテキストだけでなく確認してください。レビュー済みセグメントでは、spoken_text を追加して数字やファイル名を自然に読み上げつつ、zh_text は正確な字幕のままにすることができます。それらの意味は一致している必要があります。切り詰められた音声や目立つスピードアップを避けてください。

ワークフロー

URLとローカルファイルを判別します。URLの場合は、yt-dlpを使用してリクエストされた動画のみをダウンロードします（--no-playlist）。Bilibiliページが412を返した場合、スクリプトは動画が明示的にダウンロード可能とマークされている場合にのみBilibiliの公開APIを使用できます。リクエストされた ?p= 部分を保持してください。DRM、ペイウォール、アカウント制限を回避しないでください。
ffprobeを使用してストリームと長さを検査します。モノラル16kHz PCM音声を抽出します。
faster-whisperで文字起こしを行い、ソースのタイムスタンプを保持します。音声が検出されない場合は明確に失敗します。
トピックと隣接する音声コンテキストを考慮して翻訳し、簡潔で慣用的な中国語に仕上げます。ID、順序、意味、数値、名前、専門用語を保持します。動画のトピックに照らしてソース認識エラーを確認します。
選択された音声サービスを介して、各中国語音声セグメントを生成します。タイムスタンプのウィンドウに保守的に収めます。セグメントに積極的なスピードアップや切り詰めが必要な場合は、レポートで警告します。
フルレングスの中国語音声トラックを構築します。リクエストされたオーディオモードを適用します。オプショナルなDemucs分離は拡張機能であり、必須の依存関係ではありません。
中国語SRTと翻訳済みJSONを書き込みます。リクエストに応じて字幕を多重化または焼き付け、広く互換性のあるH.264/AAC MP4をエクスポートし、結果を検証します。
正確な出力パス、選択した設定、警告、および残っているレビューの必要性を報告します。

例

# YouTube URL; API翻訳; 中国語女性の声; 抽出された背景音にボイスオーバー
OPENAI_API_KEY="$OPENAI_API_KEY" python3 scripts/translate_video.py "https://youtu.be/VIDEO_ID" \
  --translation-provider openai --audio-mode background --subtitle-mode soft --output-dir ./output

# Bilibili パート2; 設定済みのLLMキーを使用して自然な翻訳
python3 scripts/translate_video.py "https://www.bilibili.com/video/BV1NAuq6uE8t/?p=2" \
  --translation-provider openai --translation-context "規範驅動開發 SDD 與智能體編程" \
  --voice zh-CN-YunyangNeural --audio-mode mix --output-dir ./output

# 中国語字幕を画像に焼き付け
python3 scripts/translate_video.py ./input.mp4 --subtitle-mode burn --output-dir ./output

# CosyVoice3と許可された参照音声を使用した完全ローカル音声合成（有料API不要）
python3 scripts/translate_video.py ./input.mp4 --segments-file ./reviewed.segments.json \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/Fun-CosyVoice3-0.5B \
  --cosyvoice-mode zero-shot --cosyvoice-prompt-audio ./reference.wav \
  --cosyvoice-prompt-text-file ./reference.txt --subtitle-mode burn --output-dir ./output

# ローカル文字起こし、Ollama翻訳、CosyVoiceナレーション
python3 scripts/translate_video.py ./input.mp4 --translation-provider ollama --ollama-model MODEL \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/CosyVoice-300M-SFT \
  --cosyvoice-mode sft --output-dir ./output

安全性と権利

自分が所有している、翻案するライセンスを持っている、またはダウンロードおよび変換を許可されている動画のみを処理してください。ソースプラットフォームの利用規約と著作権を尊重してください。DRMや技術的なアクセス制御を決して回避しないでください。--cookies-from-browser はオプトインであり、ユーザー自身の認証済みセッションのみを使用する必要があります。適用される権利を確認せずに、吹き替え派生作品を公開しないでください。

このプロジェクトは、学習、研究、技術交流を目的としています。違法行為、許可のない音声クローン、詐欺、なりすまし、誤解を招くコンテンツに使用しないでください。README.md の免責事項を参照してください。ユーザーは、適用法に基づき、生成されたコンテンツの使用と配布について責任を負います。

video-zh-dubbing：英語動画を中国語吹き替え完成版に