| name | video-dubbing |
| description | Translate video/audio content into another language with dubbed voice and synchronized subtitles. Use this skill whenever the user asks to: translate a video, dub a video, generate foreign-language voiceover for a video, add translated subtitles with dubbed audio, or any workflow involving ASR → translate → TTS → video composition.
|
Video Dubbing & Subtitle Sync
Complete workflow: ASR → translate → TTS → merge audio → burn subtitles
Pipeline
视频 → 抽音轨(16kHz) → ASR(whisper) → AI翻译 → TTS(dub_segments) → 合并音轨 → 烧录硬字幕
Workflow
0. Prerequisite Check
Ensure whisper + moviepy + mlx-audio are installed:
pip install openai-whisper moviepy 2>/dev/null
pip install mlx-audio 2>/dev/null
1. Extract Audio & Transcribe (ASR)
Extract 16kHz mono audio, then run whisper for accurate per-segment timestamps:
ffmpeg -y -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio16k.wav
whisper audio16k.wav \
--model large-v3-turbo \
--language <source_lang> \
--output_format srt \
--output_dir .
Output: audio16k.srt with native timestamps matching the video.
Use large-v3-turbo for best accuracy. If you want even better Chinese recognition, install Qwen3-ASR (pip install qwen-asr) and use scripts/qwen3_asr.py instead.
2. Translate Subtitles (AI does this)
Read the SRT, translate each segment's text into the target language. Output one line per SRT segment, preserving order exactly.
- Count SRT segments first (e.g. 27 segments → 27 translated lines)
- Save as
translated.txt in the working directory
- Verify line count matches SRT segment count before proceeding
3. Generate Dubbed Audio
python3 scripts/dub_segments.py audio16k.srt translated.txt dubbing.wav subtitle_synced.srt --lang <target_lang>
What it does:
- Generates TTS per segment with voice consistency (first segment = voice reference)
- Preserves original timestamps — subtitles stay synced with video
- Smart speed adjustment: only adjusts segments that overflow their slot (atempo 0.88–1.20)
- Bridges adjacent gaps <1s for natural flow
4. Merge Dubbed Audio into Video
ffmpeg -y \
-i input.mp4 \
-i dubbing.wav \
-map 0:v:0 -map 1:a:0 \
-c:v copy -c:a aac -b:a 192k \
-shortest \
output_temp.mp4
Verify audio replaced:
ffprobe -v error -show_entries stream=codec_type -of csv=p=0 output_temp.mp4
5. Burn Hard Subtitles into Video
python3 scripts/burn_subtitles.py output_temp.mp4 subtitle_synced.srt output_final.mp4
This renders translated subtitles permanently into the video frame (hardcoded).
6. Cleanup (Optional)
rm -f audio16k.wav audio16k.srt translated.txt dubbing.wav subtitle_synced.srt output_temp.mp4
Output Files
| File | Description |
|---|
output_final.mp4 | Final video with dubbed audio + hardcoded subtitles |
subtitle_synced.srt | Synced subtitles (original timestamps + translated text) |
dubbing.wav | Per-segment aligned dubbing track |
Key Design Decisions
| Principle | Why |
|---|
| Preserve original ASR timestamps | They match the video's visual cues natively. Re-ASR on dubbing drifts. |
| Per-segment speed adjustment (0.88–1.20x) | Global atempo on the whole dubbing sounds robotic. Per-segment is natural. |
| Hard subtitles (burned in) | Soft subtitles don't work on all platforms. Burn them so they always show. |
| 16kHz mono for ASR | Whisper expects this. Higher sample rate wastes compute without improving accuracy. |
| Voice consistency via first segment reference | mlx-tts supports --ref_audio. First segment sets the voice for all others. |
| No Demucs by default | For typical narration/speech videos, background music removal is unnecessary overhead. |
| large-v3-turbo model | Best accuracy/speed tradeoff. Significantly better than base for proper nouns and fast speech. |
Dependencies
| Component | Install | Purpose |
|---|
ffmpeg | brew install ffmpeg | Audio extraction, merging |
openai-whisper | pip install openai-whisper | Speech-to-text (ASR) |
moviepy | pip install moviepy | Burn subtitles into video |
mlx-audio | pip install mlx-audio | TTS on Apple Silicon |
qwen-asr | pip install qwen-asr (optional) | Better Chinese ASR |
Common Mistakes to Avoid
| Mistake | Why It Fails | Correct Approach |
|---|
ffmpeg without -map | Picks original audio (video source's audio stream), dubbing ignored | Always use -map 0:v:0 -map 1:a:0 |
| Global atempo on entire dubbing | All speech slows uniformly (EN→ZH ~0.8x), sounds robotic | Per-segment alignment (dub_segments.py) |
| Re-ASR on dubbed audio for timestamps | Timestamps drift from visual cues | Reuse original Step 1 timestamps |
| Translation line count ≠ SRT segments | dub_segments.py requires strict 1:1 mapping | Count SRT segments first, match exactly |
Use whisper base/tiny model | Proper nouns wrong, fast speech missed | Use large-v3-turbo or turbo |
| Burn subtitles without checking FFmpeg libass | subtitles= filter silently fails | Use scripts/burn_subtitles.py (moviepy) |
| Translate segments out of order | Subtitles play at wrong times | Keep segment order: 1 translated line per SRT segment |
| Skip verification | Audio may not have been replaced | Run ffprobe to check both audio + video streams exist |
