videopython 0.28.1__tar.gz → 0.28.2__tar.gz

{videopython-0.28.1 → videopython-0.28.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.28.1
+Version: 0.28.2
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -34,6 +34,7 @@ Requires-Dist: numba>=0.61.0; extra == 'ai'
 Requires-Dist: ollama>=0.4.5; extra == 'ai'
 Requires-Dist: openai-whisper>=20240930; extra == 'ai'
 Requires-Dist: pyannote-audio>=4.0.0; extra == 'ai'
+Requires-Dist: pyloudnorm>=0.1.1; extra == 'ai'
 Requires-Dist: scikit-learn>=1.3.0; extra == 'ai'
 Requires-Dist: scipy>=1.10.0; extra == 'ai'
 Requires-Dist: sentencepiece>=0.1.99; extra == 'ai'

{videopython-0.28.1 → videopython-0.28.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.28.1"
+version = "0.28.2"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -82,6 +82,8 @@ ai = [
     "demucs>=4.0.0",
     # Translation backend: Qwen3 GGUF inference (M2)
     "llama-cpp-python>=0.3.0",
+    # Loudness measurement (BS.1770) for dub-vs-source loudness matching (M3)
+    "pyloudnorm>=0.1.1",
 ]
 
 # Required for pip install videopython[ai] - pip uses optional-dependencies, not dependency-groups
@@ -115,6 +117,8 @@ ai = [
     "demucs>=4.0.0",
     # Translation backend: Qwen3 GGUF inference (M2)
     "llama-cpp-python>=0.3.0",
+    # Loudness measurement (BS.1770) for dub-vs-source loudness matching (M3)
+    "pyloudnorm>=0.1.1",
 ]
 
 [project.urls]
@@ -141,6 +145,7 @@ module = [
     "silero_vad", "silero_vad.*",
     "cv2", "cv2.*",
     "llama_cpp", "llama_cpp.*",
+    "pyloudnorm", "pyloudnorm.*",
 ]
 ignore_missing_imports = true
 

{videopython-0.28.1 → videopython-0.28.2}/src/videopython/ai/dubbing/__init__.py

@@ -1,5 +1,6 @@
 """Local video dubbing functionality."""
 
+from videopython.ai.dubbing.cache import DubCache, dub_cache_clear
 from videopython.ai.dubbing.dubber import VideoDubber
 from videopython.ai.dubbing.models import DubbingResult, RevoiceResult, SeparatedAudio, TranslatedSegment
 from videopython.ai.dubbing.pipeline import LocalDubbingPipeline
@@ -19,4 +20,6 @@ __all__ = [
     "TranscriptQuality",
     "assess_transcript",
     "UnsupportedLanguageError",
+    "DubCache",
+    "dub_cache_clear",
 ]

videopython-0.28.2/src/videopython/ai/dubbing/cache.py

@@ -0,0 +1,296 @@
+"""Filesystem-backed cache for resumable dubbing runs.
+
+A long dub crashes at TTS segment 312/400 today and re-runs Whisper,
+Demucs, translation, and the first 311 TTS segments from scratch.
+:class:`DubCache` stores three artifacts so subsequent runs skip stages
+whose inputs match:
+
+- ``transcription.json`` — output of ``AudioToText.transcribe``.
+- ``translation_<key>.json`` — output of ``TranslationBackend.translate_segments``.
+- ``tts/<key>.wav`` — per-segment TTS WAV.
+
+Cache directories are opt-in via ``VideoDubber(cache_dir=...)`` / ``LocalDubbingPipeline(cache_dir=...)``.
+``cache_dir=None`` (default) is a no-op pass-through.
+
+Hash inputs are conservative — false misses (re-run a stage) are cheap;
+false hits (deliver a stale dub) are bugs. Source-audio identity uses a
+sha256 of the raw float32 bytes, not file path, so re-encoding the same
+content invalidates correctly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from videopython.base.audio import Audio
+    from videopython.base.text.transcription import Transcription
+
+logger = logging.getLogger(__name__)
+
+
+# Cache schema version. Bump on incompatible changes to any artifact's
+# on-disk format (e.g. TranscriptionSegment field changes that break
+# from_dict). Mismatched cache entries are treated as a miss.
+SCHEMA_VERSION = 1
+
+# Reserved for M4.3 per-speaker voice library. M3.2 does not write here;
+# documented so future code knows the path is taken.
+_VOICE_CLONES_SUBDIR = "voice_clones"
+
+
+@dataclass(frozen=True)
+class _ArtifactPaths:
+    """Resolved paths for a single source's cache directory."""
+
+    src_dir: Path
+    metadata: Path
+    transcription: Path
+    tts_dir: Path
+
+    def translation_path(self, lang_key: str) -> Path:
+        return self.src_dir / f"translation_{lang_key}.json"
+
+    def tts_path(self, seg_key: str) -> Path:
+        return self.tts_dir / f"{seg_key}.wav"
+
+
+def _stable_hash(*parts: str | int | float | bool | None) -> str:
+    """Short hex digest over a tuple of primitive values.
+
+    Stable across runs — uses ``str(part)`` so int/float/bool/None all
+    serialize deterministically. 16 hex chars (64 bits) is plenty of
+    space for the small cardinality we're hashing into.
+    """
+    h = hashlib.sha256()
+    for part in parts:
+        h.update(repr(part).encode("utf-8"))
+        h.update(b"\x00")
+    return h.hexdigest()[:16]
+
+
+def _audio_bytes_hash(audio: Audio) -> str:
+    """sha256 over the raw audio data buffer.
+
+    Used as the per-source cache directory name. Bytes-level so re-encoded
+    sources (different container, same content) collide intentionally only
+    when the decoded float32 buffer matches.
+    """
+    h = hashlib.sha256()
+    h.update(audio.data.tobytes())
+    return h.hexdigest()[:16]
+
+
+class DubCache:
+    """Filesystem cache for transcription, translation, and TTS artifacts.
+
+    Layout under ``root``::
+
+        <root>/<src_hash>/
+            metadata.json              # schema version + hash inputs
+            transcription.json         # populated on transcription cache miss
+            translation_<lang_key>.json
+            tts/<seg_key>.wav
+            voice_clones/              # reserved for M4.3, not written here
+
+    All getters return ``None`` on miss. Putters are idempotent
+    (overwrite). Schema-version mismatch is treated as a miss for every
+    artifact under that source.
+    """
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    # ----- key derivation --------------------------------------------------
+
+    @staticmethod
+    def source_key(audio: Audio) -> str:
+        """Per-source identifier — sha256 of the raw audio buffer.
+
+        This is the directory name under ``root``; one dir per distinct
+        source, regardless of which stage's kwargs vary.
+        """
+        return _audio_bytes_hash(audio)
+
+    @staticmethod
+    def transcription_kwargs_hash(
+        *,
+        whisper_model: str,
+        enable_diarization: bool,
+        condition_on_previous_text: bool,
+        no_speech_threshold: float,
+        logprob_threshold: float | None,
+    ) -> str:
+        return _stable_hash(
+            whisper_model,
+            enable_diarization,
+            condition_on_previous_text,
+            no_speech_threshold,
+            logprob_threshold,
+        )
+
+    @staticmethod
+    def translation_key(
+        *,
+        source_lang: str,
+        target_lang: str,
+        translator_class: str,
+    ) -> str:
+        """Hash captures the source/target pair + the resolved backend class.
+
+        ``translator_class`` is the *resolved* class name (e.g. ``"MarianTranslator"``),
+        not the user-supplied ``"auto"`` — a CPU run that resolves to Marian
+        must not collide with a GPU run that resolves to Qwen on the same
+        language pair.
+        """
+        return _stable_hash(source_lang, target_lang, translator_class)
+
+    @staticmethod
+    def tts_key(
+        *,
+        translated_text: str,
+        voice_sample_bytes: bytes | None,
+        language: str,
+    ) -> str:
+        """Per-segment key over text + voice sample + language."""
+        h = hashlib.sha256()
+        h.update(translated_text.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(voice_sample_bytes or b"")
+        h.update(b"\x00")
+        h.update(language.encode("utf-8"))
+        return h.hexdigest()[:16]
+
+    # ----- path resolution -------------------------------------------------
+
+    def _paths_for(self, src_hash: str) -> _ArtifactPaths:
+        src_dir = self.root / src_hash
+        return _ArtifactPaths(
+            src_dir=src_dir,
+            metadata=src_dir / "metadata.json",
+            transcription=src_dir / "transcription.json",
+            tts_dir=src_dir / "tts",
+        )
+
+    def _ensure_metadata(self, paths: _ArtifactPaths, hash_inputs: dict[str, Any]) -> None:
+        """Create the source dir + metadata.json if missing.
+
+        ``hash_inputs`` records the kwargs we hashed against so a future
+        schema change can audit cache entries. The schema field is
+        load-bearing: mismatched versions invalidate the entire source dir.
+        """
+        paths.src_dir.mkdir(parents=True, exist_ok=True)
+        paths.tts_dir.mkdir(parents=True, exist_ok=True)
+        if not paths.metadata.exists():
+            paths.metadata.write_text(
+                json.dumps(
+                    {"schema": SCHEMA_VERSION, "hash_inputs": hash_inputs},
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+
+    def _schema_ok(self, paths: _ArtifactPaths) -> bool:
+        if not paths.metadata.exists():
+            return True  # fresh dir; we'll write metadata on first put.
+        try:
+            data = json.loads(paths.metadata.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return False
+        return data.get("schema") == SCHEMA_VERSION
+
+    # ----- transcription ---------------------------------------------------
+
+    def get_transcription(self, src_hash: str, kwargs_hash: str) -> Transcription | None:
+        from videopython.base.text.transcription import Transcription
+
+        paths = self._paths_for(src_hash)
+        if not paths.transcription.exists() or not self._schema_ok(paths):
+            return None
+        try:
+            data = json.loads(paths.transcription.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        if data.get("kwargs_hash") != kwargs_hash:
+            return None
+        logger.info("cache hit: transcription (%s)", src_hash)
+        return Transcription.from_dict(data["transcription"])
+
+    def put_transcription(
+        self,
+        src_hash: str,
+        kwargs_hash: str,
+        transcription: Transcription,
+        hash_inputs: dict[str, Any],
+    ) -> None:
+        paths = self._paths_for(src_hash)
+        self._ensure_metadata(paths, hash_inputs)
+        paths.transcription.write_text(
+            json.dumps(
+                {"kwargs_hash": kwargs_hash, "transcription": transcription.to_dict()},
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+
+    # ----- translation -----------------------------------------------------
+
+    def get_translation(self, src_hash: str, lang_key: str) -> list[dict[str, Any]] | None:
+        paths = self._paths_for(src_hash)
+        if not self._schema_ok(paths):
+            return None
+        path = paths.translation_path(lang_key)
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        logger.info("cache hit: translation (%s/%s)", src_hash, lang_key)
+        return data["segments"]
+
+    def put_translation(self, src_hash: str, lang_key: str, segments_dict: list[dict[str, Any]]) -> None:
+        paths = self._paths_for(src_hash)
+        self._ensure_metadata(paths, {})
+        paths.translation_path(lang_key).write_text(
+            json.dumps({"segments": segments_dict}, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    # ----- tts -------------------------------------------------------------
+
+    def get_tts_path(self, src_hash: str, seg_key: str) -> Path | None:
+        paths = self._paths_for(src_hash)
+        if not self._schema_ok(paths):
+            return None
+        path = paths.tts_path(seg_key)
+        return path if path.exists() else None
+
+    def reserve_tts_path(self, src_hash: str, seg_key: str) -> Path:
+        """Return the path TTS output should be written to. Caller is
+        responsible for the actual write (Audio.save)."""
+        paths = self._paths_for(src_hash)
+        self._ensure_metadata(paths, {})
+        return paths.tts_path(seg_key)
+
+
+def dub_cache_clear(cache_dir: str | Path, src_hash: str | None = None) -> None:
+    """Delete cache entries for a specific source or the whole cache root.
+
+    No auto-eviction in M3.2 — call this to reclaim disk space when a
+    cache directory has grown unwieldy. Safe no-op if ``cache_dir`` or
+    ``cache_dir/<src_hash>`` does not exist.
+    """
+    import shutil
+
+    root = Path(cache_dir)
+    target = root / src_hash if src_hash else root
+    if target.exists():
+        shutil.rmtree(target)
+        logger.info("dub_cache_clear: removed %s", target)

{videopython-0.28.1 → videopython-0.28.2}/src/videopython/ai/dubbing/dubber.py

@@ -50,6 +50,13 @@ class VideoDubber:
             See :class:`videopython.ai.generation.qwen3.Qwen3Translator`
             for tradeoffs (Qwen3 is slower on CPU but produces
             context-aware, length-budgeted output).
+        cache_dir: When set, persist transcription, translated segments,
+            and per-segment TTS WAVs under this directory and skip stages
+            whose inputs already match a cache entry. Use to resume crashed
+            long runs or to iterate on dub configuration without paying
+            transcription cost each time. ``None`` (default) disables
+            caching. Cache grows unbounded; clear via
+            :func:`videopython.ai.dubbing.cache.dub_cache_clear`.
     """
 
     def __init__(
@@ -62,6 +69,7 @@ class VideoDubber:
         logprob_threshold: float | None = -1.0,
         strict_quality: bool = False,
         translator: TranslatorChoice = "auto",
+        cache_dir: str | Path | None = None,
     ):
         self.device = device
         self.low_memory = low_memory
@@ -71,14 +79,16 @@ class VideoDubber:
         self.logprob_threshold = logprob_threshold
         self.strict_quality = strict_quality
         self.translator = translator
+        self.cache_dir = cache_dir
         self._local_pipeline: Any = None
         requested = device.lower() if isinstance(device, str) else "auto"
         logger.info(
-            "VideoDubber initialized with device=%s low_memory=%s whisper_model=%s translator=%s",
+            "VideoDubber initialized with device=%s low_memory=%s whisper_model=%s translator=%s cache_dir=%s",
             requested,
             low_memory,
             whisper_model,
             translator,
+            cache_dir,
         )
 
     def _init_local_pipeline(self) -> None:
@@ -93,6 +103,7 @@ class VideoDubber:
             logprob_threshold=self.logprob_threshold,
             strict_quality=self.strict_quality,
             translator=self.translator,
+            cache_dir=self.cache_dir,
         )
 
     def dub(
@@ -175,6 +186,7 @@ class VideoDubber:
         enable_diarization: bool = False,
         progress_callback: Callable[[str, float], None] | None = None,
         transcription: Any = None,
+        keep_original_audio: bool = False,
     ) -> DubbingResult:
         """Dub a video file in place on disk without loading video frames into memory.
 
@@ -201,6 +213,8 @@ class VideoDubber:
                 step. Speaker labels on the supplied transcription drive per-speaker
                 voice cloning. If it has no speakers, pass ``enable_diarization=True``
                 to add them via pyannote (requires word-level timings).
+            keep_original_audio: If True, retain the source audio in the output
+                as a secondary track behind the dubbed one (editorial A/B).
 
         Returns:
             ``DubbingResult`` with the dubbed audio, translated segments, and
@@ -239,6 +253,7 @@ class VideoDubber:
             video_path=input_path,
             audio=result.dubbed_audio,
             output_path=output_path,
+            keep_original_audio=keep_original_audio,
         )
 
         return result

{videopython-0.28.1 → videopython-0.28.2}/src/videopython/ai/dubbing/models.py

@@ -59,6 +59,31 @@ class TranslatedSegment:
         """Duration of the segment in seconds."""
         return self.end - self.start
 
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization (used by the dub cache)."""
+        return {
+            "original_segment": self.original_segment.to_dict(),
+            "translated_text": self.translated_text,
+            "source_lang": self.source_lang,
+            "target_lang": self.target_lang,
+            "speaker": self.speaker,
+            "start": self.start,
+            "end": self.end,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TranslatedSegment:
+        """Reconstruct from a dict produced by :meth:`to_dict`."""
+        return cls(
+            original_segment=TranscriptionSegment.from_dict(data["original_segment"]),
+            translated_text=data["translated_text"],
+            source_lang=data["source_lang"],
+            target_lang=data["target_lang"],
+            speaker=data.get("speaker"),
+            start=data.get("start", 0.0),
+            end=data.get("end", 0.0),
+        )
+
 
 @dataclass
 class SeparatedAudio:

{videopython-0.28.1 → videopython-0.28.2}/src/videopython/ai/dubbing/pipeline.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any, Callable, Literal
 import numpy as np
 
 from videopython.ai._device import select_device
+from videopython.ai.dubbing.cache import DubCache
 from videopython.ai.dubbing.models import DubbingResult, RevoiceResult, SeparatedAudio, TimingSummary
 from videopython.ai.dubbing.quality import GarbageTranscriptError, assess_transcript
 from videopython.ai.dubbing.timing import TimingSynchronizer
@@ -21,22 +22,25 @@ from videopython.ai.generation.translation import (
 )
 
 if TYPE_CHECKING:
+    from videopython.ai.dubbing.models import TranslatedSegment
     from videopython.base.audio import Audio
+    from videopython.base.text.transcription import Transcription
 
 
 TranslatorChoice = Literal["auto", "marian", "qwen3"]
 
 
+# BS.1770 integrated-loudness measurement requires at least 400 ms of audio
+# (one gating block). Below this, fall back to peak match — pyloudnorm
+# returns -inf or warns, neither of which gives a usable gain.
+_LUFS_MIN_DURATION_SECONDS = 0.4
+
+
 def _peak_match(target: Audio, reference: Audio) -> Audio:
     """Scale ``target`` so its peak amplitude matches ``reference``.
 
-    Demucs background normalization and the timing-assembler peak guard
-    each clamp at 1.0 instead of restoring headroom, so a dubbed mix
-    typically lands quieter than the source — perceptually "thinner."
-    A single peak match recovers most of that drift without LUFS deps.
-
-    No-op when either side has zero peak (silent input or all-silent dub).
-    The new ``Audio`` shares no buffer with ``target``.
+    Used as the fallback when LUFS measurement isn't viable (clip < 0.4s
+    or silent input). The new ``Audio`` shares no buffer with ``target``.
     """
     from videopython.base.audio import Audio as _Audio
 
@@ -53,6 +57,55 @@ def _peak_match(target: Audio, reference: Audio) -> Audio:
     return _Audio(target.data * scale, target.metadata)
 
 
+def _loudness_match(target: Audio, reference: Audio) -> Audio:
+    """Scale ``target`` so its integrated loudness (BS.1770 / LUFS) matches ``reference``.
+
+    Demucs background normalization and the timing-assembler peak guard
+    each clamp at 1.0 instead of restoring perceived loudness, so a
+    dubbed mix lands perceptually "thinner" than the source even after
+    peak match. LUFS captures the ear-weighted envelope that peak ratio
+    misses on dialogue-heavy material.
+
+    Falls back to :func:`_peak_match` when either clip is shorter than
+    the BS.1770 gating block (400 ms) or when measurement returns -inf
+    (silent or near-silent gated content). After gain is applied, peaks
+    are clamped to 0.99 — BS.1770 has no peak ceiling and a sufficiently
+    quiet source can demand gain that would otherwise clip.
+    """
+    from videopython.base.audio import Audio as _Audio
+
+    target_dur = target.metadata.duration_seconds
+    ref_dur = reference.metadata.duration_seconds
+    if target_dur < _LUFS_MIN_DURATION_SECONDS or ref_dur < _LUFS_MIN_DURATION_SECONDS:
+        return _peak_match(target, reference)
+
+    if not target.data.size or not reference.data.size:
+        return target
+
+    import pyloudnorm
+
+    target_lufs = pyloudnorm.Meter(target.metadata.sample_rate).integrated_loudness(target.data)
+    reference_lufs = pyloudnorm.Meter(reference.metadata.sample_rate).integrated_loudness(reference.data)
+
+    # Either clip's gated content was below -70 LUFS (effectively silent
+    # under BS.1770). Gain would be undefined — fall back to peak match,
+    # which has its own silent-input no-op.
+    if not np.isfinite(target_lufs) or not np.isfinite(reference_lufs):
+        return _peak_match(target, reference)
+
+    gain_db = reference_lufs - target_lufs
+    if abs(gain_db) < 0.1:
+        return target
+    scale = float(10 ** (gain_db / 20.0))
+
+    scaled = target.data * scale
+    peak = float(np.max(np.abs(scaled)))
+    if peak > 0.99:
+        scaled = scaled * (0.99 / peak)
+
+    return _Audio(scaled, target.metadata)
+
+
 WhisperModel = Literal["tiny", "base", "small", "medium", "large", "turbo"]
 
 logger = logging.getLogger(__name__)
@@ -85,6 +138,7 @@ class LocalDubbingPipeline:
         logprob_threshold: float | None = -1.0,
         strict_quality: bool = False,
         translator: TranslatorChoice = "auto",
+        cache_dir: str | Path | None = None,
     ):
         self.device = device
         self.low_memory = low_memory
@@ -94,13 +148,15 @@ class LocalDubbingPipeline:
         self.logprob_threshold = logprob_threshold
         self.strict_quality = strict_quality
         self.translator = translator
+        self.cache_dir = Path(cache_dir) if cache_dir is not None else None
         requested = device.lower() if isinstance(device, str) else "auto"
         logger.info(
-            "LocalDubbingPipeline initialized with device=%s low_memory=%s whisper_model=%s translator=%s",
+            "LocalDubbingPipeline initialized with device=%s low_memory=%s whisper_model=%s translator=%s cache_dir=%s",
             requested,
             low_memory,
             whisper_model,
             translator,
+            self.cache_dir,
         )
 
         self._transcriber: Any = None
@@ -110,6 +166,7 @@ class LocalDubbingPipeline:
         self._tts_language: str | None = None
         self._separator: Any = None
         self._synchronizer: TimingSynchronizer | None = None
+        self._cache: DubCache | None = DubCache(self.cache_dir) if self.cache_dir is not None else None
 
     def _maybe_unload(self, component_name: str) -> None:
         """Unload a stage's model when low_memory mode is enabled.
@@ -128,6 +185,188 @@ class LocalDubbingPipeline:
             logger.info("low_memory: unloading %s", component_name.lstrip("_"))
             unload()
 
+    def _transcribe_with_cache(
+        self,
+        source_audio: Audio,
+        enable_diarization: bool,
+    ) -> Transcription:
+        """Run transcription with cache-around-the-call.
+
+        Cache miss: lazy-init the transcriber, transcribe, store the
+        result (including all hashed kwargs in metadata.json so future
+        invalidators have provenance).
+        Cache hit: return the deserialized :class:`Transcription` without
+        touching Whisper/diarization at all.
+        """
+        src_hash, kwargs_hash = self._transcription_cache_keys(source_audio, enable_diarization)
+        if self._cache is not None:
+            cached = self._cache.get_transcription(src_hash, kwargs_hash)
+            if cached is not None:
+                return cached
+
+        if self._transcriber is None or self._transcriber_diarization != enable_diarization:
+            self._init_transcriber(enable_diarization=enable_diarization)
+            self._transcriber_diarization = enable_diarization
+
+        transcription = self._transcriber.transcribe(source_audio)
+        self._maybe_unload("_transcriber")
+
+        if self._cache is not None:
+            self._cache.put_transcription(
+                src_hash,
+                kwargs_hash,
+                transcription,
+                hash_inputs={
+                    "whisper_model": self.whisper_model,
+                    "enable_diarization": enable_diarization,
+                    "condition_on_previous_text": self.condition_on_previous_text,
+                    "no_speech_threshold": self.no_speech_threshold,
+                    "logprob_threshold": self.logprob_threshold,
+                },
+            )
+        return transcription
+
+    def _tts_segment_audio(
+        self,
+        segment: TranslatedSegment,
+        speaker: str,
+        speaker_bytes: bytes | None,
+        target_lang: str,
+        voice_clone: bool,
+        voice_samples: dict[str, Audio],
+        speaker_wav_paths: dict[str, Path],
+        src_hash_for_tts: str,
+    ) -> Audio | None:
+        """Produce the TTS audio for a single segment, with cache-around-the-call.
+
+        Returns the synthesized :class:`Audio`, or ``None`` if Chatterbox
+        crashed on the segment (the caller skips it). On cache miss the
+        TTS model is lazy-initialized and the per-speaker temp WAV is
+        materialized before generation; on cache hit none of that runs,
+        so a fully-cached run never loads Chatterbox.
+        """
+        from videopython.base.audio import Audio as _Audio
+
+        tts_cache_key: str | None = None
+        if self._cache is not None:
+            tts_cache_key = DubCache.tts_key(
+                translated_text=segment.translated_text,
+                voice_sample_bytes=speaker_bytes,
+                language=target_lang,
+            )
+            cached_path = self._cache.get_tts_path(src_hash_for_tts, tts_cache_key)
+            if cached_path is not None:
+                return _Audio.from_path(cached_path)
+
+        # Cache miss: pay for TTS init + voice-sample WAV exactly once
+        # across the loop. Both are wasted work when every segment hits.
+        if self._tts is None or self._tts_language != target_lang:
+            self._init_tts(language=target_lang)
+            self._tts_language = target_lang
+        if voice_clone and speaker not in speaker_wav_paths and speaker in voice_samples:
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                voice_samples[speaker].save(f.name)
+                speaker_wav_paths[speaker] = Path(f.name)
+
+        wav_path = speaker_wav_paths.get(speaker) if voice_clone else None
+        try:
+            if wav_path is not None:
+                dubbed_audio = self._tts.generate_audio(segment.translated_text, voice_sample_path=wav_path)
+            else:
+                dubbed_audio = self._tts.generate_audio(segment.translated_text)
+        except Exception as exc:
+            # Chatterbox occasionally crashes on short translated text
+            # (alignment_stream_analyzer indexing on tensors with <=5
+            # speech tokens). One bad segment shouldn't lose a long
+            # multi-hour run — log and let the caller skip.
+            logger.warning(
+                "TTS failed for segment (speaker=%s, text=%r): %s — skipping",
+                speaker,
+                segment.translated_text,
+                exc,
+            )
+            return None
+
+        if self._cache is not None and tts_cache_key is not None:
+            dubbed_audio.save(self._cache.reserve_tts_path(src_hash_for_tts, tts_cache_key))
+        return dubbed_audio
+
+    def _translate_with_cache(
+        self,
+        transcription: Transcription,
+        source_audio: Audio,
+        source_lang: str,
+        target_lang: str,
+        report_progress: Callable[[str, float], None],
+    ) -> tuple[list[TranslatedSegment], list[int]]:
+        """Run translation with cache-around-the-call.
+
+        Returns ``(translated_segments, translation_failures)``. Only
+        fully-successful translations are cached — partial Qwen failures
+        would otherwise lock in an incomplete dub across runs. The
+        progress callback maps the backend's [0, 1] fraction onto the
+        pipeline's translation window (0.35 → 0.50).
+        """
+        from videopython.ai.dubbing.models import TranslatedSegment
+
+        cache_key: str | None = None
+        if self._cache is not None:
+            cache_key = DubCache.translation_key(
+                source_lang=source_lang,
+                target_lang=target_lang,
+                translator_class=self._resolved_translator_class_name(source_lang, target_lang),
+            )
+            cached = self._cache.get_translation(DubCache.source_key(source_audio), cache_key)
+            if cached is not None:
+                return [TranslatedSegment.from_dict(d) for d in cached], []
+
+        if self._translator is None:
+            self._init_translator(source_lang=source_lang, target_lang=target_lang)
+
+        # Translation stage spans 0.35 → 0.50 of overall pipeline progress.
+        # MarianMT runs sequentially over 8-segment batches; on a 15-min
+        # source that's minutes of silent dwell on 0.35 without per-batch
+        # ticks. Map the [0,1] translation fraction onto that 15% window.
+        def _on_translation_progress(fraction: float) -> None:
+            clamped = max(0.0, min(1.0, fraction))
+            report_progress(f"Translating text ({int(clamped * 100)}%)", 0.35 + 0.15 * clamped)
+
+        translated_segments = self._translator.translate_segments(
+            segments=transcription.segments,
+            target_lang=target_lang,
+            source_lang=source_lang,
+            progress_callback=_on_translation_progress,
+        )
+        # Capture per-segment failures (always empty for Marian) before
+        # _maybe_unload nukes the backend in low_memory mode.
+        translation_failures = list(self._translator.translation_failures)
+        self._maybe_unload("_translator")
+
+        if self._cache is not None and cache_key is not None and not translation_failures:
+            self._cache.put_translation(
+                DubCache.source_key(source_audio),
+                cache_key,
+                [s.to_dict() for s in translated_segments],
+            )
+
+        return translated_segments, translation_failures
+
+    def _transcription_cache_keys(self, source_audio: Audio, enable_diarization: bool = False) -> tuple[str, str]:
+        """Return ``(src_hash, kwargs_hash)`` for the current transcription config.
+
+        Centralizes the kwarg list so the cache lookup, the put, and any
+        future invalidator agree on what's hashed.
+        """
+        src_hash = DubCache.source_key(source_audio)
+        kwargs_hash = DubCache.transcription_kwargs_hash(
+            whisper_model=self.whisper_model,
+            enable_diarization=enable_diarization,
+            condition_on_previous_text=self.condition_on_previous_text,
+            no_speech_threshold=self.no_speech_threshold,
+            logprob_threshold=self.logprob_threshold,
+        )
+        return src_hash, kwargs_hash
+
     def _init_transcriber(self, enable_diarization: bool = False) -> None:
         """Initialize the transcription model."""
         from videopython.ai.understanding.audio import AudioToText
@@ -158,6 +397,31 @@ class LocalDubbingPipeline:
         else:  # "auto"
             self._translator = self._resolve_translator_auto(source_lang, target_lang)
 
+    def _resolved_translator_class_name(self, source_lang: str, target_lang: str) -> str:
+        """Return the *class name* of the translator that ``_init_translator``
+        would pick — without constructing one.
+
+        Used by the cache to key translations on the resolved backend rather
+        than the user-supplied ``"auto"``: a CPU run that resolves to Marian
+        must not collide with a GPU run that resolves to Qwen.
+        """
+        if self.translator == "marian":
+            return "MarianTranslator"
+        if self.translator == "qwen3":
+            return "Qwen3Translator"
+        # auto — mirror _resolve_translator_auto's branching, no construction.
+        device = select_device(self.device, mps_allowed=True)
+        has_gpu = device in ("cuda", "mps")
+        if has_gpu and Qwen3Translator.supports(source_lang, target_lang):
+            return "Qwen3Translator"
+        if MarianTranslator.has_model_for(source_lang, target_lang):
+            return "MarianTranslator"
+        if Qwen3Translator.supports(source_lang, target_lang):
+            return "Qwen3Translator"
+        # No backend supports the pair — _init_translator will raise. We
+        # return a sentinel; the cache miss path will pay that cost.
+        return "Unsupported"
+
     def _resolve_translator_auto(self, source_lang: str, target_lang: str) -> TranslationBackend:
         """Pick a backend based on language coverage AND device.
 
@@ -417,12 +681,7 @@ class LocalDubbingPipeline:
                 )
         else:
             report_progress("Transcribing audio", 0.05)
-            if self._transcriber is None or self._transcriber_diarization != enable_diarization:
-                self._init_transcriber(enable_diarization=enable_diarization)
-                self._transcriber_diarization = enable_diarization
-
-            transcription = self._transcriber.transcribe(source_audio)
-            self._maybe_unload("_transcriber")
+            transcription = self._transcribe_with_cache(source_audio, enable_diarization)
 
         if not transcription.segments:
             return DubbingResult(
@@ -495,50 +754,29 @@ class LocalDubbingPipeline:
         del vocal_audio
 
         report_progress("Translating text", 0.35)
-        if self._translator is None:
-            self._init_translator(source_lang=detected_lang, target_lang=target_lang)
-
-        # Translation stage spans 0.35 → 0.50 of overall pipeline progress.
-        # MarianMT runs sequentially over 8-segment batches; on a 15-min
-        # source that's minutes of silent dwell on 0.35 without per-batch
-        # ticks. Map the [0,1] translation fraction onto that 15% window.
-        def _on_translation_progress(fraction: float) -> None:
-            clamped = max(0.0, min(1.0, fraction))
-            report_progress(f"Translating text ({int(clamped * 100)}%)", 0.35 + 0.15 * clamped)
-
-        translated_segments = self._translator.translate_segments(
-            segments=transcription.segments,
-            target_lang=target_lang,
-            source_lang=detected_lang,
-            progress_callback=_on_translation_progress,
+        translated_segments, translation_failures = self._translate_with_cache(
+            transcription, source_audio, detected_lang, target_lang, report_progress
         )
-        # Capture per-segment failures (always empty for Marian) before
-        # _maybe_unload nukes the backend in low_memory mode.
-        translation_failures = list(self._translator.translation_failures)
-        self._maybe_unload("_translator")
 
         report_progress("Generating dubbed speech", 0.50)
-        if self._tts is None or self._tts_language != target_lang:
-            self._init_tts(language=target_lang)
-            self._tts_language = target_lang
+
+        # Per-speaker voice-sample bytes for TTS cache key. Empty when
+        # voice_clone=False — the cache key still differentiates "no voice
+        # sample" from "specific clone" via the None path.
+        voice_sample_bytes: dict[str, bytes] = (
+            {speaker: sample.data.tobytes() for speaker, sample in voice_samples.items()} if voice_clone else {}
+        )
+        src_hash_for_tts = DubCache.source_key(source_audio) if self._cache is not None else ""
 
         dubbed_segments: list[Audio] = []
         target_durations: list[float] = []
         start_times: list[float] = []
 
-        # Encode each speaker's voice sample to a temp WAV exactly once and
-        # reuse the path across every segment for that speaker. Without this
-        # cache, TextToSpeech.generate_audio re-encodes the same voice sample
-        # on every call (one temp WAV write + delete per segment), which is
-        # pure overhead for long dubs with many segments per speaker.
+        # Per-speaker temp WAVs are materialized lazily by _tts_segment_audio
+        # so a fully-cached run never writes one. The dict is loop-scoped
+        # state so the finally block can clean up regardless of cache outcome.
         speaker_wav_paths: dict[str, Path] = {}
         try:
-            if voice_clone:
-                for speaker, sample in voice_samples.items():
-                    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
-                        sample.save(f.name)
-                        speaker_wav_paths[speaker] = Path(f.name)
-
             for i, segment in enumerate(translated_segments):
                 if segment.duration < 0.1:
                     continue
@@ -553,26 +791,17 @@ class LocalDubbingPipeline:
                 report_progress(f"Generating speech ({i + 1}/{len(translated_segments)})", progress)
 
                 speaker = segment.speaker or "speaker_0"
-                cached_path = speaker_wav_paths.get(speaker) if voice_clone else None
-
-                try:
-                    if cached_path is not None:
-                        dubbed_audio = self._tts.generate_audio(segment.translated_text, voice_sample_path=cached_path)
-                    else:
-                        dubbed_audio = self._tts.generate_audio(segment.translated_text)
-                except Exception as e:
-                    # Chatterbox occasionally crashes on short translated text
-                    # (alignment_stream_analyzer indexing on tensors with <=5
-                    # speech tokens). One bad segment shouldn't lose a long
-                    # multi-hour run — log and skip so the rest proceeds.
-                    logger.warning(
-                        "TTS failed for segment %d/%d (speaker=%s, text=%r): %s — skipping",
-                        i + 1,
-                        len(translated_segments),
-                        speaker,
-                        segment.translated_text,
-                        e,
-                    )
+                dubbed_audio = self._tts_segment_audio(
+                    segment=segment,
+                    speaker=speaker,
+                    speaker_bytes=voice_sample_bytes.get(speaker),
+                    target_lang=target_lang,
+                    voice_clone=voice_clone,
+                    voice_samples=voice_samples,
+                    speaker_wav_paths=speaker_wav_paths,
+                    src_hash_for_tts=src_hash_for_tts,
+                )
+                if dubbed_audio is None:
                     continue
 
                 dubbed_segments.append(dubbed_audio)
@@ -611,10 +840,10 @@ class LocalDubbingPipeline:
         else:
             final_audio = dubbed_speech
 
-        # Peak-match against the source so the dub doesn't land quieter
-        # than the original. Done last so it captures both vocals+background
-        # mixes and speech-only outputs uniformly.
-        final_audio = _peak_match(final_audio, source_audio)
+        # Loudness-match against the source so the dub doesn't land
+        # perceptually thinner than the original. Done last so it captures
+        # both vocals+background mixes and speech-only outputs uniformly.
+        final_audio = _loudness_match(final_audio, source_audio)
 
         report_progress("Complete", 1.0)
 
@@ -733,7 +962,7 @@ class LocalDubbingPipeline:
         else:
             final_audio = generated_speech
 
-        final_audio = _peak_match(final_audio, source_audio)
+        final_audio = _loudness_match(final_audio, source_audio)
 
         report_progress("Complete", 1.0)
 

{videopython-0.28.1 → videopython-0.28.2}/src/videopython/ai/dubbing/remux.py

@@ -21,25 +21,45 @@ class RemuxError(RuntimeError):
     """ffmpeg failed while replacing an audio stream."""
 
 
+def _build_stream_maps(keep_original_audio: bool) -> list[str]:
+    """ffmpeg ``-map`` flags for the video + audio + subtitle streams.
+
+    Convention: dubbed audio (input 1) is the *first* audio track so default
+    playback uses it; original audio (input 0) tags onto the back when
+    ``keep_original_audio=True`` for editorial A/B. Subtitles from input 0
+    are carried with ``?`` so sources without subs don't fail the mux.
+    """
+    maps = ["-map", "0:v:0", "-map", "1:a:0"]
+    if keep_original_audio:
+        maps += ["-map", "0:a?"]
+    maps += ["-map", "0:s?"]
+    return maps
+
+
 def replace_audio_stream(
     video_path: str | Path,
     audio_path: str | Path,
     output_path: str | Path,
     audio_codec: str = "aac",
     audio_bitrate: str = "192k",
+    keep_original_audio: bool = False,
 ) -> None:
     """Copy ``video_path``'s video stream and mux in ``audio_path`` as the audio track.
 
     Uses ffmpeg stream-copy for video (no re-encode) and encodes audio to AAC.
-    ``-shortest`` trims to the shorter of the two streams so the output duration
-    matches the source video when the dubbed audio is slightly longer.
+    Subtitle streams from ``video_path`` are carried through unchanged
+    (stream-copy). ``-shortest`` trims to the shorter of the two streams so
+    the output duration matches the source video when the dubbed audio is
+    slightly longer.
 
     Args:
-        video_path: Source video file (video stream is copied unchanged).
-        audio_path: Audio file to use as the new audio track.
+        video_path: Source video file (video + subtitle streams are copied unchanged).
+        audio_path: Audio file to use as the new (default) audio track.
         output_path: Destination file. Overwritten if it exists.
         audio_codec: ffmpeg audio codec name. Defaults to ``aac`` (MP4-compatible).
         audio_bitrate: Audio bitrate passed to ffmpeg (``-b:a``).
+        keep_original_audio: If True, retain the source audio as a secondary
+            track behind the dubbed one. Useful for editorial A/B.
 
     Raises:
         FileNotFoundError: If ``video_path`` or ``audio_path`` does not exist.
@@ -61,16 +81,15 @@ def replace_audio_stream(
         str(video_path),
         "-i",
         str(audio_path),
-        "-map",
-        "0:v:0",
-        "-map",
-        "1:a:0",
+        *_build_stream_maps(keep_original_audio),
         "-c:v",
         "copy",
         "-c:a",
         audio_codec,
         "-b:a",
         audio_bitrate,
+        "-c:s",
+        "copy",
         "-shortest",
         str(output_path),
     ]
@@ -87,20 +106,24 @@ def replace_audio_stream_from_audio(
     output_path: str | Path,
     audio_codec: str = "aac",
     audio_bitrate: str = "192k",
+    keep_original_audio: bool = False,
 ) -> None:
     """Like ``replace_audio_stream`` but takes an in-memory ``Audio`` and pipes WAV to ffmpeg.
 
     Avoids the ``Audio.save -> read-from-disk -> ffmpeg`` round-trip used by
     the path-based variant: we serialize the WAV in memory and feed it to
     ffmpeg via stdin. For long dubs this saves a full WAV write+read of the
-    output audio (~10 GB for a 2h source).
+    output audio (~10 GB for a 2h source). Subtitle streams from
+    ``video_path`` are carried through unchanged (stream-copy).
 
     Args:
-        video_path: Source video file (video stream is copied unchanged).
-        audio: ``Audio`` instance to mux in as the new audio track.
+        video_path: Source video file (video + subtitle streams are copied unchanged).
+        audio: ``Audio`` instance to mux in as the new (default) audio track.
         output_path: Destination file. Overwritten if it exists.
         audio_codec: ffmpeg audio codec name. Defaults to ``aac``.
         audio_bitrate: Audio bitrate passed to ffmpeg (``-b:a``).
+        keep_original_audio: If True, retain the source audio as a secondary
+            track behind the dubbed one. Useful for editorial A/B.
 
     Raises:
         FileNotFoundError: If ``video_path`` does not exist.
@@ -133,16 +156,15 @@ def replace_audio_stream_from_audio(
         "wav",
         "-i",
         "-",
-        "-map",
-        "0:v:0",
-        "-map",
-        "1:a:0",
+        *_build_stream_maps(keep_original_audio),
         "-c:v",
         "copy",
         "-c:a",
         audio_codec,
         "-b:a",
         audio_bitrate,
+        "-c:s",
+        "copy",
         "-shortest",
         str(output_path),
     ]