Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+# Install FFmpeg
+RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+RUN mkdir -p temp_jobs static
+
+EXPOSE 7860
+
+CMD ["python", "main.py"]

README.md

@@ -1,10 +1,25 @@
 ---
 title: Video Dubbing Agent
-emoji: 👀
-colorFrom: pink
-colorTo: indigo
+emoji: 🎬
+colorFrom: purple
+colorTo: green
 sdk: docker
-pinned: false
+app_port: 7860
+pinned: true
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Video Dubbing Agent
+
+AI-powered video dubbing system. Paste a YouTube URL, pick a language, and get the video dubbed with a male voice.
+
+- **Free GPU transcription** via HuggingFace Inference API (Whisper Large V3)
+- **20+ languages** including Hindi, Marathi, Spanish, French, Japanese, etc.
+- **Male voice only** (Edge TTS Neural voices)
+- **Subtitles** generated in both original and target language
+
+## How to use
+
+1. Paste a YouTube URL
+2. Select target language
+3. Click "Start Dubbing"
+4. Download the dubbed video when done

config.py

@@ -0,0 +1,78 @@
+"""
+Video Dubbing Agent — Configuration
+Deployed version with HuggingFace GPU transcription + male-only voices.
+"""
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).parent
+TEMP_DIR = BASE_DIR / "temp_jobs"
+STATIC_DIR = BASE_DIR / "static"
+TEMPLATES_DIR = BASE_DIR / "templates"
+TEMP_DIR.mkdir(exist_ok=True)
+
+# Server
+HOST = "0.0.0.0"
+PORT = int(os.getenv("PORT", 7860))  # HF Spaces uses 7860
+DEBUG = os.getenv("DEBUG", "false").lower() == "true"
+
+# YouTube
+YT_FORMAT = "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best"
+YT_MAX_DURATION = 4 * 3600
+
+# Audio
+AUDIO_SAMPLE_RATE = 16000
+AUDIO_CHANNELS = 1
+
+# === TRANSCRIPTION: HuggingFace Free GPU API ===
+# This uses HF's free Inference API with GPU — no local model needed!
+HF_API_URL = "https://api-inference.huggingface.co/models/openai/whisper-large-v3"
+HF_TOKEN = os.getenv("HF_TOKEN", "")  # Optional: set for higher rate limits
+# Fallback to local faster-whisper if HF API fails
+WHISPER_MODEL_SIZE = os.getenv("WHISPER_MODEL", "tiny")
+WHISPER_COMPUTE_TYPE = "int8"
+
+# === VOICE: MALE ONLY ===
+# Force all speakers to use MALE voice regardless of detected gender
+FORCE_MALE_VOICE = True
+
+# Edge TTS Voice Map — MALE voices only
+EDGE_TTS_VOICES = {
+    "mr": {"male": "mr-IN-ManoharNeural", "female": "mr-IN-ManoharNeural"},
+    "hi": {"male": "hi-IN-MadhurNeural", "female": "hi-IN-MadhurNeural"},
+    "en": {"male": "en-US-GuyNeural", "female": "en-US-GuyNeural"},
+    "es": {"male": "es-ES-AlvaroNeural", "female": "es-ES-AlvaroNeural"},
+    "fr": {"male": "fr-FR-HenriNeural", "female": "fr-FR-HenriNeural"},
+    "de": {"male": "de-DE-ConradNeural", "female": "de-DE-ConradNeural"},
+    "ja": {"male": "ja-JP-KeitaNeural", "female": "ja-JP-KeitaNeural"},
+    "zh": {"male": "zh-CN-YunxiNeural", "female": "zh-CN-YunxiNeural"},
+    "pt": {"male": "pt-BR-AntonioNeural", "female": "pt-BR-AntonioNeural"},
+    "ar": {"male": "ar-SA-HamedNeural", "female": "ar-SA-HamedNeural"},
+    "ko": {"male": "ko-KR-InJoonNeural", "female": "ko-KR-InJoonNeural"},
+    "ru": {"male": "ru-RU-DmitryNeural", "female": "ru-RU-DmitryNeural"},
+    "it": {"male": "it-IT-DiegoNeural", "female": "it-IT-DiegoNeural"},
+    "ta": {"male": "ta-IN-ValluvarNeural", "female": "ta-IN-ValluvarNeural"},
+    "te": {"male": "te-IN-MohanNeural", "female": "te-IN-MohanNeural"},
+    "bn": {"male": "bn-IN-BashkarNeural", "female": "bn-IN-BashkarNeural"},
+    "gu": {"male": "gu-IN-NiranjanNeural", "female": "gu-IN-NiranjanNeural"},
+    "kn": {"male": "kn-IN-GaganNeural", "female": "kn-IN-GaganNeural"},
+    "ml": {"male": "ml-IN-MidhunNeural", "female": "ml-IN-MidhunNeural"},
+    "ur": {"male": "ur-PK-AsadNeural", "female": "ur-PK-AsadNeural"},
+}
+
+TTS_MAX_SPEED_FACTOR = 1.3
+TTS_CROSSFADE_MS = 50
+BACKGROUND_VOLUME = 0.15
+JOB_EXPIRY_HOURS = 12
+MAX_CONCURRENT_JOBS = 2
+
+# Audio chunk size for HF API (30 seconds per chunk)
+HF_CHUNK_DURATION_SEC = 30
+
+SUPPORTED_LANGUAGES = {
+    "mr": "Marathi", "hi": "Hindi", "en": "English", "es": "Spanish",
+    "fr": "French", "de": "German", "ja": "Japanese", "zh": "Chinese",
+    "pt": "Portuguese", "ar": "Arabic", "ko": "Korean", "ru": "Russian",
+    "it": "Italian", "ta": "Tamil", "te": "Telugu", "bn": "Bengali",
+    "gu": "Gujarati", "kn": "Kannada", "ml": "Malayalam", "ur": "Urdu",
+}

jobs/pipeline.py

@@ -0,0 +1,344 @@
+"""
+Pipeline Orchestrator
+Runs all 9+ stages sequentially for a dubbing job.
+Supports stage-level resumability and detailed progress tracking.
+"""
+
+import logging
+import json
+import traceback
+from pathlib import Path
+from typing import Optional
+
+from jobs.progress_tracker import tracker
+from services.downloader import download_video, get_video_info, use_local_file
+from services.audio_extractor import extract_audio_for_stt, extract_audio_stereo, get_video_duration
+from services.vocal_separator import separate_vocals
+from services.transcriber import transcribe_audio
+from services.speaker_profiler import profile_speakers
+from services.translator import translate_segments
+from services.tts_generator import generate_dubbed_audio
+from services.audio_assembler import assemble_dubbed_audio
+from services.audio_mixer import mix_audio
+from services.merger import merge_video_audio
+from services.subtitle_generator import generate_subtitles
+
+logger = logging.getLogger(__name__)
+
+
+def run_dubbing_pipeline(
+    job_id: str,
+    job_dir: Path,
+    youtube_url: Optional[str] = None,
+    local_file: Optional[str] = None,
+    target_language: str = "mr",
+    source_language: Optional[str] = None,
+    preserve_background: bool = True,
+    generate_subs: bool = True,
+):
+    """
+    Run the complete dubbing pipeline.
+    This runs as a background task.
+    """
+    try:
+        logger.info(f"=== Pipeline started: job={job_id}, target={target_language} ===")
+
+        # Checkpoint file for resumability
+        checkpoint_path = job_dir / "checkpoint.json"
+        checkpoint = _load_checkpoint(checkpoint_path)
+
+        # ============================================================
+        # STAGE 1: Download video
+        # ============================================================
+        if checkpoint.get("stage", 0) < 1:
+            tracker.update_stage(job_id, "downloading")
+            logger.info("STAGE 1: Downloading video...")
+
+            if youtube_url:
+                video_info = get_video_info(youtube_url)
+                tracker.get_job(job_id).video_title = video_info["title"]
+
+                def dl_progress(pct):
+                    tracker.update_progress(job_id, int(pct))
+
+                video_path = download_video(youtube_url, job_dir, progress_callback=dl_progress)
+            elif local_file:
+                video_path = use_local_file(local_file, job_dir)
+                video_info = {"title": Path(local_file).stem, "duration": 0}
+                tracker.get_job(job_id).video_title = video_info["title"]
+            else:
+                raise ValueError("No youtube_url or local_file provided.")
+
+            _save_checkpoint(checkpoint_path, 1, {"video_path": str(video_path), "video_info": video_info})
+        else:
+            cp = checkpoint["data"]
+            video_path = Path(cp["video_path"])
+            video_info = cp.get("video_info", {})
+            logger.info("STAGE 1: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 2: Extract audio
+        # ============================================================
+        if checkpoint.get("stage", 0) < 2:
+            tracker.update_stage(job_id, "extracting_audio")
+            logger.info("STAGE 2: Extracting audio...")
+
+            stt_audio = extract_audio_for_stt(video_path, job_dir)
+            stereo_audio = extract_audio_stereo(video_path, job_dir)
+            total_duration = get_video_duration(video_path)
+
+            _save_checkpoint(checkpoint_path, 2, {
+                "stt_audio": str(stt_audio),
+                "stereo_audio": str(stereo_audio),
+                "total_duration": total_duration,
+            })
+        else:
+            cp = checkpoint["data"]
+            stt_audio = Path(cp["stt_audio"])
+            stereo_audio = Path(cp["stereo_audio"])
+            total_duration = cp["total_duration"]
+            logger.info("STAGE 2: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 3: Vocal separation
+        # ============================================================
+        if checkpoint.get("stage", 0) < 3:
+            tracker.update_stage(job_id, "separating_vocals")
+            logger.info("STAGE 3: Separating vocals from background...")
+
+            if preserve_background:
+                separation = separate_vocals(stt_audio, job_dir)
+            else:
+                separation = {"vocals": stt_audio, "background": None, "separated": False}
+
+            _save_checkpoint(checkpoint_path, 3, {
+                "vocals_path": str(separation["vocals"]),
+                "background_path": str(separation["background"]) if separation["background"] else None,
+                "separated": separation["separated"],
+            })
+        else:
+            cp = checkpoint["data"]
+            separation = {
+                "vocals": Path(cp["vocals_path"]),
+                "background": Path(cp["background_path"]) if cp["background_path"] else None,
+                "separated": cp["separated"],
+            }
+            logger.info("STAGE 3: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 4: Transcribe + Diarize
+        # ============================================================
+        if checkpoint.get("stage", 0) < 4:
+            tracker.update_stage(job_id, "transcribing")
+            logger.info("STAGE 4: Transcribing with WhisperX...")
+
+            def transcribe_progress(pct):
+                tracker.update_progress(job_id, pct)
+
+            segments = transcribe_audio(
+                audio_path=separation["vocals"],
+                output_dir=job_dir,
+                source_language=source_language,
+                progress_callback=transcribe_progress,
+            )
+
+            # Load detected language from transcript
+            transcript_data = json.loads((job_dir / "transcript.json").read_text())
+            detected_language = transcript_data.get("language", source_language or "en")
+
+            _save_checkpoint(checkpoint_path, 4, {
+                "detected_language": detected_language,
+            })
+        else:
+            transcript_data = json.loads((job_dir / "transcript.json").read_text())
+            segments = transcript_data["segments"]
+            detected_language = checkpoint["data"].get("detected_language", "en")
+            logger.info("STAGE 4: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 5: Speaker profiling + gender detection
+        # ============================================================
+        if checkpoint.get("stage", 0) < 5:
+            tracker.update_stage(job_id, "profiling_speakers")
+            logger.info("STAGE 5: Profiling speakers & detecting gender...")
+
+            speaker_profiles = profile_speakers(
+                segments=segments,
+                audio_path=separation["vocals"],
+                output_dir=job_dir,
+            )
+
+            # Save profiles (convert Path to str for JSON)
+            profiles_serializable = {}
+            for spk, prof in speaker_profiles.items():
+                ref = prof.get("reference_audio")
+                profiles_serializable[spk] = {
+                    **prof,
+                    "reference_audio": str(ref) if ref else None,
+                }
+
+            _save_checkpoint(checkpoint_path, 5, {
+                "speaker_profiles": profiles_serializable,
+            })
+        else:
+            profiles_serializable = checkpoint["data"]["speaker_profiles"]
+            speaker_profiles = {}
+            for spk, prof in profiles_serializable.items():
+                ref = prof.get("reference_audio")
+                speaker_profiles[spk] = {
+                    **prof,
+                    "reference_audio": Path(ref) if ref else None,
+                }
+            logger.info("STAGE 5: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 6: Translation
+        # ============================================================
+        if checkpoint.get("stage", 0) < 6:
+            tracker.update_stage(job_id, "translating")
+            logger.info(f"STAGE 6: Translating {detected_language} → {target_language}...")
+
+            def translate_progress(pct):
+                tracker.update_progress(job_id, pct)
+
+            translated = translate_segments(
+                segments=segments,
+                source_language=detected_language,
+                target_language=target_language,
+                output_dir=job_dir,
+                progress_callback=translate_progress,
+            )
+
+            _save_checkpoint(checkpoint_path, 6, {})
+        else:
+            translated_data = json.loads((job_dir / "translated_segments.json").read_text())
+            translated = translated_data["segments"]
+            logger.info("STAGE 6: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 7: TTS Generation (gender-matched)
+        # ============================================================
+        if checkpoint.get("stage", 0) < 7:
+            tracker.update_stage(job_id, "generating_tts")
+            logger.info("STAGE 7: Generating gender-matched TTS audio...")
+
+            def tts_progress(pct):
+                tracker.update_progress(job_id, pct)
+
+            tts_segments = generate_dubbed_audio(
+                translated_segments=translated,
+                speaker_profiles=speaker_profiles,
+                target_language=target_language,
+                output_dir=job_dir,
+                progress_callback=tts_progress,
+            )
+
+            _save_checkpoint(checkpoint_path, 7, {})
+        else:
+            tts_segments = translated  # Will have tts_audio_path from previous run
+            logger.info("STAGE 7: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 8: Audio Assembly
+        # ============================================================
+        if checkpoint.get("stage", 0) < 8:
+            tracker.update_stage(job_id, "assembling_audio")
+            logger.info("STAGE 8: Assembling dubbed audio track...")
+
+            def assemble_progress(pct):
+                tracker.update_progress(job_id, pct)
+
+            dubbed_audio = assemble_dubbed_audio(
+                segments=tts_segments,
+                total_duration=total_duration,
+                output_dir=job_dir,
+                progress_callback=assemble_progress,
+            )
+
+            _save_checkpoint(checkpoint_path, 8, {"dubbed_audio": str(dubbed_audio)})
+        else:
+            dubbed_audio = Path(checkpoint["data"]["dubbed_audio"])
+            logger.info("STAGE 8: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 9: Background Audio Mixing
+        # ============================================================
+        if checkpoint.get("stage", 0) < 9:
+            tracker.update_stage(job_id, "mixing_audio")
+            logger.info("STAGE 9: Mixing dubbed audio with background...")
+
+            final_audio = mix_audio(
+                dubbed_audio_path=dubbed_audio,
+                background_audio_path=separation.get("background"),
+                output_dir=job_dir,
+            )
+
+            _save_checkpoint(checkpoint_path, 9, {"final_audio": str(final_audio)})
+        else:
+            final_audio = Path(checkpoint["data"]["final_audio"])
+            logger.info("STAGE 9: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 10: Final Video Merge
+        # ============================================================
+        if checkpoint.get("stage", 0) < 10:
+            tracker.update_stage(job_id, "merging_video")
+            logger.info("STAGE 10: Merging dubbed audio into video...")
+
+            final_video = merge_video_audio(
+                video_path=video_path,
+                audio_path=final_audio,
+                output_dir=job_dir,
+                video_title=video_info.get("title", "dubbed_video"),
+            )
+
+            _save_checkpoint(checkpoint_path, 10, {"final_video": str(final_video)})
+        else:
+            final_video = Path(checkpoint["data"]["final_video"])
+            logger.info("STAGE 10: Skipped (checkpoint)")
+
+        # ============================================================
+        # STAGE 11: Subtitles (bonus)
+        # ============================================================
+        subtitle_paths = {}
+        if generate_subs:
+            tracker.update_stage(job_id, "generating_subtitles")
+            logger.info("STAGE 11: Generating subtitles...")
+
+            srt_paths = generate_subtitles(
+                segments=tts_segments,
+                output_dir=job_dir,
+                source_language=detected_language,
+                target_language=target_language,
+            )
+            subtitle_paths = {k: str(v) for k, v in srt_paths.items()}
+
+        # ============================================================
+        # DONE
+        # ============================================================
+        tracker.complete_job(job_id, str(final_video), subtitle_paths)
+        logger.info(f"=== Pipeline complete: {final_video} ===")
+
+    except Exception as e:
+        error_msg = f"{type(e).__name__}: {str(e)}"
+        logger.error(f"Pipeline failed for job {job_id}: {error_msg}")
+        logger.error(traceback.format_exc())
+        tracker.fail_job(job_id, error_msg)
+
+
+def _load_checkpoint(path: Path) -> dict:
+    """Load checkpoint for resumability."""
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except json.JSONDecodeError:
+            return {"stage": 0, "data": {}}
+    return {"stage": 0, "data": {}}
+
+
+def _save_checkpoint(path: Path, stage: int, data: dict):
+    """Save checkpoint after completing a stage."""
+    existing = _load_checkpoint(path)
+    existing["stage"] = stage
+    existing["data"].update(data)
+    path.write_text(json.dumps(existing, indent=2))

jobs/progress_tracker.py

@@ -0,0 +1,154 @@
+"""
+Job Progress Tracker
+Manages per-job state, progress, and stage tracking.
+Thread-safe for background task usage.
+"""
+
+import time
+import threading
+import json
+from pathlib import Path
+from typing import Optional, Dict
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+STAGE_NAMES = [
+    "downloading",
+    "extracting_audio",
+    "separating_vocals",
+    "transcribing",
+    "profiling_speakers",
+    "translating",
+    "generating_tts",
+    "assembling_audio",
+    "mixing_audio",
+    "merging_video",
+    "generating_subtitles",
+]
+
+
+@dataclass
+class JobState:
+    job_id: str
+    status: JobStatus = JobStatus.QUEUED
+    current_stage: str = ""
+    stage_number: int = 0
+    total_stages: int = len(STAGE_NAMES)
+    progress_percent: int = 0
+    elapsed_time: float = 0
+    estimated_remaining: str = "calculating..."
+    start_time: float = 0
+    error_message: str = ""
+    video_title: str = ""
+    target_language: str = ""
+    output_path: str = ""
+    subtitle_paths: Dict = field(default_factory=dict)
+
+    def to_dict(self):
+        d = asdict(self)
+        d["status"] = self.status.value
+        d["elapsed_time_str"] = _format_time(self.elapsed_time)
+        return d
+
+
+def _format_time(seconds: float) -> str:
+    if seconds < 60:
+        return f"{int(seconds)}s"
+    elif seconds < 3600:
+        return f"{int(seconds // 60)}m {int(seconds % 60)}s"
+    else:
+        h = int(seconds // 3600)
+        m = int((seconds % 3600) // 60)
+        return f"{h}h {m}m"
+
+
+class ProgressTracker:
+    """Thread-safe job progress tracker."""
+
+    def __init__(self):
+        self._jobs: Dict[str, JobState] = {}
+        self._lock = threading.Lock()
+
+    def create_job(self, job_id: str, target_language: str = "") -> JobState:
+        with self._lock:
+            state = JobState(
+                job_id=job_id,
+                target_language=target_language,
+                start_time=time.time()
+            )
+            self._jobs[job_id] = state
+            return state
+
+    def get_job(self, job_id: str) -> Optional[JobState]:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def update_stage(self, job_id: str, stage_name: str):
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if not job:
+                return
+            job.status = JobStatus.PROCESSING
+            job.current_stage = stage_name
+            if stage_name in STAGE_NAMES:
+                job.stage_number = STAGE_NAMES.index(stage_name) + 1
+            job.elapsed_time = time.time() - job.start_time
+            # Estimate remaining
+            if job.stage_number > 0:
+                per_stage = job.elapsed_time / job.stage_number
+                remaining_stages = job.total_stages - job.stage_number
+                est = per_stage * remaining_stages
+                job.estimated_remaining = f"~{_format_time(est)}"
+            job.progress_percent = int(job.stage_number / job.total_stages * 100)
+
+    def update_progress(self, job_id: str, percent: int):
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job:
+                # Blend stage progress into overall progress
+                base = (job.stage_number - 1) / job.total_stages * 100
+                stage_contrib = percent / job.total_stages
+                job.progress_percent = min(int(base + stage_contrib), 99)
+                job.elapsed_time = time.time() - job.start_time
+
+    def complete_job(self, job_id: str, output_path: str, subtitle_paths: dict = None):
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job:
+                job.status = JobStatus.COMPLETED
+                job.progress_percent = 100
+                job.current_stage = "done"
+                job.output_path = output_path
+                job.subtitle_paths = subtitle_paths or {}
+                job.elapsed_time = time.time() - job.start_time
+                job.estimated_remaining = "0s"
+
+    def fail_job(self, job_id: str, error: str):
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job:
+                job.status = JobStatus.FAILED
+                job.error_message = error
+                job.elapsed_time = time.time() - job.start_time
+                job.estimated_remaining = ""
+
+    def list_jobs(self) -> list:
+        with self._lock:
+            return [j.to_dict() for j in self._jobs.values()]
+
+    def remove_job(self, job_id: str):
+        with self._lock:
+            self._jobs.pop(job_id, None)
+
+
+# Global singleton
+tracker = ProgressTracker()

main.py

@@ -0,0 +1,74 @@
+"""
+Video Dubbing Agent — Deployed Version
+Run: python main.py
+Access: http://localhost:7860
+"""
+import logging
+import sys
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from fastapi.middleware.cors import CORSMiddleware
+
+from config import HOST, PORT, DEBUG, STATIC_DIR, TEMPLATES_DIR
+from routes.dub import router as dub_router
+from routes.info import router as info_router
+from utils.file_manager import cleanup_expired_jobs
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Video Dubbing Agent starting...")
+    cleanup_expired_jobs()
+    logger.info(f"Ready at http://localhost:{PORT}")
+    yield
+    logger.info("Shutting down.")
+
+
+app = FastAPI(
+    title="Video Dubbing Agent",
+    description="AI video dubbing: YouTube → any language. Male voice. Free GPU transcription.",
+    version="2.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+STATIC_DIR.mkdir(exist_ok=True)
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+app.include_router(dub_router, prefix="/api", tags=["Dubbing"])
+app.include_router(info_router, prefix="/api", tags=["Info"])
+
+
+@app.get("/")
+async def serve_frontend():
+    index_path = TEMPLATES_DIR / "index.html"
+    if index_path.exists():
+        return FileResponse(str(index_path))
+    return {"message": "Video Dubbing Agent API. Visit /docs for API docs."}
+
+
+@app.get("/health")
+async def health():
+    return {"status": "healthy", "service": "video-dubbing-agent", "version": "2.0"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host=HOST, port=PORT, reload=False)

requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+pydantic==2.5.0
+yt-dlp>=2024.1.5
+deep-translator==1.11.4
+edge-tts>=6.1.9
+pydub==0.25.1
+faster-whisper==0.10.0
+requests>=2.31.0

routes/dub.py

@@ -0,0 +1,181 @@
+"""
+API Routes — Dubbing Endpoints
+POST /dub, GET /status, GET /download, DELETE /job
+"""
+
+import logging
+import threading
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, HttpUrl
+
+from jobs.progress_tracker import tracker
+from jobs.pipeline import run_dubbing_pipeline
+from utils.file_manager import create_job_directory, cleanup_job, get_job_disk_usage
+from config import SUPPORTED_LANGUAGES
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+# === Request/Response Models ===
+
+class DubRequest(BaseModel):
+    youtube_url: Optional[str] = None
+    local_file: Optional[str] = None
+    target_language: str = "mr"
+    source_language: Optional[str] = None  # Auto-detect if None
+    preserve_background: bool = True
+    generate_subtitles: bool = True
+
+
+class DubResponse(BaseModel):
+    job_id: str
+    status: str
+    message: str
+
+
+class StatusResponse(BaseModel):
+    job_id: str
+    status: str
+    current_stage: str
+    stage_number: int
+    total_stages: int
+    progress_percent: int
+    elapsed_time: str
+    estimated_remaining: str
+    video_title: str
+    target_language: str
+    error_message: str = ""
+
+
+# === Endpoints ===
+
+@router.post("/dub", response_model=DubResponse)
+async def start_dubbing(request: DubRequest):
+    """
+    Start a new dubbing job.
+    Provide either youtube_url or local_file path.
+    """
+    # Validate input
+    if not request.youtube_url and not request.local_file:
+        raise HTTPException(400, "Provide either 'youtube_url' or 'local_file'.")
+
+    if request.target_language not in SUPPORTED_LANGUAGES:
+        raise HTTPException(
+            400,
+            f"Unsupported language: '{request.target_language}'. "
+            f"Supported: {list(SUPPORTED_LANGUAGES.keys())}"
+        )
+
+    # Create job
+    job_id, job_dir = create_job_directory()
+    tracker.create_job(job_id, target_language=request.target_language)
+
+    # Run pipeline in background thread
+    thread = threading.Thread(
+        target=run_dubbing_pipeline,
+        kwargs={
+            "job_id": job_id,
+            "job_dir": job_dir,
+            "youtube_url": request.youtube_url,
+            "local_file": request.local_file,
+            "target_language": request.target_language,
+            "source_language": request.source_language,
+            "preserve_background": request.preserve_background,
+            "generate_subs": request.generate_subtitles,
+        },
+        daemon=True,
+    )
+    thread.start()
+
+    lang_name = SUPPORTED_LANGUAGES.get(request.target_language, request.target_language)
+
+    return DubResponse(
+        job_id=job_id,
+        status="queued",
+        message=f"Dubbing job started → {lang_name}. Track progress at /status/{job_id}"
+    )
+
+
+@router.get("/status/{job_id}")
+async def get_status(job_id: str):
+    """Get the current status and progress of a dubbing job."""
+    job = tracker.get_job(job_id)
+    if not job:
+        raise HTTPException(404, f"Job not found: {job_id}")
+
+    data = job.to_dict()
+    data["disk_usage"] = get_job_disk_usage(job_id)
+    return data
+
+
+@router.get("/download/{job_id}")
+async def download_video(job_id: str):
+    """Download the final dubbed video."""
+    job = tracker.get_job(job_id)
+    if not job:
+        raise HTTPException(404, f"Job not found: {job_id}")
+
+    if job.status.value != "completed":
+        raise HTTPException(400, f"Job is not complete. Status: {job.status.value}")
+
+    video_path = Path(job.output_path)
+    if not video_path.exists():
+        raise HTTPException(404, "Output video file not found.")
+
+    return FileResponse(
+        path=str(video_path),
+        media_type="video/mp4",
+        filename=video_path.name,
+    )
+
+
+@router.get("/download/{job_id}/subtitles/{lang_type}")
+async def download_subtitles(job_id: str, lang_type: str):
+    """
+    Download subtitle file.
+    lang_type: 'original' or 'translated'
+    """
+    job = tracker.get_job(job_id)
+    if not job:
+        raise HTTPException(404, f"Job not found: {job_id}")
+
+    if job.status.value != "completed":
+        raise HTTPException(400, "Job not complete.")
+
+    srt_path_str = job.subtitle_paths.get(lang_type)
+    if not srt_path_str:
+        raise HTTPException(404, f"No '{lang_type}' subtitle file available.")
+
+    srt_path = Path(srt_path_str)
+    if not srt_path.exists():
+        raise HTTPException(404, "Subtitle file not found on disk.")
+
+    return FileResponse(
+        path=str(srt_path),
+        media_type="application/x-subrip",
+        filename=srt_path.name,
+    )
+
+
+@router.delete("/job/{job_id}")
+async def delete_job(job_id: str):
+    """Delete a job and clean up all its temp files."""
+    job = tracker.get_job(job_id)
+    if not job:
+        raise HTTPException(404, f"Job not found: {job_id}")
+
+    cleanup_job(job_id)
+    tracker.remove_job(job_id)
+
+    return {"message": f"Job {job_id} deleted.", "status": "deleted"}
+
+
+@router.get("/jobs")
+async def list_jobs():
+    """List all jobs with their current status."""
+    return {"jobs": tracker.list_jobs()}

routes/info.py

@@ -0,0 +1,36 @@
+"""
+API Routes — Info Endpoints
+GET /languages, GET /system-info
+"""
+
+from fastapi import APIRouter
+from config import SUPPORTED_LANGUAGES, EDGE_TTS_VOICES
+from utils.gpu_detector import detect_gpu, get_system_report
+
+router = APIRouter()
+
+
+@router.get("/languages")
+async def get_languages():
+    """List all supported target languages with their voice details."""
+    languages = []
+    for code, name in SUPPORTED_LANGUAGES.items():
+        voices = EDGE_TTS_VOICES.get(code, {})
+        languages.append({
+            "code": code,
+            "name": name,
+            "male_voice": voices.get("male", "N/A"),
+            "female_voice": voices.get("female", "N/A"),
+        })
+    return {"languages": languages, "total": len(languages)}
+
+
+@router.get("/system-info")
+async def get_system_info():
+    """Get system readiness report (GPU, estimated times)."""
+    gpu = detect_gpu()
+    report = get_system_report()
+    return {
+        "gpu": gpu,
+        "report": report,
+    }

services/audio_assembler.py

@@ -0,0 +1,165 @@
+"""
+Stage 7 — Audio Assembly
+Stitches all TTS segments into a single continuous dubbed audio track.
+Places each segment at the correct timestamp with silence padding.
+"""
+
+import logging
+import subprocess
+import json
+from pathlib import Path
+from typing import List, Dict
+
+from config import TTS_CROSSFADE_MS
+
+logger = logging.getLogger(__name__)
+
+
+def assemble_dubbed_audio(
+    segments: List[Dict],
+    total_duration: float,
+    output_dir: Path,
+    progress_callback=None
+) -> Path:
+    """
+    Create a full-length audio track by placing each TTS segment
+    at its original timestamp position.
+
+    Returns path to the assembled dubbed audio file.
+    """
+    output_path = output_dir / "dubbed_audio_full.wav"
+
+    # Filter segments that have TTS audio
+    valid_segments = [
+        s for s in segments
+        if s.get("tts_audio_path") and Path(s["tts_audio_path"]).exists()
+    ]
+
+    if not valid_segments:
+        raise RuntimeError("No valid TTS segments to assemble.")
+
+    logger.info(f"Assembling {len(valid_segments)} segments into {total_duration:.1f}s track")
+
+    # Use ffmpeg filter_complex to place segments at correct timestamps
+    # This is more reliable than pydub for long audio
+    filter_parts = []
+    inputs = []
+
+    # First input: silence for the full duration
+    inputs.extend([
+        "-f", "lavfi",
+        "-t", str(total_duration),
+        "-i", f"anullsrc=r=24000:cl=mono"
+    ])
+
+    # Add each TTS segment as an input
+    for idx, seg in enumerate(valid_segments):
+        inputs.extend(["-i", seg["tts_audio_path"]])
+
+    # Build filter: overlay each segment at its start time
+    # [0] is the silence base, [1], [2], etc. are the TTS segments
+    n_segs = len(valid_segments)
+
+    if n_segs == 0:
+        raise RuntimeError("No segments to assemble.")
+
+    # For large numbers of segments, build the filter in stages
+    # to avoid ffmpeg filter complexity limits
+    if n_segs > 100:
+        return _assemble_chunked(valid_segments, total_duration, output_dir, output_path, progress_callback)
+
+    # Build adelay filter chain
+    filter_parts = []
+    mix_inputs = ["[base]"]
+
+    # The silence base
+    filter_parts.append("[0]aresample=24000[base]")
+
+    for idx, seg in enumerate(valid_segments):
+        input_idx = idx + 1  # +1 because [0] is silence
+        delay_ms = int(seg["start"] * 1000)
+        # Resample to 24kHz, apply delay
+        filter_parts.append(
+            f"[{input_idx}]aresample=24000,adelay={delay_ms}|{delay_ms}[s{idx}]"
+        )
+        mix_inputs.append(f"[s{idx}]")
+
+    # Mix all together
+    all_inputs = "".join(mix_inputs)
+    filter_parts.append(
+        f"{all_inputs}amix=inputs={n_segs + 1}:duration=longest:dropout_transition=0[out]"
+    )
+
+    filter_complex = ";".join(filter_parts)
+
+    cmd = [
+        "ffmpeg", "-y",
+        *inputs,
+        "-filter_complex", filter_complex,
+        "-map", "[out]",
+        "-acodec", "pcm_s16le",
+        "-ar", "24000",
+        "-ac", "1",
+        str(output_path)
+    ]
+
+    logger.info("Running ffmpeg audio assembly...")
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+    if result.returncode != 0:
+        logger.warning(f"FFmpeg filter_complex failed. Trying chunked assembly. Error: {result.stderr[:500]}")
+        return _assemble_chunked(valid_segments, total_duration, output_dir, output_path, progress_callback)
+
+    logger.info(f"Audio assembly complete: {output_path}")
+
+    if progress_callback:
+        progress_callback(100)
+
+    return output_path
+
+
+def _assemble_chunked(
+    segments: List[Dict],
+    total_duration: float,
+    output_dir: Path,
+    output_path: Path,
+    progress_callback=None
+) -> Path:
+    """
+    Fallback: assemble audio using pydub for better memory management.
+    Processes in chunks for very long videos.
+    """
+    try:
+        from pydub import AudioSegment
+    except ImportError:
+        raise RuntimeError("pydub not installed. Run: pip install pydub")
+
+    logger.info("Using pydub chunked assembly (fallback)...")
+
+    # Create silent base track
+    total_ms = int(total_duration * 1000)
+    base = AudioSegment.silent(duration=total_ms, frame_rate=24000)
+
+    total_segs = len(segments)
+    for idx, seg in enumerate(segments):
+        try:
+            tts_audio = AudioSegment.from_file(seg["tts_audio_path"])
+            # Resample to 24kHz mono
+            tts_audio = tts_audio.set_frame_rate(24000).set_channels(1)
+
+            position_ms = int(seg["start"] * 1000)
+
+            # Overlay at the correct position
+            base = base.overlay(tts_audio, position=position_ms)
+
+        except Exception as e:
+            logger.warning(f"Failed to overlay segment {idx}: {e}")
+            continue
+
+        if progress_callback and idx % 50 == 0:
+            progress_callback(int((idx + 1) / total_segs * 100))
+
+    # Export
+    base.export(str(output_path), format="wav")
+    logger.info(f"Chunked assembly complete: {output_path}")
+    return output_path

services/audio_extractor.py

@@ -0,0 +1,82 @@
+"""
+Stage 2 — Audio Extraction & Preprocessing
+Extracts audio from video, creates STT-ready WAV and stereo backup.
+"""
+
+import logging
+import subprocess
+from pathlib import Path
+from config import AUDIO_SAMPLE_RATE, AUDIO_CHANNELS
+
+logger = logging.getLogger(__name__)
+
+
+def extract_audio_for_stt(video_path: Path, output_dir: Path) -> Path:
+    """
+    Extract audio from video as 16kHz mono WAV for speech-to-text.
+    """
+    output_path = output_dir / "audio_stt.wav"
+
+    cmd = [
+        "ffmpeg", "-y",
+        "-i", str(video_path),
+        "-vn",                          # No video
+        "-acodec", "pcm_s16le",        # 16-bit PCM
+        "-ar", str(AUDIO_SAMPLE_RATE),  # 16kHz
+        "-ac", str(AUDIO_CHANNELS),     # Mono
+        str(output_path)
+    ]
+
+    logger.info("Extracting audio for STT (16kHz mono WAV)...")
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"FFmpeg audio extraction failed: {result.stderr}")
+
+    logger.info(f"STT audio: {output_path} ({output_path.stat().st_size / 1e6:.1f} MB)")
+    return output_path
+
+
+def extract_audio_stereo(video_path: Path, output_dir: Path) -> Path:
+    """
+    Extract original stereo audio (for background mixing later).
+    """
+    output_path = output_dir / "audio_original_stereo.wav"
+
+    cmd = [
+        "ffmpeg", "-y",
+        "-i", str(video_path),
+        "-vn",
+        "-acodec", "pcm_s16le",
+        "-ar", "44100",
+        str(output_path)
+    ]
+
+    logger.info("Extracting stereo audio for background mixing...")
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"FFmpeg stereo extraction failed: {result.stderr}")
+
+    logger.info(f"Stereo audio: {output_path}")
+    return output_path
+
+
+def get_audio_duration(audio_path: Path) -> float:
+    """Get audio duration in seconds using ffprobe."""
+    cmd = [
+        "ffprobe",
+        "-v", "quiet",
+        "-show_entries", "format=duration",
+        "-of", "csv=p=0",
+        str(audio_path)
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    if result.returncode != 0:
+        raise RuntimeError(f"ffprobe failed: {result.stderr}")
+    return float(result.stdout.strip())
+
+
+def get_video_duration(video_path: Path) -> float:
+    """Get video duration in seconds."""
+    return get_audio_duration(video_path)  # ffprobe works on video too

services/audio_mixer.py

@@ -0,0 +1,96 @@
+"""
+Stage 8 — Background Audio Mixing
+Mixes the dubbed vocal track with the original background music/ambience.
+Creates a natural-sounding output that preserves the video's atmosphere.
+"""
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from config import BACKGROUND_VOLUME
+
+logger = logging.getLogger(__name__)
+
+
+def mix_audio(
+    dubbed_audio_path: Path,
+    background_audio_path: Optional[Path],
+    output_dir: Path,
+    background_volume: float = BACKGROUND_VOLUME,
+    progress_callback=None
+) -> Path:
+    """
+    Mix dubbed vocal track with original background audio.
+    If no background audio, just return the dubbed audio.
+
+    Args:
+        dubbed_audio_path: Full dubbed vocal track from assembly
+        background_audio_path: Background track from demucs (or None)
+        output_dir: Working directory
+        background_volume: Volume level for background (0.0 - 1.0)
+
+    Returns: Path to mixed audio file
+    """
+    output_path = output_dir / "final_audio_mixed.wav"
+
+    if background_audio_path is None or not background_audio_path.exists():
+        logger.info("No background audio available. Using dubbed audio as-is.")
+        # Just copy/convert the dubbed audio
+        cmd = [
+            "ffmpeg", "-y",
+            "-i", str(dubbed_audio_path),
+            "-acodec", "pcm_s16le",
+            "-ar", "44100",
+            "-ac", "2",  # Stereo output
+            str(output_path)
+        ]
+        subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        return output_path
+
+    logger.info(f"Mixing dubbed audio with background at {background_volume * 100:.0f}% volume")
+
+    if progress_callback:
+        progress_callback(20)
+
+    # Use ffmpeg to mix:
+    # - Dubbed vocals at full volume
+    # - Background at reduced volume
+    cmd = [
+        "ffmpeg", "-y",
+        "-i", str(dubbed_audio_path),          # Input 0: dubbed vocals
+        "-i", str(background_audio_path),       # Input 1: background
+        "-filter_complex",
+        f"[0]aresample=44100,aformat=sample_fmts=fltp:channel_layouts=stereo[vocals];"
+        f"[1]aresample=44100,aformat=sample_fmts=fltp:channel_layouts=stereo,"
+        f"volume={background_volume}[bg];"
+        f"[vocals][bg]amix=inputs=2:duration=first:dropout_transition=2[out]",
+        "-map", "[out]",
+        "-acodec", "pcm_s16le",
+        "-ar", "44100",
+        "-ac", "2",
+        str(output_path)
+    ]
+
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+    if result.returncode != 0:
+        logger.warning(f"Audio mixing failed: {result.stderr[:500]}")
+        logger.info("Falling back to dubbed audio without background.")
+        # Fallback: just use dubbed audio
+        cmd_fallback = [
+            "ffmpeg", "-y",
+            "-i", str(dubbed_audio_path),
+            "-acodec", "pcm_s16le",
+            "-ar", "44100", "-ac", "2",
+            str(output_path)
+        ]
+        subprocess.run(cmd_fallback, capture_output=True, text=True, timeout=300)
+    else:
+        logger.info(f"Audio mixing complete: {output_path}")
+
+    if progress_callback:
+        progress_callback(100)
+
+    return output_path

services/downloader.py

@@ -0,0 +1,114 @@
+"""
+Stage 1 — YouTube Download Service
+Downloads video from YouTube URL using yt-dlp.
+Handles long videos (2.5+ hrs), age-restricted content, and error recovery.
+"""
+
+import logging
+import subprocess
+import json
+from pathlib import Path
+from config import YT_FORMAT, YT_MAX_DURATION
+
+logger = logging.getLogger(__name__)
+
+
+def get_video_info(url: str) -> dict:
+    """Fetch video metadata without downloading."""
+    cmd = [
+        "yt-dlp",
+        "--dump-json",
+        "--no-download",
+        "--no-playlist",
+        url
+    ]
+    logger.info(f"Fetching video info: {url}")
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+
+    if result.returncode != 0:
+        raise RuntimeError(f"yt-dlp info failed: {result.stderr}")
+
+    info = json.loads(result.stdout)
+    duration = info.get("duration", 0)
+
+    if duration > YT_MAX_DURATION:
+        raise ValueError(
+            f"Video is {duration // 3600}h {(duration % 3600) // 60}m long. "
+            f"Max allowed: {YT_MAX_DURATION // 3600}h."
+        )
+
+    return {
+        "title": info.get("title", "unknown"),
+        "duration": duration,
+        "uploader": info.get("uploader", "unknown"),
+        "description": info.get("description", ""),
+        "thumbnail": info.get("thumbnail", ""),
+    }
+
+
+def download_video(url: str, output_dir: Path, progress_callback=None) -> Path:
+    """
+    Download video from YouTube.
+    Returns path to downloaded video file.
+    """
+    output_template = str(output_dir / "source_video.%(ext)s")
+
+    cmd = [
+        "yt-dlp",
+        "-f", YT_FORMAT,
+        "--no-playlist",
+        "--merge-output-format", "mp4",
+        "-o", output_template,
+        "--newline",  # Progress on new lines for parsing
+        url
+    ]
+
+    logger.info(f"Starting download: {url}")
+
+    process = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1
+    )
+
+    for line in process.stdout:
+        line = line.strip()
+        if line:
+            logger.debug(f"yt-dlp: {line}")
+            # Parse progress percentage
+            if "[download]" in line and "%" in line:
+                try:
+                    pct = float(line.split("%")[0].split()[-1])
+                    if progress_callback:
+                        progress_callback(pct)
+                except (ValueError, IndexError):
+                    pass
+
+    process.wait()
+
+    if process.returncode != 0:
+        raise RuntimeError("yt-dlp download failed. Check URL and network.")
+
+    # Find the downloaded file
+    video_files = list(output_dir.glob("source_video.*"))
+    if not video_files:
+        raise FileNotFoundError("Download completed but no video file found.")
+
+    video_path = video_files[0]
+    logger.info(f"Downloaded: {video_path} ({video_path.stat().st_size / 1e6:.1f} MB)")
+    return video_path
+
+
+def use_local_file(file_path: str, output_dir: Path) -> Path:
+    """Copy or symlink a local video file into the job directory."""
+    import shutil
+    src = Path(file_path)
+    if not src.exists():
+        raise FileNotFoundError(f"Local file not found: {file_path}")
+
+    dest = output_dir / f"source_video{src.suffix}"
+    shutil.copy2(src, dest)
+    logger.info(f"Using local file: {dest}")
+    return dest

services/merger.py

@@ -0,0 +1,84 @@
+"""
+Stage 9 — Final Video Merge
+Replaces original audio with dubbed audio in the video.
+Video stream is copied (no re-encoding) for speed.
+"""
+
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def merge_video_audio(
+    video_path: Path,
+    audio_path: Path,
+    output_dir: Path,
+    video_title: str = "dubbed_video",
+    progress_callback=None
+) -> Path:
+    """
+    Replace the original audio track in the video with the dubbed audio.
+    Video is NOT re-encoded (-c:v copy) for maximum speed.
+
+    Returns: Path to final dubbed video file.
+    """
+    # Clean filename
+    safe_title = "".join(c if c.isalnum() or c in " -_" else "_" for c in video_title)
+    safe_title = safe_title[:100].strip() or "dubbed_video"
+    output_path = output_dir / f"{safe_title}_dubbed.mp4"
+
+    logger.info(f"Merging video + dubbed audio → {output_path.name}")
+
+    if progress_callback:
+        progress_callback(10)
+
+    cmd = [
+        "ffmpeg", "-y",
+        "-i", str(video_path),     # Original video
+        "-i", str(audio_path),     # New dubbed audio
+        "-c:v", "copy",            # Don't re-encode video (fast!)
+        "-c:a", "aac",             # Encode audio as AAC
+        "-b:a", "192k",            # Audio bitrate
+        "-map", "0:v:0",           # Take video from first input
+        "-map", "1:a:0",           # Take audio from second input
+        "-shortest",               # Match shortest stream
+        "-movflags", "+faststart", # Web-optimized MP4
+        str(output_path)
+    ]
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=600  # 10 min timeout
+    )
+
+    if result.returncode != 0:
+        # Try with audio re-encoding fallback
+        logger.warning(f"Fast merge failed. Trying with full audio encode. Error: {result.stderr[:300]}")
+        cmd_fallback = [
+            "ffmpeg", "-y",
+            "-i", str(video_path),
+            "-i", str(audio_path),
+            "-c:v", "copy",
+            "-c:a", "aac",
+            "-b:a", "128k",
+            "-map", "0:v:0",
+            "-map", "1:a:0",
+            "-shortest",
+            str(output_path)
+        ]
+        result = subprocess.run(cmd_fallback, capture_output=True, text=True, timeout=600)
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Video merge failed: {result.stderr}")
+
+    file_size_mb = output_path.stat().st_size / 1e6
+    logger.info(f"Final video: {output_path} ({file_size_mb:.1f} MB)")
+
+    if progress_callback:
+        progress_callback(100)
+
+    return output_path

services/speaker_profiler.py

@@ -0,0 +1,37 @@
+"""
+Stage 5 — Speaker Profiler (Simplified — Male Voice Forced)
+Since we force male voice, this just groups speakers.
+"""
+import logging
+from pathlib import Path
+from typing import Dict, List
+from collections import defaultdict
+
+logger = logging.getLogger(__name__)
+
+
+def profile_speakers(
+    segments: List[Dict],
+    audio_path: Path,
+    output_dir: Path
+) -> Dict[str, Dict]:
+    """Profile speakers — all forced to male."""
+    speaker_segments = defaultdict(list)
+    for seg in segments:
+        speaker_segments[seg.get("speaker", "SPEAKER_00")].append(seg)
+
+    logger.info(f"Found {len(speaker_segments)} speakers — ALL forced to MALE voice")
+
+    profiles = {}
+    for speaker_id, segs in speaker_segments.items():
+        total_time = sum(s["end"] - s["start"] for s in segs)
+        profiles[speaker_id] = {
+            "gender": "male",  # FORCED
+            "reference_audio": None,
+            "total_speaking_time": round(total_time, 2),
+            "avg_pitch": 0,
+            "segment_count": len(segs),
+        }
+        logger.info(f"  {speaker_id}: MALE (forced), {len(segs)} segments, {total_time:.1f}s")
+
+    return profiles

services/subtitle_generator.py

@@ -0,0 +1,62 @@
+"""
+Bonus — Subtitle Generator
+Creates .srt subtitle files in both original and target languages.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Dict
+
+logger = logging.getLogger(__name__)
+
+
+def generate_subtitles(
+    segments: List[Dict],
+    output_dir: Path,
+    source_language: str,
+    target_language: str
+) -> Dict[str, Path]:
+    """
+    Generate .srt subtitle files.
+    Returns dict with paths to original and translated subtitle files.
+    """
+    original_srt = output_dir / f"subtitles_{source_language}.srt"
+    translated_srt = output_dir / f"subtitles_{target_language}.srt"
+
+    # Original language subtitles
+    _write_srt(original_srt, segments, text_key="text")
+    logger.info(f"Original subtitles: {original_srt}")
+
+    # Translated language subtitles
+    _write_srt(translated_srt, segments, text_key="translated_text")
+    logger.info(f"Translated subtitles: {translated_srt}")
+
+    return {
+        "original": original_srt,
+        "translated": translated_srt,
+    }
+
+
+def _write_srt(output_path: Path, segments: List[Dict], text_key: str):
+    """Write segments to .srt format."""
+    with open(output_path, "w", encoding="utf-8") as f:
+        for idx, seg in enumerate(segments, 1):
+            text = seg.get(text_key, seg.get("text", "")).strip()
+            if not text:
+                continue
+
+            start = _format_srt_time(seg["start"])
+            end = _format_srt_time(seg["end"])
+
+            f.write(f"{idx}\n")
+            f.write(f"{start} --> {end}\n")
+            f.write(f"{text}\n\n")
+
+
+def _format_srt_time(seconds: float) -> str:
+    """Convert seconds to SRT time format: HH:MM:SS,mmm"""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = int(seconds % 60)
+    millis = int((seconds % 1) * 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"

services/transcriber.py

@@ -0,0 +1,243 @@
+"""
+Stage 4 — Transcription Service
+PRIMARY: HuggingFace Inference API (free GPU — whisper-large-v3)
+FALLBACK: Local faster-whisper (CPU)
+
+For long videos: splits audio into 30s chunks and sends to HF API.
+This gives us GPU-quality transcription for FREE.
+"""
+import logging
+import subprocess
+import json
+import time
+import requests
+from pathlib import Path
+from typing import List, Dict, Optional
+
+from config import HF_API_URL, HF_TOKEN, HF_CHUNK_DURATION_SEC, WHISPER_MODEL_SIZE
+
+logger = logging.getLogger(__name__)
+
+
+def transcribe_audio(
+    audio_path: Path,
+    output_dir: Path,
+    source_language: Optional[str] = None,
+    device: str = "cpu",
+    progress_callback=None,
+) -> List[Dict]:
+    """Transcribe audio — tries HF GPU API first, falls back to local."""
+
+    # Try HuggingFace API first (free GPU!)
+    try:
+        logger.info("Attempting HuggingFace GPU transcription (whisper-large-v3)...")
+        segments = _transcribe_hf_api(audio_path, output_dir, source_language, progress_callback)
+        if segments and len(segments) > 0:
+            logger.info(f"HF API transcription success: {len(segments)} segments")
+            return segments
+    except Exception as e:
+        logger.warning(f"HF API failed: {e}. Falling back to local.")
+
+    # Fallback: local faster-whisper
+    logger.info("Using local faster-whisper fallback...")
+    return _transcribe_local(audio_path, output_dir, source_language, progress_callback)
+
+
+def _transcribe_hf_api(
+    audio_path: Path,
+    output_dir: Path,
+    source_language: Optional[str],
+    progress_callback=None,
+) -> List[Dict]:
+    """
+    Transcribe using HuggingFace Inference API with GPU.
+    Splits long audio into chunks, sends each to the API.
+    """
+    # Get audio duration
+    duration = _get_duration(audio_path)
+    logger.info(f"Audio duration: {duration:.1f}s ({duration/60:.1f} min)")
+
+    # Split into chunks
+    chunk_dir = output_dir / "audio_chunks"
+    chunk_dir.mkdir(exist_ok=True)
+
+    chunk_duration = HF_CHUNK_DURATION_SEC
+    chunks = _split_audio(audio_path, chunk_dir, chunk_duration)
+    logger.info(f"Split into {len(chunks)} chunks ({chunk_duration}s each)")
+
+    headers = {}
+    if HF_TOKEN:
+        headers["Authorization"] = f"Bearer {HF_TOKEN}"
+
+    all_segments = []
+    time_offset = 0.0
+
+    for idx, chunk_path in enumerate(chunks):
+        if progress_callback:
+            progress_callback(int((idx / len(chunks)) * 100))
+
+        # Read chunk bytes
+        with open(chunk_path, "rb") as f:
+            audio_bytes = f.read()
+
+        # Send to HF API
+        retries = 3
+        for attempt in range(retries):
+            try:
+                resp = requests.post(
+                    HF_API_URL,
+                    headers=headers,
+                    data=audio_bytes,
+                    timeout=120,
+                )
+
+                if resp.status_code == 503:
+                    # Model is loading
+                    wait_time = resp.json().get("estimated_time", 30)
+                    logger.info(f"Model loading, waiting {wait_time:.0f}s...")
+                    time.sleep(min(wait_time, 60))
+                    continue
+
+                if resp.status_code == 429:
+                    # Rate limited
+                    logger.info("Rate limited, waiting 10s...")
+                    time.sleep(10)
+                    continue
+
+                resp.raise_for_status()
+                result = resp.json()
+
+                # Extract text and create segment
+                text = result.get("text", "").strip()
+                if text:
+                    chunk_start = idx * chunk_duration
+                    all_segments.append({
+                        "start": round(chunk_start, 3),
+                        "end": round(chunk_start + chunk_duration, 3),
+                        "text": text,
+                        "speaker": "SPEAKER_00",
+                        "words": [],
+                    })
+
+                # Handle chunked results if API returns them
+                if "chunks" in result:
+                    for chunk_seg in result["chunks"]:
+                        ts = chunk_seg.get("timestamp", [0, chunk_duration])
+                        all_segments.append({
+                            "start": round((ts[0] or 0) + idx * chunk_duration, 3),
+                            "end": round((ts[1] or chunk_duration) + idx * chunk_duration, 3),
+                            "text": chunk_seg.get("text", "").strip(),
+                            "speaker": "SPEAKER_00",
+                            "words": [],
+                        })
+                    # Remove the full-chunk segment we added above
+                    if text and "chunks" in result:
+                        all_segments = [s for s in all_segments if not (
+                            s["start"] == round(idx * chunk_duration, 3) and
+                            s["text"] == text
+                        )]
+
+                break  # Success
+
+            except requests.exceptions.Timeout:
+                logger.warning(f"Chunk {idx} timed out (attempt {attempt+1})")
+                time.sleep(5)
+            except Exception as e:
+                logger.warning(f"Chunk {idx} error: {e} (attempt {attempt+1})")
+                time.sleep(5)
+
+        if idx % 10 == 0:
+            logger.info(f"Transcribed chunk {idx+1}/{len(chunks)}")
+
+    if not all_segments:
+        raise RuntimeError("HF API returned no transcription results")
+
+    # Detect language from first few segments
+    detected_lang = source_language or "hi"
+
+    # Save transcript
+    transcript_path = output_dir / "transcript.json"
+    with open(transcript_path, "w", encoding="utf-8") as f:
+        json.dump({
+            "language": detected_lang,
+            "segments": all_segments,
+            "total_segments": len(all_segments),
+            "method": "huggingface_gpu_api",
+        }, f, ensure_ascii=False, indent=2)
+
+    if progress_callback:
+        progress_callback(100)
+
+    return all_segments
+
+
+def _transcribe_local(
+    audio_path: Path,
+    output_dir: Path,
+    source_language: Optional[str],
+    progress_callback=None,
+) -> List[Dict]:
+    """Fallback: local faster-whisper on CPU."""
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError:
+        raise RuntimeError("faster-whisper not installed. Run: pip install faster-whisper")
+
+    model = WhisperModel(WHISPER_MODEL_SIZE, device="cpu", compute_type="int8")
+
+    raw_segments, info = model.transcribe(
+        str(audio_path),
+        language=source_language,
+        beam_size=5,
+        vad_filter=True,
+    )
+
+    segments = []
+    for seg in raw_segments:
+        segments.append({
+            "start": round(seg.start, 3),
+            "end": round(seg.end, 3),
+            "text": seg.text.strip(),
+            "speaker": "SPEAKER_00",
+            "words": [],
+        })
+
+    transcript_path = output_dir / "transcript.json"
+    with open(transcript_path, "w", encoding="utf-8") as f:
+        json.dump({
+            "language": info.language,
+            "segments": segments,
+            "total_segments": len(segments),
+            "method": "local_faster_whisper",
+        }, f, ensure_ascii=False, indent=2)
+
+    if progress_callback:
+        progress_callback(100)
+
+    return segments
+
+
+def _get_duration(audio_path: Path) -> float:
+    cmd = ["ffprobe", "-v", "quiet", "-show_entries", "format=duration", "-of", "csv=p=0", str(audio_path)]
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    return float(result.stdout.strip())
+
+
+def _split_audio(audio_path: Path, output_dir: Path, chunk_sec: int) -> List[Path]:
+    """Split audio into fixed-duration chunks."""
+    duration = _get_duration(audio_path)
+    chunks = []
+
+    for start in range(0, int(duration) + 1, chunk_sec):
+        chunk_path = output_dir / f"chunk_{start:06d}.wav"
+        cmd = [
+            "ffmpeg", "-y", "-i", str(audio_path),
+            "-ss", str(start), "-t", str(chunk_sec),
+            "-acodec", "pcm_s16le", "-ar", "16000", "-ac", "1",
+            str(chunk_path)
+        ]
+        subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if chunk_path.exists() and chunk_path.stat().st_size > 1000:
+            chunks.append(chunk_path)
+
+    return chunks

services/translator.py

@@ -0,0 +1,139 @@
+"""
+Stage 5 — Translation Service
+Translates transcribed segments into target language.
+Uses deep-translator (Google Translate free tier) — no API key needed.
+Batches nearby segments for better translation quality.
+"""
+
+import logging
+import json
+from pathlib import Path
+from typing import List, Dict, Optional
+
+from config import TRANSLATION_BATCH_SIZE
+
+logger = logging.getLogger(__name__)
+
+
+def translate_segments(
+    segments: List[Dict],
+    source_language: str,
+    target_language: str,
+    output_dir: Path,
+    progress_callback=None
+) -> List[Dict]:
+    """
+    Translate all segments into the target language.
+    Groups short consecutive segments from same speaker for better context.
+
+    Returns segments with added 'translated_text' field.
+    """
+    try:
+        from deep_translator import GoogleTranslator
+    except ImportError:
+        raise RuntimeError("deep-translator not installed. Run: pip install deep-translator")
+
+    translator = GoogleTranslator(source=source_language, target=target_language)
+
+    total = len(segments)
+    translated_segments = []
+
+    # Batch translate for efficiency and context
+    batches = _create_translation_batches(segments)
+    logger.info(f"Translating {total} segments in {len(batches)} batches → {target_language}")
+
+    done_count = 0
+    for batch_idx, batch in enumerate(batches):
+        # Combine batch texts with separator
+        combined_text = " ||| ".join(seg["text"] for seg in batch)
+
+        try:
+            translated_combined = translator.translate(combined_text)
+            # Split back
+            translated_parts = translated_combined.split(" ||| ")
+
+            # If split count doesn't match, translate individually
+            if len(translated_parts) != len(batch):
+                translated_parts = _translate_individually(translator, batch)
+
+        except Exception as e:
+            logger.warning(f"Batch translation failed: {e}. Translating individually.")
+            translated_parts = _translate_individually(translator, batch)
+
+        # Assign translations back to segments
+        for seg, translated_text in zip(batch, translated_parts):
+            seg_copy = seg.copy()
+            seg_copy["translated_text"] = translated_text.strip()
+            translated_segments.append(seg_copy)
+            done_count += 1
+
+        if progress_callback:
+            progress_callback(int(done_count / total * 100))
+
+    # Handle empty/non-speech segments
+    for seg in translated_segments:
+        if not seg.get("translated_text") or seg["translated_text"].strip() == "":
+            seg["translated_text"] = seg["text"]  # Keep original if translation empty
+
+    # Save translated transcript
+    output_path = output_dir / "translated_segments.json"
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump({
+            "source_language": source_language,
+            "target_language": target_language,
+            "segments": translated_segments,
+            "total": len(translated_segments),
+        }, f, ensure_ascii=False, indent=2)
+
+    logger.info(f"Translation complete: {len(translated_segments)} segments → {output_path}")
+    return translated_segments
+
+
+def _create_translation_batches(
+    segments: List[Dict],
+    max_batch_chars: int = 4000
+) -> List[List[Dict]]:
+    """
+    Group consecutive segments from same speaker into batches.
+    Respects Google Translate's character limits (~5000 chars).
+    """
+    batches = []
+    current_batch = []
+    current_chars = 0
+    current_speaker = None
+
+    for seg in segments:
+        text = seg.get("text", "").strip()
+        if not text:
+            continue
+
+        # Start new batch if speaker changes or char limit reached
+        if (current_speaker and seg["speaker"] != current_speaker) or \
+           (current_chars + len(text) > max_batch_chars) or \
+           len(current_batch) >= TRANSLATION_BATCH_SIZE:
+            if current_batch:
+                batches.append(current_batch)
+            current_batch = []
+            current_chars = 0
+
+        current_batch.append(seg)
+        current_chars += len(text) + 5  # +5 for separator
+        current_speaker = seg["speaker"]
+
+    if current_batch:
+        batches.append(current_batch)
+
+    return batches
+
+
+def _translate_individually(translator, batch: List[Dict]) -> List[str]:
+    """Fallback: translate each segment one by one."""
+    results = []
+    for seg in batch:
+        try:
+            translated = translator.translate(seg["text"])
+            results.append(translated or seg["text"])
+        except Exception as e:
+            logger.warning(f"Individual translation failed for '{seg['text'][:50]}...': {e}")
+            results.append(seg["text"])  # Keep original on failure
+    return results

services/tts_generator.py

@@ -0,0 +1,134 @@
+"""
+Stage 7 — TTS Generation (MALE VOICE ONLY)
+Uses Edge TTS (free, no API key). Forces male voice for ALL speakers.
+"""
+import logging
+import asyncio
+import subprocess
+from pathlib import Path
+from typing import List, Dict
+
+from config import EDGE_TTS_VOICES, TTS_MAX_SPEED_FACTOR, FORCE_MALE_VOICE
+
+logger = logging.getLogger(__name__)
+
+
+def generate_dubbed_audio(
+    translated_segments: List[Dict],
+    speaker_profiles: Dict,
+    target_language: str,
+    output_dir: Path,
+    progress_callback=None
+) -> List[Dict]:
+    """Generate TTS audio. ALWAYS uses male voice."""
+    tts_dir = output_dir / "tts_segments"
+    tts_dir.mkdir(exist_ok=True)
+
+    voices = EDGE_TTS_VOICES.get(target_language)
+    if not voices:
+        raise ValueError(f"No voices for '{target_language}'. Supported: {list(EDGE_TTS_VOICES.keys())}")
+
+    # FORCE MALE VOICE
+    voice = voices["male"]
+    logger.info(f"Using MALE voice: {voice} (forced)")
+
+    total = len(translated_segments)
+    results = []
+
+    # Create or get event loop
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_closed():
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+    for idx, seg in enumerate(translated_segments):
+        text = seg.get("translated_text", "").strip()
+        if not text:
+            seg_result = seg.copy()
+            seg_result["tts_audio_path"] = None
+            seg_result["tts_duration"] = 0
+            results.append(seg_result)
+            continue
+
+        output_path = tts_dir / f"seg_{idx:06d}.mp3"
+        try:
+            loop.run_until_complete(_generate_tts_segment(text, voice, output_path))
+        except Exception as e:
+            logger.warning(f"TTS failed for segment {idx}: {e}")
+            seg_result = seg.copy()
+            seg_result["tts_audio_path"] = None
+            seg_result["tts_duration"] = 0
+            results.append(seg_result)
+            continue
+
+        if not output_path.exists() or output_path.stat().st_size == 0:
+            seg_result = seg.copy()
+            seg_result["tts_audio_path"] = None
+            seg_result["tts_duration"] = 0
+            results.append(seg_result)
+            continue
+
+        tts_duration = _get_audio_duration(output_path)
+        original_duration = seg["end"] - seg["start"]
+
+        # Speed-match
+        if original_duration > 0 and tts_duration > 0:
+            speed_ratio = tts_duration / original_duration
+            if speed_ratio > 1.05:
+                target_speed = min(speed_ratio, TTS_MAX_SPEED_FACTOR)
+                adjusted_path = tts_dir / f"seg_{idx:06d}_adj.mp3"
+                _adjust_speed(output_path, adjusted_path, target_speed)
+                if adjusted_path.exists():
+                    output_path = adjusted_path
+                    tts_duration = _get_audio_duration(output_path)
+
+        seg_result = seg.copy()
+        seg_result["tts_audio_path"] = str(output_path)
+        seg_result["tts_duration"] = round(tts_duration, 3)
+        seg_result["voice_used"] = voice
+        seg_result["gender_matched"] = "male"
+        results.append(seg_result)
+
+        if progress_callback and idx % 10 == 0:
+            progress_callback(int((idx + 1) / total * 100))
+
+    if progress_callback:
+        progress_callback(100)
+
+    valid = len([r for r in results if r.get("tts_audio_path")])
+    logger.info(f"TTS complete: {valid}/{total} segments (MALE voice: {voice})")
+    return results
+
+
+async def _generate_tts_segment(text: str, voice: str, output_path: Path):
+    import edge_tts
+    communicate = edge_tts.Communicate(text, voice)
+    await communicate.save(str(output_path))
+
+
+def _get_audio_duration(audio_path: Path) -> float:
+    cmd = ["ffprobe", "-v", "quiet", "-show_entries", "format=duration", "-of", "csv=p=0", str(audio_path)]
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+    try:
+        return float(result.stdout.strip())
+    except (ValueError, AttributeError):
+        return 0.0
+
+
+def _adjust_speed(input_path: Path, output_path: Path, speed_factor: float):
+    filters = []
+    remaining = speed_factor
+    while remaining > 2.0:
+        filters.append("atempo=2.0")
+        remaining /= 2.0
+    while remaining < 0.5:
+        filters.append("atempo=0.5")
+        remaining /= 0.5
+    filters.append(f"atempo={remaining:.4f}")
+    filter_chain = ",".join(filters)
+    cmd = ["ffmpeg", "-y", "-i", str(input_path), "-filter:a", filter_chain, str(output_path)]
+    subprocess.run(cmd, capture_output=True, text=True, timeout=30)

services/vocal_separator.py

@@ -0,0 +1,89 @@
+"""
+Stage 2B — Vocal/Background Separation using Demucs
+Separates vocals from background music/noise for cleaner dubbing.
+Falls back to using raw audio if demucs is not available.
+"""
+
+import logging
+import subprocess
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def separate_vocals(audio_path: Path, output_dir: Path) -> dict:
+    """
+    Use demucs to separate vocals from background audio.
+    Returns dict with 'vocals' and 'background' paths.
+    Falls back to raw audio if demucs is unavailable.
+    """
+    vocals_dir = output_dir / "separated"
+    vocals_dir.mkdir(exist_ok=True)
+
+    # Check if demucs is available
+    if not shutil.which("python") and not shutil.which("demucs"):
+        logger.warning("Demucs not found. Using raw audio without separation.")
+        return _fallback_no_separation(audio_path, output_dir)
+
+    try:
+        cmd = [
+            "python", "-m", "demucs",
+            "--two-stems", "vocals",    # Only separate vocals vs rest
+            "-n", "htdemucs",           # Best free model
+            "-o", str(vocals_dir),
+            "--mp3",                     # Smaller output
+            str(audio_path)
+        ]
+
+        logger.info("Running demucs vocal separation (this takes a while for long audio)...")
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=3600  # 1 hour timeout for long videos
+        )
+
+        if result.returncode != 0:
+            logger.warning(f"Demucs failed: {result.stderr}. Falling back to raw audio.")
+            return _fallback_no_separation(audio_path, output_dir)
+
+        # Demucs outputs to: separated/htdemucs/<filename>/vocals.mp3 and no_vocals.mp3
+        stem_name = audio_path.stem
+        demucs_out = vocals_dir / "htdemucs" / stem_name
+
+        vocals_path = demucs_out / "vocals.mp3"
+        background_path = demucs_out / "no_vocals.mp3"
+
+        if not vocals_path.exists():
+            # Try wav extension
+            vocals_path = demucs_out / "vocals.wav"
+            background_path = demucs_out / "no_vocals.wav"
+
+        if not vocals_path.exists():
+            logger.warning("Demucs output not found. Falling back.")
+            return _fallback_no_separation(audio_path, output_dir)
+
+        logger.info(f"Vocal separation complete: vocals={vocals_path}, bg={background_path}")
+        return {
+            "vocals": vocals_path,
+            "background": background_path,
+            "separated": True
+        }
+
+    except subprocess.TimeoutExpired:
+        logger.warning("Demucs timed out. Falling back to raw audio.")
+        return _fallback_no_separation(audio_path, output_dir)
+    except Exception as e:
+        logger.warning(f"Demucs error: {e}. Falling back to raw audio.")
+        return _fallback_no_separation(audio_path, output_dir)
+
+
+def _fallback_no_separation(audio_path: Path, output_dir: Path) -> dict:
+    """Fallback: use raw audio as vocals, no background track."""
+    logger.info("Using raw audio without vocal separation.")
+    return {
+        "vocals": audio_path,
+        "background": None,
+        "separated": False
+    }

templates/index.html

@@ -0,0 +1,251 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Video Dubbing Agent</title>
+    <style>
+        :root {
+            --bg: #0a0a12; --s1: #13132a; --s2: #1c1c3a; --border: #2a2a4a;
+            --accent: #7c5cfc; --accent2: #a78bfa; --green: #10b981;
+            --yellow: #f59e0b; --red: #ef4444; --text: #e8e8f4; --text2: #8888a8;
+        }
+        * { margin:0; padding:0; box-sizing:border-box; }
+        body { font-family:'Inter','Segoe UI',system-ui,sans-serif; background:var(--bg); color:var(--text); min-height:100vh; }
+        .wrap { max-width:860px; margin:0 auto; padding:1.5rem; }
+
+        /* Header */
+        .hdr { text-align:center; padding:2rem 0 1.5rem; }
+        .hdr h1 { font-size:2rem; background:linear-gradient(135deg,var(--accent),var(--green)); -webkit-background-clip:text; -webkit-text-fill-color:transparent; }
+        .hdr p { color:var(--text2); font-size:0.9rem; margin-top:0.3rem; }
+        .badge { display:inline-block; padding:0.2rem 0.6rem; background:rgba(124,92,252,0.15); color:var(--accent2); border-radius:20px; font-size:0.7rem; font-weight:600; margin-top:0.5rem; border:1px solid rgba(124,92,252,0.3); }
+
+        /* Card */
+        .card { background:var(--s1); border:1px solid var(--border); border-radius:14px; padding:1.5rem; margin-bottom:1.2rem; }
+        .card h2 { font-size:1rem; color:var(--accent2); margin-bottom:1rem; }
+
+        /* Form */
+        .fg { margin-bottom:0.9rem; }
+        .fg label { display:block; font-size:0.78rem; color:var(--text2); margin-bottom:0.3rem; font-weight:500; text-transform:uppercase; letter-spacing:0.5px; }
+        input, select { width:100%; padding:0.7rem 0.9rem; background:var(--s2); border:1px solid var(--border); border-radius:8px; color:var(--text); font-size:0.9rem; outline:none; transition:border 0.2s; }
+        input:focus, select:focus { border-color:var(--accent); }
+        select option { background:var(--s2); }
+
+        /* Button */
+        .btn { display:flex; align-items:center; justify-content:center; gap:0.5rem; padding:0.8rem; background:linear-gradient(135deg,var(--accent),#6d28d9); color:#fff; border:none; border-radius:10px; font-size:0.95rem; font-weight:600; cursor:pointer; width:100%; transition:all 0.2s; }
+        .btn:hover { opacity:0.9; transform:translateY(-1px); }
+        .btn:disabled { opacity:0.4; cursor:not-allowed; transform:none; }
+        .btn-green { background:linear-gradient(135deg,var(--green),#059669); }
+        .btn-sm { padding:0.5rem 1rem; font-size:0.8rem; width:auto; border-radius:8px; }
+        .btn-ghost { background:var(--s2); border:1px solid var(--border); }
+
+        /* Progress */
+        .hidden { display:none !important; }
+        .prog-bar-wrap { background:var(--s2); border-radius:20px; height:32px; position:relative; overflow:hidden; margin:0.8rem 0; }
+        .prog-bar { height:100%; background:linear-gradient(90deg,var(--accent),var(--green)); border-radius:20px; transition:width 0.6s ease; }
+        .prog-text { position:absolute; top:50%; left:50%; transform:translate(-50%,-50%); font-size:0.8rem; font-weight:700; color:#fff; text-shadow:0 1px 3px rgba(0,0,0,0.5); }
+
+        /* Stats grid */
+        .stats { display:grid; grid-template-columns:1fr 1fr 1fr; gap:0.6rem; margin:0.8rem 0; }
+        .stat { background:var(--s2); padding:0.6rem 0.8rem; border-radius:8px; }
+        .stat .lbl { font-size:0.65rem; color:var(--text2); text-transform:uppercase; letter-spacing:0.5px; }
+        .stat .val { font-size:1rem; font-weight:700; margin-top:0.15rem; }
+
+        /* Pipeline visual */
+        .pipe { display:flex; flex-wrap:wrap; gap:0.3rem; margin:0.8rem 0; }
+        .dot { padding:0.25rem 0.55rem; border-radius:6px; font-size:0.65rem; font-weight:500; background:var(--s2); color:var(--text2); border:1px solid var(--border); transition:all 0.3s; }
+        .dot.done { background:rgba(16,185,129,0.12); color:var(--green); border-color:var(--green); }
+        .dot.now { background:rgba(124,92,252,0.15); color:var(--accent2); border-color:var(--accent); animation:blink 1.2s ease-in-out infinite; }
+        @keyframes blink { 0%,100%{opacity:1} 50%{opacity:0.5} }
+
+        /* Log */
+        .log { background:#06060e; border:1px solid var(--border); border-radius:8px; padding:0.8rem; font-family:'Fira Code',monospace; font-size:0.72rem; color:var(--text2); max-height:180px; overflow-y:auto; margin-top:0.8rem; }
+        .log .l { padding:0.1rem 0; }
+        .log .ok { color:var(--green); }
+        .log .wr { color:var(--yellow); }
+        .log .er { color:var(--red); }
+
+        /* Result */
+        .res-ok { border-color:var(--green) !important; }
+        .res-err { border-color:var(--red) !important; }
+
+        /* Jobs */
+        .job { display:flex; justify-content:space-between; align-items:center; padding:0.6rem 0.8rem; background:var(--s2); border-radius:8px; margin-bottom:0.4rem; }
+        .job-id { font-family:monospace; color:var(--accent2); font-size:0.85rem; }
+        .job-st { padding:0.15rem 0.5rem; border-radius:4px; font-size:0.7rem; font-weight:600; }
+        .st-completed { background:rgba(16,185,129,0.12); color:var(--green); }
+        .st-processing { background:rgba(124,92,252,0.12); color:var(--accent2); }
+        .st-failed { background:rgba(239,68,68,0.12); color:var(--red); }
+        .st-queued { background:rgba(245,158,11,0.12); color:var(--yellow); }
+
+        .dl-row { display:flex; gap:0.5rem; margin-top:0.6rem; flex-wrap:wrap; }
+        .footer { text-align:center; padding:1.5rem 0; color:var(--text2); font-size:0.72rem; }
+
+        @media(max-width:600px) { .stats{grid-template-columns:1fr 1fr} .wrap{padding:1rem} .hdr h1{font-size:1.5rem} }
+    </style>
+</head>
+<body>
+<div class="wrap">
+    <div class="hdr">
+        <h1>Video Dubbing Agent</h1>
+        <p>YouTube video → dubbed in any language with AI</p>
+        <span class="badge">MALE VOICE &bull; FREE GPU &bull; 20+ LANGUAGES</span>
+    </div>
+
+    <!-- INPUT -->
+    <div class="card" id="inputCard">
+        <h2>New Dubbing Job</h2>
+        <div class="fg">
+            <label>YouTube URL</label>
+            <input type="text" id="ytUrl" placeholder="https://www.youtube.com/watch?v=..." value="https://www.youtube.com/watch?v=LiQ91h3yFeI" />
+        </div>
+        <div class="fg">
+            <label>Target Language</label>
+            <select id="lang">
+                <option value="mr" selected>Marathi</option>
+                <option value="hi">Hindi</option>
+                <option value="en">English</option>
+                <option value="es">Spanish</option>
+                <option value="fr">French</option>
+                <option value="de">German</option>
+                <option value="ja">Japanese</option>
+                <option value="zh">Chinese</option>
+                <option value="pt">Portuguese</option>
+                <option value="ar">Arabic</option>
+                <option value="ko">Korean</option>
+                <option value="ru">Russian</option>
+                <option value="it">Italian</option>
+                <option value="ta">Tamil</option>
+                <option value="te">Telugu</option>
+                <option value="bn">Bengali</option>
+                <option value="gu">Gujarati</option>
+                <option value="kn">Kannada</option>
+                <option value="ml">Malayalam</option>
+                <option value="ur">Urdu</option>
+            </select>
+        </div>
+        <button class="btn" id="startBtn" onclick="startJob()">Start Dubbing</button>
+    </div>
+
+    <!-- PROGRESS -->
+    <div class="card hidden" id="progCard">
+        <h2 id="progTitle">Processing...</h2>
+        <div id="vidTitle" style="color:var(--text2);font-size:0.85rem;margin-bottom:0.4rem"></div>
+        <div class="prog-bar-wrap">
+            <div class="prog-bar" id="pBar" style="width:0%"></div>
+            <div class="prog-text" id="pText">0%</div>
+        </div>
+        <div class="stats">
+            <div class="stat"><div class="lbl">Stage</div><div class="val" id="sStage">Queued</div></div>
+            <div class="stat"><div class="lbl">Progress</div><div class="val" id="sNum">0 / 11</div></div>
+            <div class="stat"><div class="lbl">Elapsed</div><div class="val" id="sTime">0s</div></div>
+        </div>
+        <div class="pipe" id="pipeDots"></div>
+        <div class="log" id="logBox"></div>
+    </div>
+
+    <!-- RESULT -->
+    <div class="card hidden" id="resCard">
+        <h2 id="resTitle">Done!</h2>
+        <p id="resMsg" style="margin-bottom:0.8rem"></p>
+        <button class="btn btn-green" id="dlBtn" onclick="dlVideo()">Download Dubbed Video (.mp4)</button>
+        <div class="dl-row">
+            <button class="btn btn-sm btn-ghost" onclick="dlSub('original')">Original Subtitles</button>
+            <button class="btn btn-sm btn-ghost" onclick="dlSub('translated')">Translated Subtitles</button>
+            <button class="btn btn-sm btn-ghost" onclick="resetUI()">New Job</button>
+        </div>
+    </div>
+
+    <!-- JOBS -->
+    <div class="card">
+        <h2>Recent Jobs</h2>
+        <div id="jobsList"><span style="color:var(--text2);font-size:0.85rem">No jobs yet</span></div>
+    </div>
+
+    <div class="footer">Video Dubbing Agent v2.0 &mdash; HuggingFace GPU + Edge TTS + FFmpeg &bull; Male Voice Only &bull; 100% Free</div>
+</div>
+
+<script>
+const API='/api';
+let jobId=null, poll=null;
+const SL={downloading:'Download',extracting_audio:'Extract Audio',separating_vocals:'Vocal Split',transcribing:'Transcribe (GPU)',profiling_speakers:'Speakers',translating:'Translate',generating_tts:'TTS (Male)',assembling_audio:'Assembly',mixing_audio:'Mixing',merging_video:'Merge Video',generating_subtitles:'Subtitles'};
+
+function dots(cur){
+    const c=document.getElementById('pipeDots');
+    const st=Object.keys(SL), ci=st.indexOf(cur);
+    c.innerHTML=st.map((s,i)=>`<span class="dot${i<ci?' done':i===ci?' now':''}">${SL[s]}</span>`).join('');
+}
+
+function log(m,t=''){
+    const b=document.getElementById('logBox'),d=document.createElement('div');
+    d.className=`l ${t}`;d.textContent=`[${new Date().toLocaleTimeString()}] ${m}`;
+    b.appendChild(d);b.scrollTop=b.scrollHeight;
+}
+
+async function startJob(){
+    const url=document.getElementById('ytUrl').value.trim();
+    if(!url){alert('Enter a YouTube URL');return}
+    const btn=document.getElementById('startBtn');
+    btn.disabled=true;btn.textContent='Starting...';
+    try{
+        const r=await fetch(`${API}/dub`,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({youtube_url:url,target_language:document.getElementById('lang').value,preserve_background:true,generate_subtitles:true})});
+        const d=await r.json();
+        if(!r.ok)throw new Error(d.detail||'Failed');
+        jobId=d.job_id;log(`Job ${jobId} started`,'ok');
+        document.getElementById('progCard').classList.remove('hidden');
+        document.getElementById('resCard').classList.add('hidden');
+        poll=setInterval(pollJob,2500);
+    }catch(e){alert(e.message);log(e.message,'er')}
+    finally{btn.disabled=false;btn.textContent='Start Dubbing'}
+}
+
+async function pollJob(){
+    if(!jobId)return;
+    try{
+        const r=await fetch(`${API}/status/${jobId}`);
+        const d=await r.json();
+        document.getElementById('sStage').textContent=SL[d.current_stage]||d.current_stage||'Queued';
+        document.getElementById('sNum').textContent=`${d.stage_number} / ${d.total_stages}`;
+        document.getElementById('sTime').textContent=d.elapsed_time_str||'0s';
+        document.getElementById('pBar').style.width=`${d.progress_percent}%`;
+        document.getElementById('pText').textContent=`${d.progress_percent}%`;
+        if(d.video_title)document.getElementById('vidTitle').textContent=d.video_title;
+        dots(d.current_stage);
+        if(d.status==='completed'){clearInterval(poll);log('DONE!','ok');showRes(true,'Your dubbed video is ready!')}
+        else if(d.status==='failed'){clearInterval(poll);log(`FAILED: ${d.error_message}`,'er');showRes(false,d.error_message)}
+        else log(`${SL[d.current_stage]||d.current_stage} — ${d.progress_percent}%`);
+        refreshJobs();
+    }catch(e){log(`Poll err: ${e.message}`,'wr')}
+}
+
+function showRes(ok,msg){
+    const c=document.getElementById('resCard');
+    c.classList.remove('hidden','res-ok','res-err');
+    c.classList.add(ok?'res-ok':'res-err');
+    document.getElementById('resTitle').textContent=ok?'Dubbing Complete!':'Failed';
+    document.getElementById('resMsg').textContent=msg;
+    document.getElementById('dlBtn').style.display=ok?'flex':'none';
+}
+
+function dlVideo(){if(jobId)window.open(`${API}/download/${jobId}`,'_blank')}
+function dlSub(t){if(jobId)window.open(`${API}/download/${jobId}/subtitles/${t}`,'_blank')}
+function resetUI(){
+    jobId=null;
+    document.getElementById('progCard').classList.add('hidden');
+    document.getElementById('resCard').classList.add('hidden');
+    document.getElementById('logBox').innerHTML='';
+    document.getElementById('pBar').style.width='0%';
+    document.getElementById('pText').textContent='0%';
+}
+
+async function refreshJobs(){
+    try{
+        const r=await fetch(`${API}/jobs`),d=await r.json(),c=document.getElementById('jobsList');
+        if(!d.jobs||!d.jobs.length){c.innerHTML='<span style="color:var(--text2);font-size:0.85rem">No jobs yet</span>';return}
+        c.innerHTML=d.jobs.slice(-5).reverse().map(j=>`<div class="job"><div><span class="job-id">${j.job_id}</span> <span style="color:var(--text2);font-size:0.75rem">${j.video_title||''}</span></div><span class="job-st st-${j.status}">${j.status}</span></div>`).join('');
+    }catch(e){}
+}
+refreshJobs();
+</script>
+</body>
+</html>

utils/file_manager.py

@@ -0,0 +1,76 @@
+"""
+Utility — File & Job Directory Manager
+Creates/cleans temp directories, tracks disk usage, handles expiry.
+"""
+
+import logging
+import shutil
+import uuid
+import time
+from pathlib import Path
+from config import TEMP_DIR, JOB_EXPIRY_HOURS
+
+logger = logging.getLogger(__name__)
+
+
+def create_job_directory() -> tuple:
+    """Create a unique job directory. Returns (job_id, job_dir)."""
+    job_id = str(uuid.uuid4())[:8]
+    job_dir = TEMP_DIR / job_id
+    job_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Created job directory: {job_dir}")
+    return job_id, job_dir
+
+
+def get_job_directory(job_id: str) -> Path:
+    """Get the directory for a given job ID."""
+    job_dir = TEMP_DIR / job_id
+    if not job_dir.exists():
+        raise FileNotFoundError(f"Job directory not found: {job_id}")
+    return job_dir
+
+
+def cleanup_job(job_id: str):
+    """Remove all temp files for a job."""
+    job_dir = TEMP_DIR / job_id
+    if job_dir.exists():
+        shutil.rmtree(job_dir)
+        logger.info(f"Cleaned up job: {job_id}")
+
+
+def cleanup_expired_jobs():
+    """Remove job directories older than JOB_EXPIRY_HOURS."""
+    if not TEMP_DIR.exists():
+        return
+
+    now = time.time()
+    expiry_seconds = JOB_EXPIRY_HOURS * 3600
+    cleaned = 0
+
+    for job_dir in TEMP_DIR.iterdir():
+        if job_dir.is_dir():
+            age = now - job_dir.stat().st_mtime
+            if age > expiry_seconds:
+                shutil.rmtree(job_dir)
+                logger.info(f"Expired job cleaned: {job_dir.name}")
+                cleaned += 1
+
+    if cleaned:
+        logger.info(f"Cleaned {cleaned} expired jobs")
+
+
+def get_job_disk_usage(job_id: str) -> str:
+    """Get human-readable disk usage for a job."""
+    job_dir = TEMP_DIR / job_id
+    if not job_dir.exists():
+        return "0 B"
+
+    total = sum(f.stat().st_size for f in job_dir.rglob("*") if f.is_file())
+
+    if total > 1e9:
+        return f"{total / 1e9:.1f} GB"
+    elif total > 1e6:
+        return f"{total / 1e6:.1f} MB"
+    elif total > 1e3:
+        return f"{total / 1e3:.1f} KB"
+    return f"{total} B"

utils/gpu_detector.py

@@ -0,0 +1,87 @@
+"""
+Utility — GPU Detection
+Auto-detect CUDA availability and recommend settings.
+"""
+
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+def detect_gpu() -> dict:
+    """
+    Detect GPU availability and return system info.
+    """
+    info = {
+        "cuda_available": False,
+        "gpu_name": None,
+        "gpu_memory_mb": 0,
+        "recommended_device": "cpu",
+        "recommended_compute": "int8",
+        "recommended_batch_size": 4,
+    }
+
+    try:
+        import torch
+        if torch.cuda.is_available():
+            info["cuda_available"] = True
+            info["gpu_name"] = torch.cuda.get_device_name(0)
+            info["gpu_memory_mb"] = torch.cuda.get_device_properties(0).total_mem // (1024 * 1024)
+            info["recommended_device"] = "cuda"
+            info["recommended_compute"] = "float16"
+            info["recommended_batch_size"] = 16 if info["gpu_memory_mb"] > 8000 else 8
+
+            logger.info(f"GPU detected: {info['gpu_name']} ({info['gpu_memory_mb']} MB)")
+        else:
+            logger.info("PyTorch installed but no CUDA GPU detected.")
+    except ImportError:
+        logger.info("PyTorch not installed. Using CPU mode.")
+
+    # Fallback: check nvidia-smi
+    if not info["cuda_available"]:
+        try:
+            result = subprocess.run(
+                ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"],
+                capture_output=True, text=True, timeout=5
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                parts = result.stdout.strip().split(",")
+                info["gpu_name"] = parts[0].strip()
+                logger.info(f"nvidia-smi found GPU: {info['gpu_name']} (but PyTorch CUDA not available)")
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    return info
+
+
+def get_system_report() -> str:
+    """Generate a human-readable system readiness report."""
+    gpu = detect_gpu()
+    lines = [
+        "=== System Report ===",
+        f"GPU: {gpu['gpu_name'] or 'None detected'}",
+        f"CUDA: {'Yes' if gpu['cuda_available'] else 'No'}",
+        f"VRAM: {gpu['gpu_memory_mb']} MB" if gpu['gpu_memory_mb'] else "VRAM: N/A",
+        f"Mode: {gpu['recommended_device'].upper()}",
+        f"Compute: {gpu['recommended_compute']}",
+        f"Batch size: {gpu['recommended_batch_size']}",
+        "",
+        "Estimated processing times for 2.5hr video:",
+    ]
+
+    if gpu["cuda_available"] and gpu["gpu_memory_mb"] > 8000:
+        lines.append("  Transcription: ~15-25 min")
+        lines.append("  TTS Generation: ~20-30 min")
+        lines.append("  Total: ~45-75 min")
+    elif gpu["cuda_available"]:
+        lines.append("  Transcription: ~25-40 min")
+        lines.append("  TTS Generation: ~30-45 min")
+        lines.append("  Total: ~75-120 min")
+    else:
+        lines.append("  Transcription: ~2-4 hours (CPU)")
+        lines.append("  TTS Generation: ~1-2 hours (CPU)")
+        lines.append("  Total: ~3-6 hours")
+        lines.append("  ⚠ GPU strongly recommended for videos > 30 min")
+
+    return "\n".join(lines)