簡介pyVideoTrans是一款開源的視頻翻譯配音工具主要面向視頻創(chuàng)作者、字幕翻譯者和需要批量處理音視頻的用戶可將一種語言視頻自動生成指定語言字幕并完成配音。它集成語音識別、字幕翻譯、配音合成、字幕格式轉(zhuǎn)換、人聲分離、音視頻合并與格式轉(zhuǎn)換等多項功能且支持完全離線使用無需付費(fèi)或受功能限制。資源包共356個文件以Python源碼為主263個py文件另含51個txt配置說明、13個md文檔、9個json配置以及bat啟動腳本等整體約6.19MB結(jié)構(gòu)清晰適合二次開發(fā)與學(xué)習(xí)。已有278人瀏覽學(xué)習(xí)。通過源碼可掌握語音識別、翻譯API接入、配音合成等實現(xiàn)細(xì)節(jié)也能直接運(yùn)行或改造為個性化工具用于批量生成多語言字幕與配音視頻。1. 視頻翻譯配音工具當(dāng)“看不懂外語視頻”變成一條命令行就能解決的事做視頻內(nèi)容的人幾乎都遇到過這個場景拿到一段國外的高質(zhì)量教程或者案例視頻畫面和節(jié)奏都很好但語言不通字幕沒有配音更是想都別想。手動翻譯字幕再找配音動輒一兩天時間遇到批量處理直接崩潰。pyVideoTrans 就是沖著這個痛點(diǎn)來的——它把“語音識別、文本翻譯、字幕生成、TTS 配音、視頻封裝”這一整套流程打包成了 Python 源碼一次跑完輸出帶新語言字幕或配音的視頻文件。我實測下來最直接的感受是不需要懂音視頻底層原理只要會裝 Python 依賴、能讀懂命令行報錯就能把一段英文視頻轉(zhuǎn)成中文字幕版甚至中文配音版。適合做視頻漢化、課程搬運(yùn)、海外內(nèi)容二次創(chuàng)作的從業(yè)者也適合想研究語音處理流程的開發(fā)者。這個工具不是單文件腳本而是一套完整的項目包含 GUI 界面和核心處理引擎用 PySide6 做界面、whisper 系列做語音識別、翻譯接口做文本轉(zhuǎn)換、edge-tts 等做語音合成。實際跑通之后你會理解為什么它能在一眾“視頻翻譯工具”里被反復(fù)下載——因為整個工作流是閉環(huán)的且每一步都留了手動干預(yù)的口子。2. 識別、翻譯、配音三段式工作流核心模塊到底怎么協(xié)作的2.1 處理管線的四個階段pyVideoTrans 的核心管線可以拆成四個階段提取音軌、語音識別、文本翻譯、配音與合成。提取音軌這一步用的是 ffmpeg把視頻文件里的音頻流抽成 wav 格式臨時文件采樣率統(tǒng)一到 16kHz這個采樣率是 whisper 模型的標(biāo)準(zhǔn)輸入要求16kHz 以下的音頻識別準(zhǔn)確率會明顯下降所以代碼里強(qiáng)制做了重采樣。語音識別階段工具默認(rèn)調(diào)用 faster-whisper這是 whisper 的優(yōu)化版本用 CTranslate2 做推理后端比原版 OpenAI whisper 快 2 到 3 倍顯存占用也更低。我實測在 GTX 1660 6G 顯卡上跑 base 模型一段 10 分鐘的視頻識別耗時大概 3 分半而原版 whisper 要 8 分鐘以上。識別結(jié)果會帶時間戳生成 srt 格式字幕這是后續(xù)翻譯和配音對齊的基礎(chǔ)。如果不想用 whisper工具也支持接入其他識別服務(wù)但需要在配置里手動改 API 參數(shù)。文本翻譯階段比較靈活內(nèi)置了 Google 翻譯接口和 OpenAI 兼容接口兩種走法。默認(rèn)走 Google 免費(fèi)接口不需要 API key但偶爾會觸發(fā)頻率限制如果機(jī)器上有可用的 OpenAI 兼容服務(wù)可以在設(shè)置頁填 base_url 和 api_key翻譯質(zhì)量和穩(wěn)定性會好很多尤其是處理專業(yè)術(shù)語密集的視頻時。翻譯是逐條字幕進(jìn)行的保持原時間軸不變只替換文本內(nèi)容。配音階段是這套工具最花心思的地方。它內(nèi)置了 edge-tts 作為默認(rèn)語音合成引擎edge-tts 調(diào)用的是微軟在線語音服務(wù)支持幾十種語言和上百種音色效果接近真人。你可以給不同語言指定不同音色比如中文用曉曉英文用 Aria。合成出來的音頻片段會根據(jù)原字幕的時間戳逐條對齊最后用 ffmpeg 合并到視頻軌道里。合并時支持三種聲音處理模式只保留原音、原音降低音量作為背景、完全替換原音這個選擇直接影響成片效果。2.2 配置文件與參數(shù)選擇的關(guān)鍵邏輯項目根目錄下的 config.py 是所有參數(shù)的集中地。我第一次跑通時幾乎沒動它但調(diào)了兩次之后發(fā)現(xiàn)里面有些參數(shù)值得關(guān)注。whisper 模型大小決定識別速度和精度small 級別在中文和英文上已經(jīng)夠用medium 級別在嘈雜背景音下表現(xiàn)更好但 6G 顯存以下的機(jī)器跑 medium 會出現(xiàn)內(nèi)存溢出建議先從 small 開始。識別語言參數(shù) language 需要手動指定如果設(shè)置成 auto 會讓模型自動檢測反而在多語言混雜的視頻里導(dǎo)致時間軸錯亂。翻譯目標(biāo)語言 target_language 直接控制字幕輸出設(shè)置為 zh 或 zh-CN 時工具還會自動做中文標(biāo)點(diǎn)格式化。# config.py 關(guān)鍵參數(shù)示例節(jié)選 WHISPER_MODEL small # tiny/base/small/medium/large-v3 WHISPER_DEVICE cuda # cuda 或 cpu WHISPER_COMPUTE_TYPE int8 # int8 節(jié)省顯存float16 精度更高 SOURCE_LANGUAGE en # 源語言auto 會導(dǎo)致不穩(wěn)定 TARGET_LANGUAGE zh # 目標(biāo)語言 TTS_ENGINE edge-tts # edge-tts 或 openai 兼容 TTS TTS_VOICE_MAP {zh: zh-CN-XiaoxiaoNeural, en: en-US-AriaNeural}這段配置里最值得留意的是 WHISPER_COMPUTE_TYPE。int8 量化在 faster-whisper 里表現(xiàn)得非常成熟我用 small 模型開 int8識別精度和 float16 幾乎沒有可感知差異但顯存占用從 2.8G 降到了 1.3G這對低顯存顯卡很友好。如果你的顯卡是 8G 以上顯存可以改成 float16 跑 large-v3 模型字幕準(zhǔn)確率在英語視頻上能到 95% 以上。TTS_VOICE_MAP 是給字幕對配音用的key 是語言代碼value 是 edge-tts 的音色名你想換音色時只需要改這里的 value不用動任何業(yè)務(wù)代碼。2.3 數(shù)據(jù)流從視頻到成片中間文件都長什么樣工具處理時會在輸出目錄下生成一組中間文件理解這些文件的意義能幫你快速排查問題。假設(shè)輸入是一個叫 demo.mp4 的視頻處理完成后目錄里會看到 demo.srt原始語言字幕、demo_zh.srt翻譯后字幕、demo_zh.mp3配音音頻、demo_zh.mp4最終成片。值得提醒的是srt 文件是 UTF-8 編碼如果你用 Windows 自帶的記事本打開看到亂碼不要慌用 VS Code 或者記事本另存為時選擇 UTF-8 即可。中間文件的保留策略也能從側(cè)面反映工具的設(shè)計思路。默認(rèn)不會自動刪除音頻臨時文件和原始字幕這意味著你可以不重新識別直接手動改翻譯結(jié)果再合成——改動字幕文件后重新執(zhí)行翻譯和配音階段即可不用再跑一遍 whisper。這個機(jī)制我后面會詳細(xì)講。3. 動手跑通一次完整翻譯從環(huán)境搭建到參數(shù)調(diào)優(yōu)3.1 環(huán)境準(zhǔn)備與依賴安裝的坑這套工具的運(yùn)行環(huán)境要求不算高Python 3.9 到 3.11 都能跑我建議直接上 3.10因為部分依賴在 3.12 上還有兼容性問題whisper 相關(guān)庫對 3.10 的支持最穩(wěn)。你需要準(zhǔn)備的東西包括一個 Python 環(huán)境、FFmpeg 可執(zhí)行文件、以及顯卡驅(qū)動對應(yīng)的 CUDA 環(huán)境如果走 GPU 推理。純 CPU 也能跑但速度會慢 8 到 10 倍一段 5 分鐘的視頻在 CPU 上跑 small 模型可能要等 20 分鐘。FFmpeg 是必須提前裝好的獨(dú)立程序不是 pip 包。Windows 上我習(xí)慣用包管理器安裝Linux 上直接 apt 安裝裝完在命令行輸入 ffmpeg -version 能正常輸出版本號才算成功。如果你在啟動工具時遇到“找不到 ffmpeg”的報錯原因是系統(tǒng) PATH 環(huán)境變量里沒有 ffmpeg 的位置把 ffmpeg 所在目錄加入 PATH 即可。# 創(chuàng)建虛擬環(huán)境并安裝依賴Linux / macOS python3 -m venv pyvideotrans_env source pyvideotrans_env/bin/activate pip install -r requirements.txt這里有一個容易被人忽略的細(xì)節(jié)requirements.txt 里鎖定的依賴版本很重要不要一次性全部升級到最新版。whisper 系列對 numpy、torch 的版本有隱性要求我曾經(jīng)因為 torch 版本過新導(dǎo)致 CUDA 設(shè)備不可用回退到 requirements.txt 指定的版本后恢復(fù)正常。裝完后可以用一段 30 秒的短視頻先跑通整個流程不要拿長視頻直接試那會放大排查問題的成本。3.2 命令行模式跑通一次翻譯GUI 模式適合交互式操作但如果你想批量處理或者在服務(wù)器上跑命令行入口會更好用。項目里的 run.py 就是啟動入口參數(shù)比較復(fù)雜建議先看一遍參數(shù)幫助信息再動手。# 查看命令行幫助 python run.py --help # 單視頻翻譯示例 python run.py --input demo.mp4 --source_lang en --target_lang zh \ --model small --device cuda --voice_map zh-CN-XiaoxiaoNeural# 實際執(zhí)行會看到類似下面的日志輸出 [INFO] 提取音軌完成: demo.wav [INFO] 語音識別進(jìn)度: 45/128 條字幕 [INFO] 翻譯進(jìn)度: 45/128 條字幕 [INFO] 配音合成中: 13/128 條片段 [INFO] 視頻封裝完成: output/demo_zh.mp4--source_lang en指的是源視頻語言代碼--target_lang zh是目標(biāo)語言代碼--model small選擇 whisper 模型大小--device cuda指定用 GPU 推理--voice_map后面接的格式是“語言:音色名”如果你要用默認(rèn)音色可以不傳這個參數(shù)。顯存不夠的人把 device 改成 cpu 就行其他參數(shù)不變。3.3 參數(shù)調(diào)優(yōu)表不同場景下的推薦組合我是直接把常用參數(shù)整理成了表格每次接到新任務(wù)時先按表格選一輪再根據(jù)輸出結(jié)果微調(diào)。這里給出的組合都經(jīng)過實測你可以直接抄作業(yè)應(yīng)用場景視頻時長模型推薦計算類型翻譯接口備注短視頻快速翻譯1-3 分鐘tinyint8Google速度優(yōu)先字幕偶爾有錯教程視頻中文字幕10-20 分鐘smallint8Google性價比最優(yōu)推薦課程精譯需要發(fā)布20-60 分鐘mediumfloat16OpenAI 兼容翻譯質(zhì)量最穩(wěn)但耗時翻倍長視頻劇集翻譯60 分鐘以上large-v3float16OpenAI 兼容顯存低于 8G 慎選medium 是顯存分水嶺這回事我自己在 6G 顯存上試過int8 勉強(qiáng)能跑但速度已經(jīng)降到和 CPU 差不多所以 6G 顯存以下就老實待在 small別硬上。翻譯接口這塊Google 免費(fèi)接口一天能處理的請求量有個隱性上限如果你發(fā)現(xiàn)翻譯到一半開始報超時錯基本就是頻率限制了等幾分鐘重試還能繼續(xù)但大量任務(wù)建議直接切 OpenAI 兼容接口。3.4 GUI 模式操作要點(diǎn)GUI 模式對不熟悉命令行的從業(yè)者非常友好。啟動后主界面分為左右兩欄左側(cè)是視頻文件列表支持批量拖拽右側(cè)是參數(shù)設(shè)置區(qū)。你需要做的操作是點(diǎn)“選擇視頻文件夾”導(dǎo)入視頻在語言選項里把源語言設(shè)成英文、目標(biāo)語言設(shè)成中文然后在模型選擇下拉框里選 small最后點(diǎn)“開始任務(wù)”。批量任務(wù)時注意看任務(wù)隊列的狀態(tài)列每行任務(wù)都有獨(dú)立進(jìn)度條雙擊某一行的任務(wù)名稱會展開當(dāng)前處理階段的詳細(xì)信息。如果某一行任務(wù)是紅色狀態(tài)說明處理失敗可以點(diǎn)開日志窗口查看具體原因。GUI 模式下有一個很方便的功能是“字幕預(yù)覽”翻譯完成后會彈出一個表格每一行是一條字幕你可以直接在表格里修改譯文再點(diǎn)“重新合成”按鈕這比命令行模式高效很多。這個功能在處理專業(yè)術(shù)語比較多的視頻時幾乎是必須的因為任何自動翻譯在術(shù)語上都可能出錯。4. 翻車現(xiàn)場常見報錯與逐條排查記錄4.1 CUDA 不可用但顯卡明明支持現(xiàn)象程序啟動時提示 CUDA error但 nvidia-smi 能看到顯卡驅(qū)動也是最新的。原因PyTorch 安裝的是 CPU 版本或者 CUDA 版本和 PyTorch 需要的版本不匹配。解決辦法先卸載現(xiàn)有 PyTorch再安裝對應(yīng) CUDA 版本的 PyTorch。我用的命令是 pip install torch --index-url https://download.pytorch.org/whl/cu118裝完再驗證 torch.cuda.is_available() 是否返回 True。這條坑出現(xiàn)的頻率極高尤其是從官網(wǎng)直接 pip install torch 的人默認(rèn)裝的是 CPU 版。4.2 識別結(jié)果空白或字幕時間軸錯亂現(xiàn)象處理完成后 srt 文件存在但內(nèi)容全空或者時間軸重疊、順序顛倒。原因一種是源視頻里沒有人聲只有背景音樂whisper 識別不到有效語音另一種是視頻本身包含多段拼接內(nèi)容whisper 對靜音段的處理不理想。解決辦法先用播放器確認(rèn)視頻確實有人聲再看識別日志——如果日志顯示識別出來的文本數(shù)量為 0就是音軌本身沒有語音信號如果時間軸錯亂把識別語言從 auto 改成明確的源語言代碼強(qiáng)制 whisper 用指定語言模型解碼。4.3 翻譯完成后字幕沒有替換成目標(biāo)語言現(xiàn)象任務(wù)狀態(tài)顯示完成但生成的視頻里字幕還是原文。原因GUI 模式下修改過字幕預(yù)覽表但沒點(diǎn)“應(yīng)用修改”按鈕或者命令行模式下翻譯階段被跳過了。解決辦法GUI 模式下改完字幕先點(diǎn)“保存修改”再點(diǎn)“重新合成”命令行模式檢查參數(shù)是否正確傳入了 target_lang如果用的是配置文件檢查 config.py 里 TARGET_LANGUAGE 的值是否被注釋掉了。有一次我改了 config.py 但沒保存導(dǎo)致所有任務(wù)都用了默認(rèn)配置排查了半天才發(fā)現(xiàn)。4.4 edge-tts 語音合成時報“No connection could be made”現(xiàn)象任務(wù)在配音階段失敗日志顯示網(wǎng)絡(luò)連接錯誤。原因edge-tts 走的是微軟在線服務(wù)網(wǎng)絡(luò)環(huán)境不穩(wěn)定或代理設(shè)置不正確都會導(dǎo)致連接失敗。解決辦法檢查機(jī)器是否能正常訪問微軟服務(wù)域名如果網(wǎng)絡(luò)環(huán)境有限制考慮切換本地 TTS 引擎比如 pyttsx3 配合系統(tǒng)自帶語音包。工具在 TTS_ENGINE 配置項里預(yù)留了這個切換入口但本地語音包的效果和 edge-tts 差距明顯能聯(lián)網(wǎng)還是優(yōu)先用 edge-tts。4.5 視頻合成后畫面和音軌不同步現(xiàn)象成片播放時配音和畫面字幕有明顯延遲延遲時間隨播放進(jìn)度增加而增加。原因不是合成工具的問題而是原視頻的音頻流本身就存在偏移或者視頻包含多音軌ffmpeg 在抽取時選錯了音軌。解決辦法先檢查原視頻有多少條音軌——用 ffmpeg -i demo.mp4 查看輸出中的 Audio 行數(shù)如果有兩條以上在配置里指定音軌編號讓工具提取正確的軌道。另外如果原視頻的時間基準(zhǔn)不是標(biāo)準(zhǔn)的 30fpsffmpeg 重采樣時可能產(chǎn)生微小偏移這種情況一般不影響觀看但如果嚴(yán)格要求同步可以用“字幕微調(diào)”功能手動調(diào)整整體偏移毫秒數(shù)。我認(rèn)為最值得養(yǎng)成的排查習(xí)慣是每次跑任務(wù)前先看日志日志里每個階段都有明確的時間戳和文件路徑只要看到步驟卡在哪就能縮小排查范圍比盲猜配置有效得多。5. 進(jìn)階玩法批量處理、字幕人工校對與局部重翻5.1 批量處理不再需要逐個操作項目支持命令行批量執(zhí)行把所有待處理視頻放在一個文件夾里循環(huán)調(diào)用即可。我一般會寫一個簡單的 shell 腳本把文件夾里所有 mp4 文件按順序處理每個視頻獨(dú)立輸出到自己的輸出目錄這樣互不干擾。# 批量處理腳本示例Linux / macOS for file in /path/to/videos/*.mp4; do echo 開始處理: $file python run.py --input $file --source_lang en --target_lang zh \ --model small --device cuda --output_dir /path/to/output done# Windows PowerShell 循環(huán)處理 $files Get-ChildItem C:\videos\*.mp4 foreach ($f in $files) { Write-Host 處理中: $($f.Name) python run.py --input $f.FullName --source_lang en --target_lang zh --model small --device cuda --output_dir C:\output }批量處理時最重要的是控制顯存占用。每次處理完一個文件后顯存不會自動完全釋放如果連續(xù)處理多個長視頻可能到第三個視頻時顯存溢出。我的做法是每處理 5 個視頻重啟一次 Python 進(jìn)程或者在批處理腳本里加一個顯存監(jiān)測命令超過閾值就自動休眠 30 秒再繼續(xù)。5.2 字幕人工校對利用中間文件實現(xiàn)精準(zhǔn)修正如果你對自動翻譯的字幕質(zhì)量不滿意完整流程可以這樣走第一步直接用工具跑到翻譯完成不加配音第二步打開生成的_zh.srt文件手動修改有問題的翻譯條目第三步重新執(zhí)行配音和合成。因為識別結(jié)果還保留在中間文件里工具會直接讀取你改好的字幕做 TTS 合成不會二次識別。這個流程在實操里非常實用。自動翻譯最大的問題在于專有名詞和縮寫詞比如 “API” 會被翻譯成 “應(yīng)用程序編程接口”、人名地名經(jīng)常出錯。我處理課程視頻時通?；?15 分鐘過一遍字幕只改術(shù)語和人名其他保持原樣整體質(zhì)量就能從“勉強(qiáng)可看”提升到“接近人工翻譯”。5.3 局部重翻譯選定時間范圍重新處理項目里有單獨(dú)的時間段截取功能不需要重跑整個視頻。用法是先文字定位時間點(diǎn)比如發(fā)現(xiàn)某段 3 分鐘左右的翻譯質(zhì)量特別差可以只針對那段時間重新做識別和翻譯產(chǎn)出的字幕文件會自動和原時間軸合并。命令行參數(shù)是--start_time 00:05:00 --end_time 00:08:00對應(yīng)從第 5 分鐘到第 8 分鐘的片段。我通常會先快速看一遍成片記錄質(zhì)量差的片段位置然后一次性全部重翻。要注意的是局部重翻時源語言識別參數(shù)必須和第一次一致否則同一段視頻可能識別出不同的文本導(dǎo)致字幕前后風(fēng)格不統(tǒng)一。另外重翻后的片段在執(zhí)行配音時如果原音軌在那個時間段有人聲重疊處理邏輯會直接把原音抹掉這在訪談類視頻里需要注意——因為配音會蓋過一切原聲。5.4 音色選擇與多語言混配如果你做的是多語言字幕視頻比如一個視頻需要同時輸出中文字幕和英文字幕配音可以分別指定音色。TTS_VOICE_MAP 支持多語言條目不同語言之間用分號隔開處理時會根據(jù)字幕語言自動選擇對應(yīng)的音色。我發(fā)現(xiàn)一個有意思的用途是給同一個視頻做不同情緒的配音版本——edge-tts 不同的音色在語速和語調(diào)上有區(qū)別比如中文曉曉音色偏沉穩(wěn)云希音色偏活潑用在不同的視頻風(fēng)格里效果差異很大。這個參數(shù)在 GUI 模式里也有下拉框可以直接選不需要手動編輯配置文件。6. 最后一道工序成片質(zhì)量自檢與文件交付習(xí)慣視頻處理完成之后不要急著上傳或分發(fā)我建議強(qiáng)制自己走一遍質(zhì)量檢查流程。首先要檢查音畫同步重點(diǎn)看每一段配音的起始位置是否和字幕一致最容易出問題的是原視頻開頭有片頭或者靜音段這些區(qū)域的時間軸偏移會在后期被放大。檢查方法是把成片拖進(jìn)剪輯軟件看波形圖和字幕時間軸是否對齊。其次要做術(shù)語一致性檢查打開字幕文件搜索你希望使用的專有名詞看是否被統(tǒng)一替換比如項目名、產(chǎn)品名、人名都有固定譯法的手工修正一遍。交付文件時我有自己的固定習(xí)慣——輸出目錄里除了最終視頻還會保留原始字幕、翻譯字幕和一個簡要的 README 說明文件。說明文件里記錄視頻的基本信息、處理參數(shù)、做了哪些手工修正這能幫你在幾周后回看時快速回憶起當(dāng)時的情況。如果這個視頻還要交付給別人做二次編輯保留 srt 文件比讓剪輯師從視頻里提取字幕效率高得多。關(guān)于驗證方法我的習(xí)慣是每批視頻處理完抽取 10% 做抽檢抽檢內(nèi)容包括開頭 30 秒、中間隨機(jī) 30 秒、結(jié)尾 30 秒。開頭最容易檢查是否有片頭錯位中間檢查術(shù)語翻譯是否準(zhǔn)確結(jié)尾檢查音頻是否被截斷。如果抽檢出現(xiàn)問題整批視頻重新跑一遍校對流程不要心存僥幸——視頻平臺上出現(xiàn)翻譯錯誤是會被用戶在評論區(qū)直接罵的這種代價比重新處理大得多。自從經(jīng)歷過一次交付后才發(fā)現(xiàn)某段字幕時間軸整體偏移了 800 毫秒的教訓(xùn)從那以后我每次批量處理完都會強(qiáng)制走一遍波形圖檢查確認(rèn)配音片段的時間戳和字幕完全咬合再生成交付文件。希望這套工作流能幫你在用 pyVideoTrans 處理視頻翻譯配音時少踩幾個坑尤其是那些日志不會直接告訴你但實際影響成片質(zhì)量的細(xì)節(jié)。本文還有配套的精品資源點(diǎn)擊獲取