videopython 0.41.0__tar.gz → 0.43.0__tar.gz

{videopython-0.41.0 → videopython-0.43.0}/.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.41.0 → videopython-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.41.0
+Version: 0.43.0
 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
@@ -117,9 +156,9 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 ## Features
 
-- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
-- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, reverse, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
+- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
 - **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
 

{videopython-0.41.0 → videopython-0.43.0}/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
@@ -68,9 +70,9 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 ## Features
 
-- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
-- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, reverse, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
+- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
 - **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
 

{videopython-0.41.0 → videopython-0.43.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.41.0"
+version = "0.43.0"
 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.0/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.0/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.0/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__)

{videopython-0.41.0 → videopython-0.43.0}/src/videopython/ai/dubbing/dubber.py

@@ -10,6 +10,7 @@ from videopython.ai.dubbing.config import DubbingConfig
 from videopython.ai.dubbing.models import DubbingResult, RevoiceResult
 
 if TYPE_CHECKING:
+    from videopython.ai.generation._tts_backend import SpeechBackend
     from videopython.base.video import Video
 
 logger = logging.getLogger(__name__)
@@ -24,10 +25,20 @@ class VideoDubber:
     :class:`DubbingConfig` for the full knob list and defaults.
     """
 
-    def __init__(self, config: DubbingConfig | None = None, **kwargs: Any):
+    def __init__(
+        self,
+        config: DubbingConfig | None = None,
+        *,
+        tts_backend: SpeechBackend | None = None,
+        **kwargs: Any,
+    ):
         if config is not None and kwargs:
             raise TypeError("Pass either `config=` or knob kwargs, not both")
         self.config = config or DubbingConfig(**kwargs)
+        # Optional injected speech backend. None -> the pipeline lazily builds
+        # the local chatterbox-backed TextToSpeech (requires the [tts] extra).
+        # Inject a SpeechBackend to dub with only [dub] installed.
+        self._tts_backend = tts_backend
         self._local_pipeline: Any = None
         logger.info(
             "VideoDubber initialized with %s",
@@ -37,7 +48,7 @@ class VideoDubber:
     def _init_local_pipeline(self) -> None:
         from videopython.ai.dubbing.pipeline import LocalDubbingPipeline
 
-        self._local_pipeline = LocalDubbingPipeline(config=self.config)
+        self._local_pipeline = LocalDubbingPipeline(config=self.config, tts_backend=self._tts_backend)
 
     def dub(
         self,

{videopython-0.41.0 → videopython-0.43.0}/src/videopython/ai/dubbing/loudness.py

@@ -62,7 +62,9 @@ def loudness_match(target: Audio, reference: Audio) -> Audio:
     if not target.data.size or not reference.data.size:
         return target
 
-    import pyloudnorm
+    from videopython.ai._optional import require
+
+    pyloudnorm = require("pyloudnorm", "dub", feature="loudness matching")
 
     target_lufs = pyloudnorm.Meter(target.metadata.sample_rate).integrated_loudness(target.data)
     reference_lufs = pyloudnorm.Meter(reference.metadata.sample_rate).integrated_loudness(reference.data)

{videopython-0.41.0 → videopython-0.43.0}/src/videopython/ai/dubbing/pipeline.py

@@ -22,6 +22,7 @@ from videopython.ai.generation.translation import (
 
 if TYPE_CHECKING:
     from videopython.ai.dubbing.models import TranslatedSegment
+    from videopython.ai.generation._tts_backend import SpeechBackend
     from videopython.audio import Audio
     from videopython.base.transcription import Transcription
 
@@ -38,16 +39,29 @@ class LocalDubbingPipeline:
     with <=12GB VRAM or hosts with <32GB RAM.
     """
 
-    def __init__(self, config: DubbingConfig | None = None, **kwargs: Any):
+    def __init__(
+        self,
+        config: DubbingConfig | None = None,
+        *,
+        tts_backend: SpeechBackend | None = None,
+        **kwargs: Any,
+    ):
         # ``DubbingConfig`` consolidates the nine knobs that used to be
         # constructor kwargs. Either ``config=`` or the flat kwargs are
         # accepted (not both) so existing callers don't need to change.
         if config is not None and kwargs:
             raise TypeError("Pass either `config=` or knob kwargs, not both")
         self.config = config or DubbingConfig(**kwargs)
+        # Injected speech backend (a SpeechBackend, e.g. a remote/out-of-process
+        # synthesizer). When None, _init_tts lazily constructs the local
+        # chatterbox-backed TextToSpeech — which requires the [tts] extra.
+        # Supplying a backend lets dubbing run with only [dub] installed (no
+        # chatterbox in the process).
+        self._tts_backend = tts_backend
         logger.info(
-            "LocalDubbingPipeline initialized with %s",
+            "LocalDubbingPipeline initialized with %s%s",
             " ".join(f"{k}={v}" for k, v in self.config.init_log_fields().items()),
+            " tts_backend=injected" if tts_backend is not None else "",
         )
 
         self._transcriber: Any = None
@@ -250,7 +264,18 @@ class LocalDubbingPipeline:
         raise UnsupportedLanguageError(source_lang, target_lang)
 
     def _init_tts(self, language: str = "en") -> None:
-        """Initialize the text-to-speech model."""
+        """Resolve the text-to-speech backend for ``language``.
+
+        When a ``tts_backend`` was injected at construction it is used as-is
+        (it owns its own language handling). Otherwise the local
+        chatterbox-backed :class:`TextToSpeech` is constructed for ``language``
+        — importing it requires the ``[tts]`` extra; a bare ``[dub]`` install
+        raises a clear ``[tts]``-pointing ``ImportError`` at this point.
+        """
+        if self._tts_backend is not None:
+            self._tts = self._tts_backend
+            return
+
         from videopython.ai.generation.audio import TextToSpeech
 
         self._tts = TextToSpeech(device=self.config.device, language=language)