影片轉中文配音

使用內建的 Python 管道生成完整的中文配音影片。當使用者提供網址並要求完成的成品時，請勿僅提供建議的工作流程：如果終端機執行可用且使用者已授權所需的網路/下載動作，請執行此管道。

需要 Python 3.10+、FFmpeg/ffprobe、用於下載網址的網路存取，以及本機的 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 依賴項。請參閱 README.md 以了解 macOS、Windows 和 Linux 的安裝指令。
若要在不使用付費 API 的情況下進行自然翻譯，請使用已安裝的 Ollama 模型，搭配 --translation-provider ollama --ollama-model MODEL。管線會在本機執行雙次翻譯，並驗證每個片段 ID；在交付前，請檢閱技術術語和時間碼。如果沒有可用的本機模型，請僅在獲得許可的情況下使用 --translation-provider google，作為線上草稿，並手動潤飾帶時間戳的片段，或透過 --segments-file 傳入已審核的 JSON。僅在明確允許時使用 OPENAI_API_KEY 或 DEEPSEEK_API_KEY；絕不切換到不允許的 API。

轉換影片網址（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 網址可包含 ?p=2 等片段參數；請傳入完整的目標網址。

或處理本機影片：

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 選擇男聲旁白。
對於自然且無按次付費的語音，當有明確授權的參考片段和完整轉寫文字可用時，建議使用本機安裝的 Fun-CosyVoice3-0.5B 並採用 zero-shot 模式。否則，請使用內建說話人（例如 中文女）的 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 "video topic and key terms"；否則會使用標題或檔案名稱。
--audio-mode replace 會以中文語音取代來源音訊（預設，可靠）。--audio-mode mix 會將原始音軌以較低音量保留，與中文語音混合。--audio-mode background 會嘗試使用選用的 Demucs 分離原始人聲，然後將中文語音與剩餘的背景音混合。如果 Demucs 不可用或失敗，腳本會報告問題並安全地回退到取代音訊。
--subtitle-mode soft 會將可選擇的中文字幕嵌入 MP4，並同時寫入外部 SRT 檔案（預設）。首先檢查來源影格：如果字幕已燒錄在畫面中，請保持 soft 以避免重疊的重複文字。burn 會將字幕燒錄到畫面中，並需要一個帶有 subtitles/libass 過濾器的 FFmpeg 建置，以及一個可用的中文字型。none 會從 MP4 中省略字幕，但仍會寫入一個 SRT 側邊檔案以供檢閱。
使用 --model small（平衡的預設值）、--model medium 或 --model large-v3 調整 ASR。較大的模型需要更多記憶體且耗時更長。第一次執行會下載所選模型。
僅當您已登入且網站需要您自己的瀏覽器工作階段時，才使用 --cookies-from-browser chrome。這會讀取本機瀏覽器 Cookie；預設不會啟用。
使用 --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 保持為準確的字幕。它們的含義必須相符。避免交付剪輯過的語音或明顯的加速。

工作流程

解析網址 vs 本機檔案。對於網址，使用 yt-dlp 僅下載請求的影片（--no-playlist）。如果 Bilibili 頁面返回 412，腳本可能僅在影片明確標記為可下載時使用 Bilibili 的公開 API；保留請求的 ?p= 部分。絕不繞過 DRM、付費牆或帳戶限制。
使用 ffprobe 檢查串流和時長。提取單聲道 16 kHz PCM 音訊。
使用 faster-whisper 進行轉寫，保留來源時間碼。如果未檢測到語音，則明確失敗。
根據主題和相鄰語音上下文進行翻譯，然後潤飾為簡潔、地道的中文。保留 ID、順序、含義、數字、名稱和技術術語。根據影片主題檢查來源辨識錯誤。
透過選定的語音服務生成每個中文語音片段。保守地將其適配到時間碼視窗中；當片段需要激進的速度調整或截斷時，在報告中發出警告。
建構一段全長的中文語音音軌。應用請求的音訊模式；選用的 Demucs 分離是一項增強功能，而非硬性依賴。
寫入中文 SRT 和翻譯後的 JSON。按請求嵌入或燒錄字幕，匯出廣泛相容的 H.264/AAC MP4，並驗證結果。
報告確切的輸出路徑、所選設定、警告以及任何剩餘的審核需求。

範例

# YouTube 網址；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：英文影片轉中文配音成片