videopython 0.42.0__tar.gz → 0.43.1__tar.gz

{videopython-0.42.0 → videopython-0.43.1}/.gitignore

@@ -148,3 +148,10 @@ data/exported/*.mp4
 # Model weights
 *.pt
 
+# Sample / working videos (keep them out of the repo root)
+*.mp4
+!data/exported/example.mp4
+
+# Local scratch / sign-off artifacts
+libass_signoff/
+

{videopython-0.42.0 → videopython-0.43.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.42.0
+Version: 0.43.1
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -27,17 +27,12 @@ Requires-Dist: accelerate>=0.29.2; extra == 'ai'
 Requires-Dist: chatterbox-tts>=0.1.7; extra == 'ai'
 Requires-Dist: demucs>=4.0.0; extra == 'ai'
 Requires-Dist: diffusers>=0.30.0; extra == 'ai'
-Requires-Dist: hf-transfer>=0.1.9; extra == 'ai'
 Requires-Dist: imagehash>=4.3; extra == 'ai'
 Requires-Dist: llama-cpp-python>=0.3.0; extra == 'ai'
-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: qwen-vl-utils>=0.0.10; 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'
 Requires-Dist: silero-vad>=5.1; extra == 'ai'
 Requires-Dist: torch>=2.8.0; extra == 'ai'
@@ -45,6 +40,48 @@ Requires-Dist: torchaudio>=2.8.0; extra == 'ai'
 Requires-Dist: transformers>=5.2.0; extra == 'ai'
 Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'ai'
 Requires-Dist: ultralytics>=8.0.0; extra == 'ai'
+Provides-Extra: asr
+Requires-Dist: openai-whisper>=20240930; extra == 'asr'
+Requires-Dist: pyannote-audio>=4.0.0; extra == 'asr'
+Requires-Dist: silero-vad>=5.1; extra == 'asr'
+Requires-Dist: torch>=2.8.0; extra == 'asr'
+Requires-Dist: torchaudio>=2.8.0; extra == 'asr'
+Provides-Extra: dub
+Requires-Dist: demucs>=4.0.0; extra == 'dub'
+Requires-Dist: llama-cpp-python>=0.3.0; extra == 'dub'
+Requires-Dist: openai-whisper>=20240930; extra == 'dub'
+Requires-Dist: pyannote-audio>=4.0.0; extra == 'dub'
+Requires-Dist: pyloudnorm>=0.1.1; extra == 'dub'
+Requires-Dist: sentencepiece>=0.1.99; extra == 'dub'
+Requires-Dist: silero-vad>=5.1; extra == 'dub'
+Requires-Dist: torch>=2.8.0; extra == 'dub'
+Requires-Dist: torchaudio>=2.8.0; extra == 'dub'
+Requires-Dist: transformers>=5.2.0; extra == 'dub'
+Provides-Extra: generation
+Requires-Dist: accelerate>=0.29.2; extra == 'generation'
+Requires-Dist: diffusers>=0.30.0; extra == 'generation'
+Requires-Dist: torch>=2.8.0; extra == 'generation'
+Requires-Dist: torchaudio>=2.8.0; extra == 'generation'
+Requires-Dist: transformers>=5.2.0; extra == 'generation'
+Provides-Extra: separation
+Requires-Dist: demucs>=4.0.0; extra == 'separation'
+Requires-Dist: torch>=2.8.0; extra == 'separation'
+Requires-Dist: torchaudio>=2.8.0; extra == 'separation'
+Provides-Extra: translation
+Requires-Dist: llama-cpp-python>=0.3.0; extra == 'translation'
+Requires-Dist: sentencepiece>=0.1.99; extra == 'translation'
+Requires-Dist: torch>=2.8.0; extra == 'translation'
+Requires-Dist: transformers>=5.2.0; extra == 'translation'
+Provides-Extra: tts
+Requires-Dist: chatterbox-tts>=0.1.7; extra == 'tts'
+Provides-Extra: vision
+Requires-Dist: imagehash>=4.3; extra == 'vision'
+Requires-Dist: qwen-vl-utils>=0.0.10; extra == 'vision'
+Requires-Dist: torch>=2.8.0; extra == 'vision'
+Requires-Dist: torchaudio>=2.8.0; extra == 'vision'
+Requires-Dist: transformers>=5.2.0; extra == 'vision'
+Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'vision'
+Requires-Dist: ultralytics>=8.0.0; extra == 'vision'
 Description-Content-Type: text/markdown
 
 # videopython
@@ -64,9 +101,11 @@ Full documentation: [videopython.com](https://videopython.com)
 ```bash
 # Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
 pip install videopython          # core video/audio editing
-pip install "videopython[ai]"    # + local AI features (GPU recommended)
+pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
+AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
+
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.42.0 → videopython-0.43.1}/README.md

@@ -15,9 +15,11 @@ Full documentation: [videopython.com](https://videopython.com)
 ```bash
 # Install FFmpeg first (macOS: brew install ffmpeg | Debian: apt-get install ffmpeg)
 pip install videopython          # core video/audio editing
-pip install "videopython[ai]"    # + local AI features (GPU recommended)
+pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
+AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
+
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.42.0 → videopython-0.43.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.42.0"
+version = "0.43.1"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -53,81 +53,90 @@ dev = [
     "mkdocstrings>=1.0.0",
     "mkdocstrings-python>=2.0.1",
 ]
-ai = [
-    "accelerate>=0.29.2",
-    "diffusers>=0.30.0",
-    "hf-transfer>=0.1.9",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-    "transformers>=5.2.0",
+# Thin dev-workflow group so `uv sync` / uv.lock keep working. Resolves the
+# SAME set as the aggregate `[ai]` extra below via a PEP 508 self-reference, so
+# there is a single source of truth (the granular extras) and no hand-sync.
+# `test_packaging_extras.py` asserts this stays consistent with the extra.
+ai = ["videopython[ai]"]
+
+# pip install videopython[<extra>] - pip uses optional-dependencies, not dependency-groups.
+#
+# Granular extras partition the heavy ML deps by the leaf module that imports
+# them, so consumers install only what a capability needs. `ai` is a convenience
+# aggregate that installs EVERYTHING via PEP 685 self-references (no hand-sync).
+# `test_packaging_extras.py` enforces union(granular) == ai as a drift guard.
+[project.optional-dependencies]
+# Speech recognition / diarization (understanding/audio.py).
+asr = [
     "openai-whisper>=20240930",
     "pyannote-audio>=4.0.0",
     # Voice activity detection (used by AudioToText to gate Whisper language detection)
     "silero-vad>=5.1",
-    "numba>=0.61.0",
-    "ollama>=0.4.5",
-    "scipy>=1.10.0",
-    "scikit-learn>=1.3.0",
-    # Detection backends
+    "torch>=2.8.0",
+    "torchaudio>=2.8.0",
+]
+# Visual understanding: detection, scene/temporal, VLM (understanding/{faces,
+# objects,temporal,image}.py + video_analysis). transformers also backs the AST
+# AudioClassifier and the SceneVLM; qwen-vl-utils is the SceneVLM preprocessor;
+# imagehash is the SceneVLM frame-dedup; transnetv2 is scene detection.
+vision = [
     "ultralytics>=8.0.0",
-    # Audio classification (AST via transformers - no separate dep needed)
-    # Scene detection
     "transnetv2-pytorch>=1.0.5",
-    # Voice cloning TTS (Chatterbox Multilingual by Resemble AI)
-    "chatterbox-tts>=0.1.7",
-    # Translation (Marian MT tokenizer requires sentencepiece)
-    "sentencepiece>=0.1.99",
-    # Audio source separation
-    "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",
-    # Vision-language preprocessing for Qwen3.5 (M5) - documented prerequisite
-    # for AutoModelForImageTextToText with image/video chat templates.
+    "transformers>=5.2.0",
     "qwen-vl-utils>=0.0.10",
-    # Perceptual hashing for SceneVLM frame dedup (M5)
     "imagehash>=4.3",
+    "torch>=2.8.0",
+    "torchaudio>=2.8.0",
 ]
-
-# Required for pip install videopython[ai] - pip uses optional-dependencies, not dependency-groups
-[project.optional-dependencies]
-ai = [
-    "accelerate>=0.29.2",
-    "diffusers>=0.30.0",
-    "hf-transfer>=0.1.9",
+# Audio source separation (understanding/separation.py).
+separation = [
+    "demucs>=4.0.0",
     "torch>=2.8.0",
     "torchaudio>=2.8.0",
+]
+# Text translation backends (generation/translation.py MarianMT +
+# generation/qwen3.py Qwen3 GGUF). MarianTokenizer requires sentencepiece.
+translation = [
     "transformers>=5.2.0",
-    "openai-whisper>=20240930",
-    "pyannote-audio>=4.0.0",
-    # Voice activity detection (used by AudioToText to gate Whisper language detection)
-    "silero-vad>=5.1",
-    "numba>=0.61.0",
-    "ollama>=0.4.5",
-    "scipy>=1.10.0",
-    "scikit-learn>=1.3.0",
-    # Detection backends
-    "ultralytics>=8.0.0",
-    # Audio classification (AST via transformers - no separate dep needed)
-    # Scene detection
-    "transnetv2-pytorch>=1.0.5",
-    # Voice cloning TTS (Chatterbox Multilingual by Resemble AI)
-    "chatterbox-tts>=0.1.7",
-    # Translation (Marian MT tokenizer requires sentencepiece)
     "sentencepiece>=0.1.99",
-    # Audio source separation
-    "demucs>=4.0.0",
-    # Translation backend: Qwen3 GGUF inference (M2)
     "llama-cpp-python>=0.3.0",
+    "torch>=2.8.0",
+]
+# Voice cloning TTS (generation/audio.py — Chatterbox Multilingual by Resemble
+# AI). ISOLATED: chatterbox-tts 0.1.7 carries the strict pins that force the
+# [tool.uv].override-dependencies block. This is the ONLY extra that drags them.
+# Left to chatterbox's own torch==2.6.0 / torchaudio==2.6.0 pins (no floors
+# here) so `pip install videopython[tts]` resolves STANDALONE in its own
+# image/Modal function -- the whole point of running TTS behind SpeechBackend.
+# The all-in [ai] resolve forces torch>=2.8.0 over this via override-dependencies.
+tts = [
+    "chatterbox-tts>=0.1.7",
+]
+# Local media generation: SDXL/CogVideoX (generation/{image,video}.py) +
+# MusicGen (generation/audio.py TextToMusic, via transformers).
+generation = [
+    "diffusers>=0.30.0",
+    "transformers>=5.2.0",
+    "accelerate>=0.29.2",
+    "torch>=2.8.0",
+    "torchaudio>=2.8.0",
+]
+# Dubbing pipeline's hard top-level deps: transcription (asr) + source
+# separation (separation) + translation, plus BS.1770 loudness matching
+# (dubbing/loudness.py). Deliberately EXCLUDES tts/chatterbox: local synthesis
+# runs through the SpeechBackend protocol against a separately-installed [tts]
+# extra or an injected remote backend, so a [dub] image co-resolves WITHOUT
+# chatterbox's override-forcing pin. A bare [dub] install that hits local
+# synthesis raises a clear [tts]-pointing ImportError.
+dub = [
+    "videopython[asr,separation,translation]",
     # Loudness measurement (BS.1770) for dub-vs-source loudness matching (M3)
     "pyloudnorm>=0.1.1",
-    # Vision-language preprocessing for Qwen3.5 (M5) - documented prerequisite
-    # for AutoModelForImageTextToText with image/video chat templates.
-    "qwen-vl-utils>=0.0.10",
-    # Perceptual hashing for SceneVLM frame dedup (M5)
-    "imagehash>=4.3",
 ]
+# Convenience aggregate: installs every capability. PEP 685 self-references make
+# this the single "everything" install with no hand-duplicated dep list. This
+# combined resolve is what the [tool.uv].override-dependencies block exists for.
+ai = ["videopython[asr,vision,separation,translation,tts,generation,dub]"]
 
 [project.urls]
 Homepage = "https://videopython.com"
@@ -163,11 +172,16 @@ module = [
 ignore_missing_imports = true
 
 [tool.uv]
-# chatterbox-tts 0.1.7 pins strict versions of torch, torchaudio, numpy, and
-# diffusers that conflict with pyannote-audio (torch>=2.8) and CogVideoX
-# (diffusers>=0.30). Override to let the resolver pick compatible versions.
-# The ai dependency floors are aligned with these overrides to keep pip and uv
-# resolving similar versions.
+# LOAD-BEARING ONLY for the all-in `[ai]` resolve (every extra installed
+# together, as in dev/CI and `uv sync`). chatterbox-tts 0.1.7 (the `[tts]`
+# extra) pins strict torch/torchaudio/numpy/diffusers that conflict with
+# pyannote-audio (torch>=2.8, `[asr]`) and CogVideoX (diffusers>=0.30,
+# `[generation]`). This override lets the combined resolver pick compatible
+# versions. A consumer installing a SUBSET that excludes chatterbox — notably
+# `[dub]` (asr+separation+translation+pyloudnorm, no tts) — co-resolves cleanly
+# WITHOUT this override; that clean `[dub]` resolve is the whole point of
+# isolating `[tts]`. The ai dependency floors are aligned with these overrides
+# to keep pip and uv resolving similar versions.
 override-dependencies = [
     "torch>=2.8.0", "torchaudio>=2.8.0", "numpy>=2.0.0", "diffusers>=0.30.0",
     # ultralytics depends on opencv-python which conflicts with our

videopython-0.43.1/src/videopython/ai/__init__.py

@@ -0,0 +1,82 @@
+"""AI-powered generation, understanding, dubbing, and analysis.
+
+Every public symbol is re-exported lazily via PEP 562 ``__getattr__`` so that
+``import videopython.ai`` (or ``from videopython.ai import X``) loads ONLY the
+leaf module backing the requested symbol — not every sibling. This is what
+makes the granular extras (``asr``, ``vision``, ``tts``, ``generation``,
+``dub``, ...) usable: with only ``[asr]`` installed, ``from videopython.ai
+import AudioToText`` works, while touching ``TextToSpeech`` raises a clear
+``[tts]``-pointing ``ImportError`` at attribute access instead of failing the
+whole package import.
+
+The ``TYPE_CHECKING`` block below keeps the eager imports visible to mypy and
+IDEs (static autocompletion / re-export checking) without executing them at
+runtime.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Redundant aliases mark these as intentional re-exports (mypy/IDE see the
+    # symbols; ruff doesn't flag them as unused). Runtime resolution is lazy via
+    # __getattr__ below.
+    from .effects import ObjectDetectionOverlay as ObjectDetectionOverlay
+    from .generation import ImageToVideo as ImageToVideo
+    from .generation import TextToImage as TextToImage
+    from .generation import TextToMusic as TextToMusic
+    from .generation import TextToSpeech as TextToSpeech
+    from .generation import TextToVideo as TextToVideo
+    from .transforms import FaceTrackingCrop as FaceTrackingCrop
+    from .understanding import AudioClassifier as AudioClassifier
+    from .understanding import AudioToText as AudioToText
+    from .understanding import FaceTracker as FaceTracker
+    from .understanding import ObjectDetector as ObjectDetector
+    from .understanding import SceneVLM as SceneVLM
+    from .understanding import SemanticSceneDetector as SemanticSceneDetector
+    from .video_analysis import VideoAnalysis as VideoAnalysis
+    from .video_analysis import VideoAnalysisConfig as VideoAnalysisConfig
+    from .video_analysis import VideoAnalyzer as VideoAnalyzer
+
+# Public symbol -> submodule (relative to this package) that defines it. The
+# submodule's own (lazy) __init__ resolves the symbol; we only import the
+# submodule, never its siblings.
+_SYMBOL_MODULES: dict[str, str] = {
+    # Generation
+    "TextToVideo": ".generation",
+    "ImageToVideo": ".generation",
+    "TextToImage": ".generation",
+    "TextToSpeech": ".generation",
+    "TextToMusic": ".generation",
+    # Understanding
+    "AudioToText": ".understanding",
+    "AudioClassifier": ".understanding",
+    "FaceTracker": ".understanding",
+    "ObjectDetector": ".understanding",
+    "SceneVLM": ".understanding",
+    "SemanticSceneDetector": ".understanding",
+    # Transforms (AI-powered)
+    "FaceTrackingCrop": ".transforms",
+    # Effects (AI-powered)
+    "ObjectDetectionOverlay": ".effects",
+    # Video analysis
+    "VideoAnalysis": ".video_analysis",
+    "VideoAnalysisConfig": ".video_analysis",
+    "VideoAnalyzer": ".video_analysis",
+}
+
+__all__ = list(_SYMBOL_MODULES)
+
+
+def __getattr__(name: str) -> object:
+    module_name = _SYMBOL_MODULES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(module_name, __name__)
+    return getattr(module, name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

videopython-0.43.1/src/videopython/ai/_optional.py

@@ -0,0 +1,47 @@
+"""Helpers for guarding optional heavy-dependency imports.
+
+Every heavy ML dependency in ``videopython.ai`` is imported lazily inside the
+method that needs it (there are no top-level ``import torch``/``transformers``/
+``chatterbox`` statements anywhere under ``ai/``). That keeps leaf modules
+importable on a slim install: importing ``ai.understanding.objects`` only needs
+core deps until a detector is actually constructed.
+
+The granular extras (``asr``, ``vision``, ``tts``, ...) partition those heavy
+deps. When a user installs only one extra and reaches a code path needing a dep
+from another, the bare ``import`` would raise a stock ``ModuleNotFoundError``
+with no hint about which extra restores it. :func:`require` wraps the import and
+turns that into an actionable ``ImportError`` pointing at the right
+``pip install 'videopython[<extra>]'``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+
+
+def require(module: str, extra: str, *, feature: str | None = None) -> ModuleType:
+    """Import ``module`` or raise a clear, extra-pointing ``ImportError``.
+
+    Args:
+        module: Dotted module name to import (e.g. ``"chatterbox.mtl_tts"``,
+            ``"torch"``). The fully-imported module object is returned so the
+            call site can bind the symbols it needs.
+        extra: The videopython extra that ships ``module`` (e.g. ``"tts"``,
+            ``"asr"``). Surfaced verbatim in the install hint.
+        feature: Optional human-readable feature name for the message head. When
+            omitted the top-level package of ``module`` is used.
+
+    Returns:
+        The imported module object.
+
+    Raises:
+        ImportError: If ``module`` cannot be imported. The message always
+            contains the extra name and a ``pip install 'videopython[<extra>]'``
+            hint so the caller knows exactly how to fix it.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        label = feature or module.split(".")[0]
+        raise ImportError(f"{label} requires the '{extra}' extra: pip install 'videopython[{extra}]'") from exc

videopython-0.43.1/src/videopython/ai/_predictor.py

@@ -0,0 +1,54 @@
+"""Context-manager mixin for VRAM-releasing predictors.
+
+Every predictor under ``videopython.ai`` already exposes an ``unload()`` method
+that drops its model reference (``self._model = None``, plus any processor /
+pipeline fields) and calls :func:`videopython.ai._device.release_device_memory`
+to free the allocator cache. Today that has to be called by hand -- the dubbing
+pipeline, for example, unloads each stage manually once it is done.
+
+:class:`ManagedPredictor` makes that bookkeeping automatic by turning any such
+predictor into a context manager::
+
+    with SceneVLM(...) as vlm:
+        ...  # use vlm
+    # vlm.unload() has fired here, releasing VRAM
+
+The mixin is deliberately tiny and dependency-free: it imports no torch /
+transformers / ultralytics and holds no state, so it is safe to mix into any
+predictor class regardless of how it is constructed.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class ManagedPredictor:
+    """Adds ``with``-statement support that calls ``unload()`` on exit.
+
+    Subclasses MUST define their own ``unload()`` method; this mixin does not
+    provide one. The expected contract is the one shared by every predictor in
+    ``videopython.ai``: ``unload()`` clears the model reference(s) and releases
+    device memory, and is safe to call more than once (including before the
+    model was ever loaded).
+
+    ``__exit__`` always returns ``False`` so exceptions raised inside the ``with``
+    block are never suppressed -- ``unload()`` runs on both the success and
+    failure paths.
+    """
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        self.unload()  # type: ignore[attr-defined]
+        return False

videopython-0.43.1/src/videopython/ai/_revisions.py

@@ -0,0 +1,109 @@
+"""Centralized HuggingFace model-revision pins.
+
+The AI predictors load weights via ``from_pretrained(...)``,
+``hf_hub_download(...)``, and ``YOLO(...)`` with no revision pinning by
+default, so a silent upstream weight change can alter production analysis
+without any code change on our side. This module maps each *fixed* model
+identifier to the commit SHA we want to pin to, so callers can pass
+``revision=pinned(model_id)`` to lock the download to a known-good commit.
+
+Resolution: each SHA below is the ``sha`` field returned by the HuggingFace
+model API (``https://huggingface.co/api/models/<repo_id>``), i.e. the latest
+commit on the repo's ``main`` branch at the time it was captured.
+
+Refreshing SHAs:
+    For each ``model_id`` in ``MODEL_REVISIONS`` (and the TODO list, if any),
+    fetch ``https://huggingface.co/api/models/<model_id>`` and copy the JSON
+    ``sha`` field into the dict. Bump deliberately -- the whole point of a pin
+    is that it does not move on its own. After editing, re-run the AI suite
+    so the new revision is exercised before release.
+
+Usage:
+    >>> from videopython.ai._revisions import pinned
+    >>> pinned("facebook/musicgen-small")  # -> "<sha>" or None
+    Pass the result straight through:
+    ``AutoProcessor.from_pretrained(model_id, revision=pinned(model_id))``.
+    ``revision=None`` is the library default and means "current behavior"
+    (track ``main``), so an unpinned or dynamic model stays safe.
+
+# ---------------------------------------------------------------------------
+# Unpinnable-by-design (intentionally absent from MODEL_REVISIONS)
+# ---------------------------------------------------------------------------
+# These load paths cannot be pinned to a HuggingFace commit SHA, so they are
+# documented here rather than registered above. ``pinned()`` returns None for
+# them, which leaves the caller on its current (unpinned) behavior.
+#
+#   * ultralytics YOLO asset -- ai/understanding/objects.py loads
+#     ``YOLO(self.model_name)`` (e.g. "yolov8n.pt"). Ultralytics resolves and
+#     downloads this from its own GitHub release assets, not from a HF repo,
+#     so there is no HF revision to pin. (The face detector in
+#     ai/understanding/faces.py is different: it pulls a YOLOv8 *checkpoint*
+#     from the HF repo ``arnabdhar/YOLOv8-Face-Detection`` via
+#     hf_hub_download, and that one IS pinned below.)
+#
+#   * Dynamic Marian pairs -- ai/generation/translation.py builds the model
+#     name per language pair at runtime (e.g. "Helsinki-NLP/opus-mt-en-de").
+#     The set of repos is open-ended (one per direction), so pinning each pair
+#     to a SHA is impractical and out of scope; left unpinned by design.
+#
+#   * Chatterbox internal load -- ai/generation/audio.py calls
+#     ``ChatterboxMultilingualTTS.from_pretrained(device=...)`` with no repo
+#     argument. The repo id + revision are resolved internally by the
+#     chatterbox package, so there is nothing for us to pass a ``revision`` to.
+#
+#   * openai-whisper CDN models -- ai/understanding/audio.py loads transcription
+#     weights via ``whisper.load_model(name="turbo", ...)`` (tiny/base/small/
+#     medium/large/turbo). openai-whisper downloads these from OpenAI's own CDN
+#     by name, NOT through a HF ``from_pretrained`` repo, so there is no HF
+#     commit SHA to pin. (The faster-whisper backend, if/when used, WOULD map to
+#     a HF repo and could be pinned -- this code path does not use it.)
+# ---------------------------------------------------------------------------
+"""
+
+from __future__ import annotations
+
+# Exact model-identifier string -> pinned commit SHA. The key must match the
+# literal value passed to from_pretrained/hf_hub_download at the call site so
+# ``pinned(model_id)`` resolves with a plain dict lookup. SHAs captured from
+# the HuggingFace model API (see module docstring for refresh instructions).
+MODEL_REVISIONS: dict[str, str] = {
+    # SceneVLM (ai/understanding/image.py: SCENE_VLM_MODEL_IDS)
+    "Qwen/Qwen3.5-4B": "851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a",
+    "Qwen/Qwen3.5-9B": "c202236235762e1c871ad0ccb60c8ee5ba337b9a",
+    "Qwen/Qwen3.5-27B": "fc05daec18b0a78c049392ed2e771dde82bdf654",
+    # Speaker diarization (ai/understanding/audio.py: PYANNOTE_DIARIZATION_MODEL).
+    # Gated repo (auto-approved); from_pretrained needs an accepted HF token.
+    "pyannote/speaker-diarization-community-1": "3533c8cf8e369892e6b79ff1bf80f7b0286a54ee",
+    # Audio event classifier (ai/understanding/audio.py: AudioClassifier)
+    "MIT/ast-finetuned-audioset-10-10-0.4593": "f826b80d28226b62986cc218e5cec390b1096902",
+    # Face detection checkpoint (ai/understanding/faces.py: hf_hub_download)
+    "arnabdhar/YOLOv8-Face-Detection": "52fa54977207fa4f021de949b515fb19dcab4488",
+    # Qwen3 translation GGUF (ai/generation/qwen3.py: DEFAULT_REPO_ID)
+    "unsloth/Qwen3-4B-Instruct-2507-GGUF": "a06e946bb6b655725eafa393f4a9745d460374c9",
+    # MusicGen (ai/generation/audio.py: TextToMusic)
+    "facebook/musicgen-small": "4c8334b02c6ec4e8664a91979669a501ec497792",
+    # SDXL (ai/generation/image.py: TextToImage)
+    "stabilityai/stable-diffusion-xl-base-1.0": "462165984030d82259a11f4367a4eed129e94a7b",
+    # CogVideoX (ai/generation/video.py: TextToVideo / ImageToVideo)
+    "THUDM/CogVideoX1.5-5B": "fdc5267c90b5c06492985b966e43aae984e189e0",
+    "THUDM/CogVideoX1.5-5B-I2V": "46c90528707aebbe69066390b4fe7e7d24c9c2a4",
+}
+
+
+def pinned(model_id: str) -> str | None:
+    """Return the pinned commit SHA for ``model_id``, or ``None`` if unpinned.
+
+    ``None`` is a valid, safe value to forward as ``revision=`` to
+    ``from_pretrained`` / ``hf_hub_download`` -- it is their default and means
+    "no pin" (track the repo's ``main`` branch, i.e. the current behavior).
+    Dynamic and unpinnable-by-design models (see the module docstring) fall
+    into this case.
+
+    Args:
+        model_id: The exact repo id / model identifier string passed to the
+            loader at the call site (e.g. ``"facebook/musicgen-small"``).
+
+    Returns:
+        The pinned SHA, or ``None`` when no pin is registered for ``model_id``.
+    """
+    return MODEL_REVISIONS.get(model_id)

videopython-0.43.1/src/videopython/ai/dubbing/__init__.py

@@ -0,0 +1,63 @@
+"""Local video dubbing functionality, lazily re-exported (PEP 562).
+
+The pipeline's translation backends (``MarianTranslator``/``Qwen3Translator``)
+top-level import transformers/llama-cpp/torch, so eagerly chaining ``pipeline``
+here would drag the ``[dub]`` translation stack in just to read
+``DubbingConfig`` (pydantic-only). Lazy re-exports keep the lightweight
+config/model symbols importable without that; only ``LocalDubbingPipeline`` /
+``VideoDubber`` access loads the heavy chain. The ``TYPE_CHECKING`` block keeps
+symbols visible to mypy and IDEs.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Redundant aliases = intentional re-exports (visible to mypy/IDE, not
+    # flagged by ruff). Runtime resolution is lazy via __getattr__ below.
+    from videopython.ai.dubbing.config import DubbingConfig as DubbingConfig
+    from videopython.ai.dubbing.dubber import VideoDubber as VideoDubber
+    from videopython.ai.dubbing.models import DubbingResult as DubbingResult
+    from videopython.ai.dubbing.models import Expressiveness as Expressiveness
+    from videopython.ai.dubbing.models import RevoiceResult as RevoiceResult
+    from videopython.ai.dubbing.models import SeparatedAudio as SeparatedAudio
+    from videopython.ai.dubbing.models import TranslatedSegment as TranslatedSegment
+    from videopython.ai.dubbing.pipeline import LocalDubbingPipeline as LocalDubbingPipeline
+    from videopython.ai.dubbing.quality import GarbageTranscriptError as GarbageTranscriptError
+    from videopython.ai.dubbing.quality import TranscriptQuality as TranscriptQuality
+    from videopython.ai.dubbing.quality import assess_transcript as assess_transcript
+    from videopython.ai.dubbing.timing import TimingSynchronizer as TimingSynchronizer
+    from videopython.ai.generation.translation import UnsupportedLanguageError as UnsupportedLanguageError
+
+# Public symbol -> fully-qualified module that defines it.
+_SYMBOL_MODULES: dict[str, str] = {
+    "DubbingConfig": "videopython.ai.dubbing.config",
+    "VideoDubber": "videopython.ai.dubbing.dubber",
+    "DubbingResult": "videopython.ai.dubbing.models",
+    "RevoiceResult": "videopython.ai.dubbing.models",
+    "TranslatedSegment": "videopython.ai.dubbing.models",
+    "SeparatedAudio": "videopython.ai.dubbing.models",
+    "Expressiveness": "videopython.ai.dubbing.models",
+    "LocalDubbingPipeline": "videopython.ai.dubbing.pipeline",
+    "TimingSynchronizer": "videopython.ai.dubbing.timing",
+    "GarbageTranscriptError": "videopython.ai.dubbing.quality",
+    "TranscriptQuality": "videopython.ai.dubbing.quality",
+    "assess_transcript": "videopython.ai.dubbing.quality",
+    "UnsupportedLanguageError": "videopython.ai.generation.translation",
+}
+
+__all__ = list(_SYMBOL_MODULES)
+
+
+def __getattr__(name: str) -> object:
+    module_name = _SYMBOL_MODULES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = importlib.import_module(module_name)
+    return getattr(module, name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)