videopython 0.28.1__tar.gz → 0.28.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.28.1
+Version: 0.28.3
 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.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.28.1"
+version = "0.28.3"
 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.3}/src/videopython/ai/dubbing/__init__.py

@@ -1,7 +1,14 @@
 """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.models import (
+    DubbingResult,
+    Expressiveness,
+    RevoiceResult,
+    SeparatedAudio,
+    TranslatedSegment,
+)
 from videopython.ai.dubbing.pipeline import LocalDubbingPipeline
 from videopython.ai.dubbing.quality import GarbageTranscriptError, TranscriptQuality, assess_transcript
 from videopython.ai.dubbing.timing import TimingSynchronizer
@@ -19,4 +26,7 @@ __all__ = [
     "TranscriptQuality",
     "assess_transcript",
     "UnsupportedLanguageError",
+    "DubCache",
+    "dub_cache_clear",
+    "Expressiveness",
 ]

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

@@ -0,0 +1,309 @@
+"""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,
+        exaggeration: float | None = None,
+        cfg_weight: float | None = None,
+        temperature: float | None = None,
+    ) -> str:
+        """Per-segment key over text + voice sample + language + expressiveness.
+
+        ``exaggeration`` / ``cfg_weight`` / ``temperature`` are the M4
+        Chatterbox knobs. Defaulting to ``None`` keeps pre-M4 callers that
+        omit them hashing the same way (no-knob profile collides with
+        absent kwargs), so cache invalidation is driven by *passing
+        non-None values*, not by the M4 code path being present.
+        """
+        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"))
+        for knob in (exaggeration, cfg_weight, temperature):
+            h.update(b"\x00")
+            h.update(repr(knob).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.3}/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.3}/src/videopython/ai/dubbing/models.py

@@ -19,6 +19,42 @@ if TYPE_CHECKING:
 CLEAN_SPEED_TOLERANCE = 0.01
 
 
+@dataclass(frozen=True)
+class Expressiveness:
+    """Chatterbox ``generate()`` knobs derived from source-segment prosody.
+
+    ``None`` on any field means "let Chatterbox use its own default" —
+    avoids pinning the dub against future Chatterbox default changes.
+
+    Attributes:
+        exaggeration: Emotional intensity. Chatterbox default ``0.5``;
+            ``0.7+`` produces dramatic output.
+        cfg_weight: Classifier-free guidance weight. Chatterbox default
+            ``0.5``; lower values (~``0.3``) slow pacing.
+        temperature: Sampling temperature. Chatterbox default ``0.8``.
+    """
+
+    exaggeration: float | None = None
+    cfg_weight: float | None = None
+    temperature: float | None = None
+
+    def as_kwargs(self) -> dict[str, float]:
+        """Knobs as a dict, dropping ``None`` entries.
+
+        Suitable for ``**``-expansion into Chatterbox or
+        :meth:`DubCache.tts_key`.
+        """
+        return {
+            name: value
+            for name, value in (
+                ("exaggeration", self.exaggeration),
+                ("cfg_weight", self.cfg_weight),
+                ("temperature", self.temperature),
+            )
+            if value is not None
+        }
+
+
 @dataclass
 class TranslatedSegment:
     """A segment of translated text with timing information.
@@ -59,6 +95,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: