Automatically dub YouTube videos with synchronized Vietnamese TTS.
demo_1min.mp4
Pipeline:
YouTube URL
│
▼ Step 1 — download
│ yt-dlp downloads video + Vietnamese subtitles (.vi.vtt)
│ Falls back to auto-translated vi-en if vi is unavailable
│
▼ Step 2 — normalize
│ Parses YouTube karaoke-tagged VTT → sentence-level timing
│ Removes speaker labels [Name], sound effects (description)
│ Handles numbers (10.000) and abbreviations (U.S.A) correctly
│
▼ Step 3 — tts
│ Vieneu TTS synthesizes each sentence
│ Compresses audio to fit timeline window (pitch-preserving)
│ Outputs single *_vi_timeline.wav
│
▼ Step 4 — merge (requires ffmpeg)
ffmpeg mixes original audio (20% volume) + TTS audio
Outputs *_vi.webm / *_vi.mp4 in the same container format
- Python 3.10+
- ffmpeg on
$PATH(brew install ffmpegon macOS) - Apple Silicon Mac recommended for Vieneu Metal acceleration
git clone https://github.com/drminh2807/vi-dubber.git
cd vi-dubberpython3 -m venv venv
source venv/bin/activatepip install --upgrade "yt-dlp[default,curl-cffi]"pip install vieneu --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal/For other platforms, omit the --extra-index-url flag.
pip install -r requirements.txtThat's it — no extra install step required. You can run the tool directly with python -m vi_dubber (see Usage below).
Optional:
pip install -e .installs thevi-dubberconsole command globally in the venv so you can typevi-dubberinstead ofpython -m vi_dubber.
python -m vi_dubber https://youtu.be/XXXXXXXXXXXMultiple URLs at once:
python -m vi_dubber https://youtu.be/AAA https://youtu.be/BBBOptions:
| Flag | Default | Description |
|---|---|---|
-o DIR / --output-dir DIR |
Output/ |
Directory for all output files |
--orig-volume VOL |
0.20 |
Original audio volume (0–1) in final video |
-v / --verbose |
off | Show detailed logs and library output |
# Step 1: download video + subtitles
python -m vi_dubber download https://youtu.be/...
# Step 2: normalize subtitles (sentence splitting + timing)
python -m vi_dubber normalize
# Step 3: TTS synthesis
python -m vi_dubber tts
# Step 4: merge into video
python -m vi_dubber merge --orig-volume 0.15Each step skips files that already exist, so you can re-run safely.
from pathlib import Path
from vi_dubber.download import download_with_subs
from vi_dubber.subtitle import sentences_with_timing, write_normalized_vtt
from vi_dubber.tts import synthesize_timeline
from vi_dubber.merge import merge_audio
output = Path("Output")
download_with_subs(["https://youtu.be/..."], output)
for vtt in sorted(output.glob("*.vi.vtt")):
cues = sentences_with_timing(vtt)
norm = write_normalized_vtt(vtt, cues)
synthesize_timeline(norm, output)
merge_audio(output, orig_volume=0.20)| File | Description |
|---|---|
Output/<title>.vi.vtt |
Original Vietnamese subtitles |
Output/<title>.vi_normalized.vtt |
Sentence-split subtitles with karaoke timing |
Output/<title>_vi_timeline.wav |
TTS audio aligned to video timeline |
Output/<title>_vi.webm |
Final dubbed video |
yt-dlp releases frequently to keep up with YouTube changes. Always upgrade before a new download session:
pip install --upgrade "yt-dlp[default,curl-cffi]"Vietnamese TTS powered by vieneu — a beautiful open-source Vietnamese TTS engine. Thank you for making high-quality Vietnamese speech synthesis accessible to everyone.
MIT — see LICENSE.