Refactor: package restructure with AIOS

- New package youtube_auto_dub/ with pyproject.toml and CLI entry point
- Split 546-line engines.py into transcriber, renderer, segmenter, config
- Split 182-line core_utils.py into exceptions, utils
- Moved main.py logic into pipeline.py; main.py is now a 6-line wrapper
- Moved language_map.json into package as package data
- Added 13 tests (models, googlev4, tts)
- Added CI pipeline (ruff + pytest on 3.10/3.11/3.12)
- Leftover root language_map.json cleaned up
- Updated latest_langmap_generate.py path

Author: mangodxd

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Lint with Ruff
+        run: ruff check youtube_auto_dub/
+
+  test:
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Test with pytest
+        run: python -m pytest tests/ -v

.gitignore

@@ -1,8 +1,22 @@
+# Python
 __pycache__/
-*.pyc
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.egg
+
+# Project runtime
 .cache/
 temp/
 output/
 *.mp4
 *.wav
-*.mp3
+*.mp3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo

README.md

@@ -1,5 +1,9 @@
 # youtube-auto-dub
 
+[![CI](https://github.com/mangodxd/youtube-auto-dub/actions/workflows/ci.yml/badge.svg)](https://github.com/mangodxd/youtube-auto-dub/actions/workflows/ci.yml)
+[![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.
@@ -26,7 +30,7 @@ YouTube URL → Download → Transcribe (Whisper) → Chunk → Translate → TT
 
 ### Prerequisites
 
-- Python 3.8+
+- Python 3.10+
 - FFmpeg in your PATH
 - (Optional) CUDA for faster Whisper inference
 
@@ -42,10 +46,16 @@ sudo apt install ffmpeg
 
 ### Install
 
+```bash
+pip install youtube-auto-dub
+```
+
+Or install from source:
+
 ```bash
 git clone https://github.com/mangodxd/youtube-auto-dub.git
 cd youtube-auto-dub
-pip install -r requirements.txt
+pip install .
 ```
 
 For GPU support:
@@ -59,19 +69,25 @@ pip install torch torchvision torchaudio --index-url https://download.pytorch.or
 
 ```bash
 # Dub + subtitles in Vietnamese (default)
+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
-python main.py "https://youtube.com/watch?v=VIDEO_ID" --mode sub --lang es
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --mode sub --lang es
 
 # Dubbing only, French, female voice
-python main.py "https://youtube.com/watch?v=VIDEO_ID" --mode dub --lang fr --gender female
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --mode dub --lang fr --gender female
 
 # Different languages for subs and dub
-python main.py "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" --mode both --lang_sub en --lang_dub vi
 
 # Age-restricted or private video — pull cookies from your browser
-python main.py "https://youtube.com/watch?v=VIDEO_ID" --lang es --browser chrome
+youtube-auto-dub "https://youtube.com/watch?v=VIDEO_ID" --lang es --browser chrome
 ```
 
 ### All options
@@ -91,7 +107,7 @@ python main.py "https://youtube.com/watch?v=VIDEO_ID" --lang es --browser chrome
 
 ## Language & voice config
 
-Voices are mapped in `language_map.json`. Edit it to change defaults or add new languages:
+Voices are mapped in `language_map.json` inside the package. Edit it to change defaults or add new languages:
 
 ```json
 {
@@ -113,20 +129,37 @@ Common codes: `es` · `fr` · `de` · `it` · `pt` · `ja` · `ko` · `zh` · `a
 
 ```
 youtube-auto-dub/
-├── main.py                 # Entry point, CLI, pipeline orchestration
-├── language_map.json       # Language → voice mappings
-├── requirements.txt
-└── src/
+├── 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 generation, audio mixing, FFmpeg render
+    ├── media.py            # Chunking, SRT, mixing, FFmpeg render
     ├── googlev4.py         # Google Translate (RPC + scrape fallback)
-    ├── tts.py              # Edge TTS synthesis
-    └── ui.py               # Rich console logger
-
-.cache/                     # Downloaded videos (persists between runs)
-output/                     # Final rendered videos
-temp/                       # Intermediate files (cleared each run)
+    ├── 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)
 ```
 
 ---
@@ -168,6 +201,17 @@ On the backlog:
 
 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 .
+```
+
 ---
 
 ## License
@@ -176,4 +220,4 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-*Built by Nguyen Cong Thuan Huy ([@mangodxd](https://github.com/mangodxd))*
+*Built by Nguyen Cong Thuan Huy ([@mangodxd](https://github.com/mangodxd))*

latest_langmap_generate.py

@@ -1,15 +1,16 @@
 import asyncio
 import json
-import edge_tts
 from pathlib import Path
-from typing import Dict, Any
+from typing import Any, Dict
+
+import edge_tts
 
 BASE_DIR = Path(__file__).resolve().parent
-LANG_MAP_FILE = BASE_DIR / "language_map.json"
+LANG_MAP_FILE = BASE_DIR / "youtube_auto_dub" / "language_map.json"
 
 async def generate_lang_map() -> None:
     print("[*] Connecting to Microsoft Edge TTS API...")
-    
+
     try:
         #fetch all available voices
         voices = await edge_tts.list_voices()
@@ -18,47 +19,47 @@ async def generate_lang_map() -> None:
         return
 
     print(f"[*] Processing {len(voices)} raw voice entries...")
-    
+
     # Structure: { "vi": { "name": "vi-VN", "voices": { "male": [], "female": [] } } }
     lang_map: Dict[str, Any] = {}
-    
+
     for v in voices:
         if "Neural" not in v["ShortName"]:
             continue
-            
+
         short_name = v["ShortName"]      # e.g., "vi-VN-NamMinhNeural"
         locale = v["Locale"]             # e.g., "vi-VN"
         gender = v["Gender"].lower()     # "male" or "female"
         lang_code = locale.split('-')[0] # ISO Language Code (e.g., 'vi' from 'vi-VN')
-        
+
         if lang_code not in lang_map:
             lang_map[lang_code] = {
-                "name": locale, 
+                "name": locale,
                 "voices": {"male": [], "female": []}
             }
-        
+
         if gender in lang_map[lang_code]["voices"]:
             lang_map[lang_code]["voices"][gender].append(short_name)
-        
-    
+
+
     final_map = {
-        k: v for k, v in lang_map.items() 
+        k: v for k, v in lang_map.items()
         if v["voices"]["male"] or v["voices"]["female"]
     }
 
     try:
         with open(LANG_MAP_FILE, "w", encoding="utf-8") as f:
             json.dump(final_map, f, ensure_ascii=False, indent=2)
-            
+
         print(f"\n[+] SUCCESS! Generated configuration for {len(final_map)} languages.")
         print(f"    File saved to -> {LANG_MAP_FILE}")
-        
+
         if "vi" in final_map:
             print("\n[*] Preview (Vietnamese):")
             print(json.dumps(final_map["vi"], indent=2))
-            
+
     except Exception as e:
         print(f"[!] ERROR: Failed to write JSON file: {e}")
 
 if __name__ == "__main__":
-    asyncio.run(generate_lang_map())
+    asyncio.run(generate_lang_map())