Refactor: centralized configuration, removed legacy code, updated CLI and docs

Author: mangodxd

README.md

@@ -4,25 +4,23 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A Python pipeline that takes a YouTube URL and spits out a dubbed/subtitled video. Feed it a link, pick a target language, and it handles the rest — downloading, transcribing, translating, synthesizing speech, and rendering the final video.
-
-We built this because existing tools were either too manual, too expensive, or too locked-in. This one runs locally, stays free, and gives you full control over the output.
+Translate, subtitle, and dub any YouTube video automatically. Takes a URL and a target language — handles download, transcription, translation, TTS, and final render locally.
 
 ---
 
 ## How it works
 
 ```
-YouTube URL → Download → Transcribe (Whisper) → Chunk → Translate → TTS → Mix → Render
+YouTube URL → Download → Transcribe (Whisper) → Chunk → Translate (Google) → TTS → Mix → Render
 ```
 
-1. **Download** — pulls video and audio via `yt-dlp`
-2. **Transcribe** — runs Whisper ASR to get timestamped text
-3. **Chunk** — splits transcript into natural speech segments (respects silence gaps, max 10s)
-4. **Translate** — sends segments to Google Translate (RPC method, falls back to scraping)
-5. **TTS** — synthesizes each segment using Edge TTS with the appropriate voice
-6. **Mix** — overlays TTS audio on top of the original, ducked by 12dB
-7. **Render** — burns subtitles and/or swaps the audio track via FFmpeg
+1. **Download** — video + audio via `yt-dlp`
+2. **Transcribe** — Whisper ASR with VAD and temperature fallback
+3. **Chunk** — groups into natural speech segments (≤10s, split at silences)
+4. **Translate** — Google Translate (RPC → scrape fallback)
+5. **TTS** — Edge TTS or Qwen3-TTS with voice cloning & personas
+6. **Mix** — tempo-aligned TTS overlaid with optional background music
+7. **Render** — burns subtitles and/or replaces audio via FFmpeg
 
 ---
 
@@ -31,17 +29,15 @@ YouTube URL → Download → Transcribe (Whisper) → Chunk → Translate → TT
 ### Prerequisites
 
 - Python 3.10+
-- FFmpeg in your PATH
-- (Optional) CUDA for faster Whisper inference
+- FFmpeg in PATH
+- (Optional) CUDA GPU for faster Whisper
 
 ```bash
 # macOS
 brew install ffmpeg
-
 # Ubuntu/Debian
 sudo apt install ffmpeg
-
-# Windows — grab a build from https://ffmpeg.org/download.html
+# Windows — https://ffmpeg.org/download.html
 ```
 
 ### Install
@@ -50,15 +46,16 @@ sudo apt install ffmpeg
 pip install youtube-auto-dub
 ```
 
-Or install from source:
+Or from source:
 
 ```bash
 git clone https://github.com/mangodxd/youtube-auto-dub.git
 cd youtube-auto-dub
 pip install .
 ```
 
-For GPU support:
+For GPU:
+
 ```bash
 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
 ```
@@ -74,20 +71,17 @@ youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID"
 # Or via python -m
 python -m youtube_auto_dub "https://youtube.com/watch?v=VIDEO_ID"
 
-# Or legacy entry point (still works)
-python main.py "https://youtube.com/watch?v=VIDEO_ID"
-
-# Just subtitles, in Spanish
-youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --mode sub --lang es
+# Just subtitles, Spanish
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" -m sub -l es
 
 # Dubbing only, French, female voice
-youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --mode dub --lang fr --gender female
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" -m dub -l fr -g female
 
 # Different languages for subs and dub
-youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --mode both --lang_sub en --lang_dub vi
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" -m both -s en -d vi
 
-# Age-restricted or private video — pull cookies from your browser
-youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --lang es --browser chrome
+# Age-restricted — pull cookies from browser
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" -b chrome
 ```
 
 ### All options
@@ -97,17 +91,35 @@ youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --lang es --browser chro
 | `url` | | YouTube URL (required) |
 | `--mode` | `-m` | `sub`, `dub`, or `both` (default: `both`) |
 | `--lang` | `-l` | Target language for both sub and dub |
-| `--lang_sub` | `-ls` | Override subtitle language |
-| `--lang_dub` | `-ld` | Override dubbing language |
+| `--sub-lang` | `-s` | Override subtitle language |
+| `--dub-lang` | `-d` | Override dubbing language |
 | `--gender` | `-g` | `male` or `female` voice (default: `female`) |
-| `--whisper_model` | `-wm` | `tiny`, `base`, `small`, `medium` |
+| `--model` | | Whisper model: `tiny`, `base`, `small`, `medium`, `large` |
 | `--browser` | `-b` | Cookie source: `chrome`, `edge`, `firefox` |
+| `--tts-engine` | `-e` | `edge` or `qwen` (default: `edge`) |
+| `--voice` | | Qwen3-TTS persona: `narrator-m`, `young-f`, etc. |
+| `--voice-clone` | | Auto-clone voice from source audio |
+| `--no-tempo` | | Disable tempo alignment |
+| `--no-vad` | | Disable voice-activity detection |
+| `--bg-music` | | Mix original background audio into dub |
+| `--output-dir` | `-o` | Output directory (default: `./output`) |
+| `--version` | | Show version |
 
 ---
 
-## Language & voice config
+## Configuration
+
+All defaults are centralized in `youtube_auto_dub/models.py` and can be overridden via environment variables:
 
-Voices are mapped in `language_map.json` inside the package. Edit it to change defaults or add new languages:
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `YAD_CACHE_DIR` | `./.cache` | Download cache |
+| `YAD_TEMP_DIR` | `./temp` | Intermediates |
+| `YAD_OUTPUT_DIR` | `./output` | Final videos |
+| `YAD_SAMPLE_RATE` | `24000` | TTS / export sample rate |
+| `YAD_AMBIENT_GAIN` | `0.15` | Background music volume |
+
+Voices are mapped in `youtube_auto_dub/language_map.json`. Edit to add languages or change voices:
 
 ```json
 {
@@ -121,103 +133,71 @@ Voices are mapped in `language_map.json` inside the package. Edit it to change d
 }
 ```
 
-Common codes: `es` · `fr` · `de` · `it` · `pt` · `ja` · `ko` · `zh` · `ar` · `hi` · `ru` · `vi` · `th`
+Common codes: `es` `fr` `de` `it` `pt` `ja` `ko` `zh` `ar` `hi` `ru` `vi` `th`
 
 ---
 
 ## Project structure
 
 ```
-youtube-auto-dub/
-├── pyproject.toml           # Package config, dependencies, CLI entry
-├── main.py                 # Legacy entry point (thin wrapper)
-├── language_map.json       # (root copy kept for reference)
-└── youtube_auto_dub/       # Installable Python package
-    ├── __init__.py         # Package version
-    ├── __main__.py         # python -m youtube_auto_dub support
-    ├── cli.py              # Thin CLI adapter (argparse → pipeline)
-    ├── pipeline.py         # Pipeline orchestration logic
-    ├── models.py           # Dataclasses (SubtitleSegment, ProjectContext)
-    ├── youtube.py          # yt-dlp wrapper, audio extraction
-    ├── media.py            # Chunking, SRT, mixing, FFmpeg render
-    ├── googlev4.py         # Google Translate (RPC + scrape fallback)
-    ├── tts.py              # Edge TTS synthesis with retry
-    ├── transcriber.py      # Whisper transcription + device manager
-    ├── renderer.py         # FFmpeg helper utilities
-    ├── segmenter.py        # Smart segmentation (dynamic chunking)
-    ├── config.py           # Config manager, language data loading
-    ├── exceptions.py       # Custom exception hierarchy
-    ├── utils.py            # General-purpose utilities
-    ├── engine.py           # Legacy AI Engine (preserved for BC)
-    └── language_map.json   # Language → voice mappings (package data)
-├── tests/
-│   ├── test_models.py      # Model dataclass tests
-│   ├── test_googlev4.py    # Translation shortcut tests (no network)
-│   └── test_tts.py         # Voice lookup tests
-.tests/
-├── .github/workflows/
-│   └── ci.yml              # Ruff lint + pytest on 3.10, 3.11, 3.12
-├── .cache/                 # Downloaded videos (persists between runs)
-├── output/                 # Final rendered videos
-└── temp/                   # Intermediate files (cleared each run)
+youtube_auto_dub/
+├── __init__.py       # Package version
+├── __main__.py       # python -m support
+├── cli.py            # argparse with global-standard flags
+├── core.py           # Pipeline orchestrator (7-step run)
+├── models.py         # Dataclasses + all centralized constants
+├── audio.py          # Chunking, mixing, tempo align, loudness, render
+├── speech.py         # Whisper ASR with VAD & metadata prompt
+├── subs.py           # SRT parsing, resplit, refinement
+├── voice.py          # Edge TTS + Qwen3-TTS synthesis
+├── googlev4.py       # Google Translate (RPC + scrape)
+├── youtube.py        # yt-dlp wrapper with metadata
+├── ui.py             # Rich console helpers
+└── language_map.json # Language → voice mappings
+tests/
+├── test_models.py    # Dataclass tests
+├── test_googlev4.py  # Translation logic tests (no network)
+└── test_voice.py     # Voice lookup tests
+.github/workflows/
+└── ci.yml            # Ruff lint + pytest
 ```
 
 ---
 
-## Known issues & workarounds
-
-**FFmpeg not found**
-Add FFmpeg to your system PATH. Run `ffmpeg -version` to verify.
+## Known issues
 
-**CUDA out of memory**
-Switch to a smaller model: `--whisper_model tiny` or `--whisper_model base`. The pipeline auto-selects `base` on CPU and `small` on GPU if you don't specify.
+**FFmpeg not found** — add FFmpeg to PATH.
 
-**Translation splitting wrong**
-The batch translator joins segments with a delimiter and splits on it after. If the translated text collapses the delimiter, it falls back to translating each segment individually. Slower but accurate.
+**CUDA OOM** — use `--model tiny` or `--model base`.
 
-**YouTube rate-limited or auth errors**
-Close your browser fully before running with `--browser chrome`. If that still fails, export a `cookies.txt` file via a browser extension and pass it with `yt-dlp`'s `--cookies` option directly (you'd need to patch `youtube.py` for now — PRs welcome).
-
-**TTS file too small / silent audio**
-Usually a bad language code or a voice that's region-restricted. Double check your `language_map.json` entry and try the other gender.
+**YouTube auth errors** — close browser fully before `--browser chrome`.
 
 ---
 
 ## What we're working on
 
-- **Speaker diarization** — using `pyannote.audio` to detect multiple speakers and assign them distinct voices
-- **Background music separation** — `Demucs` integration to preserve BGM while replacing only the vocals
-- **Voice conversion (RVC)** — optional post-processing to match the original speaker's voice characteristics
-
-On the backlog:
-- Batch mode for playlists/channels
-- Local LLM translation (Llama 3 / Mistral) for offline/private use
-- Web UI via Gradio or Streamlit
-- Better lip-sync timing (stretch/compress TTS clips to fit original segment duration)
+- Speaker diarization (`pyannote.audio`)
+- Background music separation (Demucs)
+- Voice conversion (RVC) post-processing
+- Local LLM translation (offline)
+- Web UI (Gradio / Streamlit)
 
 ---
 
 ## Contributing
 
-Issues and PRs are open. If you're adding a new language to `language_map.json`, please include both a male and female voice where Edge TTS supports it.
-
 ```bash
-# Dev install
 pip install -e ".[dev]"
-
-# Run tests
 pytest tests/ -v
-
-# Lint
 ruff check .
 ```
 
+Issues and PRs welcome. Include both male and female voices when adding a language to `language_map.json`.
+
 ---
 
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
----
-
 *Built by Nguyen Cong Thuan Huy ([@mangodxd](https://github.com/mangodxd))*

tests/test_tts.py

@@ -0,0 +1,24 @@
+"""Tests for voice lookup functions (no network calls)."""
+
+import pytest
+
+from youtube_auto_dub.voice import pick_voice
+
+
+class TestPickVoice:
+    def test_returns_string(self):
+        voice = pick_voice("en", gender="female")
+        assert isinstance(voice, str)
+        assert len(voice) > 0
+
+    def test_male(self):
+        voice = pick_voice("en", gender="male")
+        assert isinstance(voice, str)
+
+    def test_fallback_gender(self):
+        voice = pick_voice("am", gender="male")
+        assert isinstance(voice, str)
+
+    def test_unknown_language(self):
+        with pytest.raises(ValueError, match="not found|not in map"):
+            pick_voice("zz", gender="female")

tests/test_voice.py

@@ -1,9 +1,3 @@
-"""YouTube Auto Dub — Automated Video Translation and Dubbing."""
+"""YouTube Auto Dub — translate, subtitle, and dub any video automatically."""
 
-__version__ = "1.0.0"
-__author__ = "Nguyen Cong Thuan Huy (mangodxd)"
-
-__all__ = [
-    "__version__",
-    "__author__",
-]
+__version__ = "2.0.0"