videopython 0.51.0__tar.gz → 0.52.1__tar.gz

{videopython-0.51.0 → videopython-0.52.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.51.0
+Version: 0.52.1
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/

{videopython-0.51.0 → videopython-0.52.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.51.0"
+version = "0.52.1"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/__init__.py

@@ -34,6 +34,7 @@ if TYPE_CHECKING:
     from .auto_edit import StructuredVisionLLM as StructuredVisionLLM
     from .auto_edit import build_catalog as build_catalog
     from .effects import ObjectDetectionOverlay as ObjectDetectionOverlay
+    from .errors import AiError as AiError
     from .generation import ImageToVideo as ImageToVideo
     from .generation import TextToImage as TextToImage
     from .generation import TextToMusic as TextToMusic
@@ -42,7 +43,8 @@ if TYPE_CHECKING:
     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 FaceShotTracker as FaceShotTracker
+    from .understanding import FaceSmoothingTracker as FaceSmoothingTracker
     from .understanding import ObjectDetector as ObjectDetector
     from .understanding import SceneVLM as SceneVLM
     from .understanding import SemanticSceneDetector as SemanticSceneDetector
@@ -63,7 +65,8 @@ _exports: dict[str, str] = {
     # Understanding
     "AudioToText": ".understanding",
     "AudioClassifier": ".understanding",
-    "FaceTracker": ".understanding",
+    "FaceShotTracker": ".understanding",
+    "FaceSmoothingTracker": ".understanding",
     "ObjectDetector": ".understanding",
     "SceneVLM": ".understanding",
     "SemanticSceneDetector": ".understanding",
@@ -75,6 +78,8 @@ _exports: dict[str, str] = {
     "VideoAnalysis": ".video_analysis",
     "VideoAnalysisConfig": ".video_analysis",
     "VideoAnalyzer": ".video_analysis",
+    # Errors
+    "AiError": ".errors",
     # Auto-editing (LLM-authored edits)
     "AutoEditor": ".auto_edit",
     "AutoEditError": ".auto_edit",

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/_ollama.py

@@ -2,19 +2,17 @@
 
 from __future__ import annotations
 
-import base64
-import io
 import json
 from typing import Any
 
-import cv2
 import numpy as np
-from PIL import Image
 
 from videopython.ai._optional import require
+from videopython.ai.errors import AiError
+from videopython.ai.keyframe import encode_png_b64
 
 
-class OllamaError(RuntimeError):
+class OllamaError(AiError, RuntimeError):
     """Ollama returned unusable output (non-JSON or an unexpected shape)."""
 
 
@@ -50,7 +48,7 @@ class OllamaStructuredClient:
         """Return the parsed JSON object Ollama generates under ``schema``."""
         user: dict[str, Any] = {"role": "user", "content": text}
         if images:
-            user["images"] = [_encode_png_b64(image) for image in images]
+            user["images"] = [encode_png_b64(image) for image in images]
         messages = [{"role": "system", "content": system}, user]
         response = self._get_client().chat(model=self.model, messages=messages, format=schema, options=self.options)
         content = response.message.content
@@ -64,23 +62,3 @@ class OllamaStructuredClient:
 
     def unload(self) -> None:
         self._client = None
-
-
-# Used only on the MCP keyframe path (videopython.mcp). SceneVLM captioning and the local
-# planner deliberately encode full-resolution frames via _encode_png_b64.
-KEYFRAME_MAX_DIM = 768  # bound a keyframe's longest side before PNG-encoding for the MCP payload
-
-
-def _downscale(frame: np.ndarray, max_dim: int = KEYFRAME_MAX_DIM) -> np.ndarray:
-    """Shrink an RGB frame so its longest side is at most ``max_dim`` (aspect preserved; never upscales)."""
-    h, w = frame.shape[:2]
-    scale = max_dim / max(h, w)
-    if scale >= 1.0:
-        return frame
-    return cv2.resize(frame, (max(1, round(w * scale)), max(1, round(h * scale))), interpolation=cv2.INTER_AREA)
-
-
-def _encode_png_b64(frame: np.ndarray) -> str:
-    buffer = io.BytesIO()
-    Image.fromarray(frame).save(buffer, format="PNG")
-    return base64.b64encode(buffer.getvalue()).decode("ascii")

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/_revisions.py

@@ -65,7 +65,7 @@ MODEL_REVISIONS: dict[str, str] = {
     # 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)
+    # Audio event classifier (ai/understanding/classification.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",

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/auto_edit/__init__.py

@@ -1,4 +1,10 @@
-"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it."""
+"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it.
+
+Uses eager imports (unlike the leaf packages): it is a thin orchestration
+package whose submodules load together, and it MUST eagerly import
+``videopython.ai.ops`` so the AI editing ops are registered before any
+``EditPlan.json_schema()`` call. Heavy ML deps it pulls in stay lazy.
+"""
 
 from __future__ import annotations
 

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/auto_edit/backend.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
+from videopython.ai.errors import AiError
+
 if TYPE_CHECKING:
     import numpy as np
 
 
-class PlannerError(RuntimeError):
+class PlannerError(AiError, RuntimeError):
     """A backend produced unusable output; the editor retries (infra errors should propagate instead)."""
 
 

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/auto_edit/editor.py

@@ -8,6 +8,8 @@ from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import ValidationError
 
+from videopython.ai.errors import AiError
+
 from .backend import PlannerError, StructuredVisionLLM
 from .catalog import build_catalog
 from .models import CatalogBundle, CatalogScene, EditPlan
@@ -30,7 +32,7 @@ _SYSTEM_PROMPT = (
 _NormalizeTarget = tuple[int, int] | Literal["first", "largest", "match"]
 
 
-class AutoEditError(RuntimeError):
+class AutoEditError(AiError, RuntimeError):
     """The planner could not produce a valid edit within the retry budget."""
 
 

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/auto_edit/resolve.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
+from videopython.ai.errors import AiError
 from videopython.editing import SegmentConfig, VideoEdit
 
 from .models import EditCatalog, EditPlan
 
 
-class UnknownSceneIdsError(ValueError):
+class UnknownSceneIdsError(AiError, ValueError):
     """An EditPlan referenced scene ids absent from the catalog."""
 
     def __init__(self, ids: list[str]) -> None:

videopython-0.51.0/src/videopython/ai/dubbing/loudness.py → videopython-0.52.1/src/videopython/ai/dubbing/audio_ops.py

@@ -1,4 +1,11 @@
-"""LUFS / peak loudness matching for dubbed audio."""
+"""Audio DSP helpers for the dubbing pipeline.
+
+Merges the former ``expressiveness`` and ``loudness`` leaf modules: RMS,
+source-prosody -> Chatterbox expressiveness mapping, and LUFS/peak loudness
+matching. These are the small numpy/DSP helpers the pipeline composes; keeping
+them in one file (rather than two ~50-line files) makes the audio-side toolkit
+legible.
+"""
 
 from __future__ import annotations
 
@@ -6,10 +13,48 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from videopython.ai.dubbing.models import Expressiveness
+
 if TYPE_CHECKING:
     from videopython.audio import Audio
 
 
+def rms(data: np.ndarray) -> float:
+    """RMS over samples; ``0.0`` for empty input. float64 reduction so a
+    long slice can't overflow the squared accumulator."""
+    if data.size == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(np.square(data, dtype=np.float64))))
+
+
+# --- Source-prosody-driven expressiveness (Chatterbox TTS knobs) -----------
+# Source-segment RMS / whole-vocals RMS below CALM lands in the calm bucket;
+# above DRAMATIC in the dramatic bucket; in between gets Chatterbox's defaults.
+# Knob values picked by-ear on cam1_1min.mp4 -- see RELEASE_NOTES 0.29.0.
+CALM_RATIO_THRESHOLD = 0.7
+DRAMATIC_RATIO_THRESHOLD = 1.3
+_CALM = Expressiveness(exaggeration=0.3, cfg_weight=0.7)
+_DRAMATIC = Expressiveness(exaggeration=0.85, cfg_weight=0.35)
+
+
+def expressiveness_for(source_slice: Audio, baseline_rms: float) -> Expressiveness:
+    """Map a source vocals slice to a Chatterbox expressiveness profile
+    by RMS ratio. Falls back to the no-knobs default for empty or silent
+    inputs."""
+    if baseline_rms <= 0.0:
+        return Expressiveness()
+    segment_rms = rms(source_slice.data)
+    if segment_rms <= 0.0:
+        return Expressiveness()
+    ratio = segment_rms / baseline_rms
+    if ratio < CALM_RATIO_THRESHOLD:
+        return _CALM
+    if ratio > DRAMATIC_RATIO_THRESHOLD:
+        return _DRAMATIC
+    return Expressiveness()
+
+
+# --- LUFS / peak loudness matching -----------------------------------------
 # 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.

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/config.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict
 
@@ -63,6 +63,18 @@ class DubbingConfig(BaseModel):
     translator_model: str | None = None
     translator_host: str | None = None
 
+    @classmethod
+    def from_args(cls, config: DubbingConfig | None = None, /, **kwargs: Any) -> DubbingConfig:
+        """Resolve either a ``config`` object or flat knob kwargs into a config.
+
+        The shared accept-one-or-the-other guard for ``VideoDubber`` and
+        ``LocalDubbingPipeline``, which both take ``config=DubbingConfig(...)``
+        or the flat kwargs (not both).
+        """
+        if config is not None and kwargs:
+            raise TypeError("Pass either `config=` or knob kwargs, not both")
+        return config or cls(**kwargs)
+
     def init_log_fields(self) -> dict[str, object]:
         """Subset of fields surfaced in the init-log line.
 

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/dubber.py

@@ -10,7 +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.ai.dubbing._tts_backend import SpeechBackend
     from videopython.base.video import Video
 
 logger = logging.getLogger(__name__)
@@ -20,8 +20,8 @@ class VideoDubber:
     """Dubs videos into different languages using the local pipeline.
 
     Accepts either a :class:`DubbingConfig` or the same knobs as flat kwargs
-    (``device``, ``low_memory``, ``whisper_model``, ``translator``, etc.) --
-    the flat path builds a ``DubbingConfig`` internally. See
+    (``device``, ``low_memory``, ``whisper_model``, ``translator_model``, etc.)
+    -- the flat path builds a ``DubbingConfig`` internally. See
     :class:`DubbingConfig` for the full knob list and defaults.
     """
 
@@ -32,9 +32,7 @@ class VideoDubber:
         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)
+        self.config = DubbingConfig.from_args(config, **kwargs)
         # Optional injected speech backend. None -> the pipeline lazily builds
         # the local chatterbox-backed TextToSpeech (from the [ai] extra). Inject
         # a SpeechBackend to run synthesis out-of-process (e.g. a remote/Modal
@@ -248,6 +246,6 @@ class VideoDubber:
 
     @staticmethod
     def get_supported_languages() -> dict[str, str]:
-        from videopython.ai.generation.translation import OllamaTranslator
+        from videopython.ai.dubbing.translation import OllamaTranslator
 
         return OllamaTranslator.get_supported_languages()

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/models.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Annotated, Any
+from dataclasses import dataclass
+from typing import Annotated, Any
 
 from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, PlainSerializer, model_validator
 
@@ -10,8 +11,26 @@ from videopython.ai.dubbing.quality import TranscriptQuality
 from videopython.audio import Audio
 from videopython.base.transcription import Transcription, TranscriptionSegment
 
-if TYPE_CHECKING:
-    from videopython.ai.dubbing.timing import TimingAdjustment
+
+@dataclass
+class TimingAdjustment:
+    """Information about a timing adjustment made to a segment.
+
+    Attributes:
+        segment_index: Index of the segment that was adjusted.
+        original_duration: Original duration of the segment in seconds.
+        target_duration: Target duration to fit into.
+        actual_duration: Actual duration after adjustment.
+        speed_factor: Speed factor applied (> 1 means sped up).
+        was_truncated: Whether the segment had to be truncated.
+    """
+
+    segment_index: int
+    original_duration: float
+    target_duration: float
+    actual_duration: float
+    speed_factor: float
+    was_truncated: bool
 
 
 # Speed factors within this band of 1.0 are treated as a "clean" timing

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/pipeline.py

@@ -7,16 +7,16 @@ import tempfile
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable
 
-from videopython.ai.dubbing import expressiveness, loudness, voice_sample
+from videopython.ai.dubbing import audio_ops, voice_sample
 from videopython.ai.dubbing.config import DubbingConfig
 from videopython.ai.dubbing.models import DubbingResult, Expressiveness, RevoiceResult, SeparatedAudio, TimingSummary
 from videopython.ai.dubbing.quality import GarbageTranscriptError, assess_transcript
 from videopython.ai.dubbing.timing import TimingSynchronizer
-from videopython.ai.generation.translation import DEFAULT_TRANSLATION_MODEL, OllamaTranslator
+from videopython.ai.dubbing.translation import DEFAULT_TRANSLATION_MODEL, OllamaTranslator
 
 if TYPE_CHECKING:
+    from videopython.ai.dubbing._tts_backend import SpeechBackend
     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
 
@@ -40,12 +40,9 @@ class LocalDubbingPipeline:
         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)
+        # ``DubbingConfig`` consolidates the knobs that used to be constructor
+        # kwargs. Either ``config=`` or the flat kwargs are accepted (not both).
+        self.config = DubbingConfig.from_args(config, **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 (from the [ai] extra). Supplying a
@@ -224,7 +221,7 @@ class LocalDubbingPipeline:
 
     def _init_separator(self) -> None:
         """Initialize the audio separator."""
-        from videopython.ai.understanding.separation import AudioSeparator
+        from videopython.ai.dubbing.separation import AudioSeparator
 
         self._separator = AudioSeparator(device=self.config.device)
 
@@ -232,6 +229,43 @@ class LocalDubbingPipeline:
         """Initialize the timing synchronizer."""
         self._synchronizer = TimingSynchronizer()
 
+    def _separate(
+        self,
+        source_audio: Audio,
+        transcription: Transcription,
+        progress_fraction: float,
+        report_progress: Callable[[str, float], None],
+    ) -> tuple[SeparatedAudio | None, Audio, Audio | None]:
+        """Demucs source separation over the speech regions; shared by process()/revoice().
+
+        Limits Demucs to the speech-bearing portion of the audio: the transcription
+        has already located every speech region, and separating outside those is pure
+        overhead (no vocals to isolate). On talk-heavy sources with silence/music gaps
+        this roughly halves separation time; when speech covers most of the track,
+        separate_regions falls back to a full-track separate().
+
+        Returns ``(separated_audio, vocal_audio, background_audio)``. In low_memory
+        mode the ``SeparatedAudio`` container is dropped (returned as ``None``) so
+        vocals and background release as soon as their last local reference goes.
+        """
+        report_progress("Separating audio", progress_fraction)
+        if self._separator is None:
+            self._init_separator()
+
+        from videopython.ai.dubbing.separation import merge_regions
+
+        speech_regions = merge_regions(
+            [(s.start, s.end) for s in transcription.segments],
+            audio_duration=source_audio.metadata.duration_seconds,
+        )
+        separated_audio = self._separator.separate_regions(source_audio, speech_regions)
+        self._maybe_unload("_separator")
+        vocal_audio = separated_audio.vocals
+        background_audio = separated_audio.background
+        if self.config.low_memory:
+            separated_audio = None
+        return separated_audio, vocal_audio, background_audio
+
     def _finalise_audio(
         self,
         dubbed_speech: Audio,
@@ -253,7 +287,7 @@ class LocalDubbingPipeline:
             final_audio = background_audio.overlay(dubbed_speech, position=0.0)
         else:
             final_audio = dubbed_speech
-        return loudness.loudness_match(final_audio, source_audio)
+        return audio_ops.loudness_match(final_audio, source_audio)
 
     def process(
         self,
@@ -358,32 +392,9 @@ class LocalDubbingPipeline:
         background_audio: Audio | None = None
 
         if preserve_background:
-            report_progress("Separating audio", 0.15)
-            if self._separator is None:
-                self._init_separator()
-
-            # Limit Demucs to the speech-bearing portion of the audio. The
-            # transcription has already located every speech region; running
-            # source separation outside those is pure overhead (no vocals to
-            # isolate). On talk-heavy sources with silence/music gaps this
-            # roughly halves separation time. When speech covers most of the
-            # track separate_regions falls back to a full-track separate().
-            from videopython.ai.understanding.separation import _merge_regions
-
-            speech_regions = _merge_regions(
-                [(s.start, s.end) for s in transcription.segments],
-                audio_duration=source_audio.metadata.duration_seconds,
+            separated_audio, vocal_audio, background_audio = self._separate(
+                source_audio, transcription, 0.15, report_progress
             )
-            separated_audio = self._separator.separate_regions(source_audio, speech_regions)
-            self._maybe_unload("_separator")
-            vocal_audio = separated_audio.vocals
-            background_audio = separated_audio.background
-            # In low_memory mode, drop the SeparatedAudio container so vocals
-            # and background can be released as soon as their last local
-            # reference goes (after voice-sample extraction and final overlay
-            # respectively). The result will report separated_audio=None.
-            if self.config.low_memory:
-                separated_audio = None
 
         voice_samples: dict[str, Audio] = {}
         if voice_clone:
@@ -401,10 +412,10 @@ class LocalDubbingPipeline:
         # — transcription timestamps can drift past the buffer tail
         # (especially on synthetic test audio) and Audio.slice rejects
         # out-of-range ends past a 0.1s tolerance.
-        baseline_rms = expressiveness.rms(vocal_audio.data)
+        baseline_rms = audio_ops.rms(vocal_audio.data)
         vocal_duration = vocal_audio.metadata.duration_seconds
         expressiveness_per_segment = [
-            expressiveness.expressiveness_for(
+            audio_ops.expressiveness_for(
                 vocal_audio.slice(min(s.start, vocal_duration), min(s.end, vocal_duration)),
                 baseline_rms,
             )
@@ -530,22 +541,9 @@ class LocalDubbingPipeline:
         background_audio: Audio | None = None
 
         if preserve_background:
-            report_progress("Separating audio", 0.20)
-            if self._separator is None:
-                self._init_separator()
-
-            from videopython.ai.understanding.separation import _merge_regions
-
-            speech_regions = _merge_regions(
-                [(s.start, s.end) for s in transcription.segments],
-                audio_duration=source_audio.metadata.duration_seconds,
+            separated_audio, vocal_audio, background_audio = self._separate(
+                source_audio, transcription, 0.20, report_progress
             )
-            separated_audio = self._separator.separate_regions(source_audio, speech_regions)
-            self._maybe_unload("_separator")
-            vocal_audio = separated_audio.vocals
-            background_audio = separated_audio.background
-            if self.config.low_memory:
-                separated_audio = None
 
         report_progress("Extracting voice sample", 0.40)
         chosen_sample: Audio | None = None

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/quality.py

@@ -24,6 +24,8 @@ from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, Field
 
+from videopython.ai.errors import AiError
+
 if TYPE_CHECKING:
     from videopython.base.transcription import Transcription
 
@@ -74,7 +76,7 @@ class TranscriptQuality(BaseModel):
     flags: list[str] = Field(default_factory=list)
 
 
-class GarbageTranscriptError(RuntimeError):
+class GarbageTranscriptError(AiError, RuntimeError):
     """Raised by the dubbing pipeline when ``strict_quality=True`` and the
     transcript heuristic returns ``recommendation="reject"``.
 

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/remux.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from videopython.ai.errors import AiError
 from videopython.base import _ffmpeg
 from videopython.base.exceptions import FFmpegRunError
 
@@ -19,7 +20,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class RemuxError(RuntimeError):
+class RemuxError(AiError, RuntimeError):
     """ffmpeg failed while replacing an audio stream."""
 
 

{videopython-0.51.0/src/videopython/ai/understanding → videopython-0.52.1/src/videopython/ai/dubbing}/separation.py

@@ -13,7 +13,7 @@ from videopython.audio import Audio, AudioMetadata
 logger = logging.getLogger(__name__)
 
 
-def _merge_regions(
+def merge_regions(
     regions: list[tuple[float, float]],
     audio_duration: float,
     pad: float = 0.5,
@@ -59,14 +59,9 @@ def _merge_regions(
 class AudioSeparator(ManagedPredictor):
     """Separates audio into vocals and background components using Demucs."""
 
-    SUPPORTED_MODELS: list[str] = ["htdemucs", "htdemucs_ft", "htdemucs_6s", "mdx_extra"]
     STEM_NAMES = ["drums", "bass", "other", "vocals"]
-    STEM_NAMES_6S = ["drums", "bass", "other", "vocals", "guitar", "piano"]
 
     def __init__(self, model_name: str = "htdemucs", device: str | None = None):
-        if model_name not in self.SUPPORTED_MODELS:
-            raise ValueError(f"Model '{model_name}' not supported. Supported: {self.SUPPORTED_MODELS}")
-
         self.model_name = model_name
         self.device = device
         self._model: Any = None
@@ -129,7 +124,7 @@ class AudioSeparator(ManagedPredictor):
         sources_np = sources[0].cpu().numpy()
         del sources
 
-        stem_names = self.STEM_NAMES_6S if self.model_name == "htdemucs_6s" else self.STEM_NAMES
+        stem_names = self.STEM_NAMES
         vocals_idx = stem_names.index("vocals")
         non_vocal_indices = [i for i in range(len(stem_names)) if i != vocals_idx]
 
@@ -185,7 +180,7 @@ class AudioSeparator(ManagedPredictor):
             audio: Source audio (typically the full track).
             regions: List of ``(start, end)`` second pairs marking
                 speech-bearing portions. Caller is responsible for
-                merging/padding (use ``_merge_regions``).
+                merging/padding (use ``merge_regions``).
             full_separation_threshold: If the regions cover more than
                 this fraction of the audio, fall back to full-track
                 ``separate()`` since per-region slicing+stitching

{videopython-0.51.0 → videopython-0.52.1}/src/videopython/ai/dubbing/timing.py

@@ -2,34 +2,12 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-
 import numpy as np
 
+from videopython.ai.dubbing.models import TimingAdjustment
 from videopython.audio import Audio, AudioMetadata
 
 
-@dataclass
-class TimingAdjustment:
-    """Information about a timing adjustment made to a segment.
-
-    Attributes:
-        segment_index: Index of the segment that was adjusted.
-        original_duration: Original duration of the segment in seconds.
-        target_duration: Target duration to fit into.
-        actual_duration: Actual duration after adjustment.
-        speed_factor: Speed factor applied (> 1 means sped up).
-        was_truncated: Whether the segment had to be truncated.
-    """
-
-    segment_index: int
-    original_duration: float
-    target_duration: float
-    actual_duration: float
-    speed_factor: float
-    was_truncated: bool
-
-
 class TimingSynchronizer:
     """Synchronizes dubbed audio segments to match original timing.
 

videopython-0.52.1/src/videopython/ai/errors.py

@@ -0,0 +1,13 @@
+"""Common base for ``videopython.ai`` error types.
+
+Every error the AI layer raises subclasses :class:`AiError` (alongside the
+builtin it semantically is — ``RuntimeError`` for operational failures,
+``ValueError`` for bad inputs), so a caller can ``except AiError`` to catch any
+of them without enumerating each submodule's error type.
+"""
+
+from __future__ import annotations
+
+
+class AiError(Exception):
+    """Base class for all ``videopython.ai`` errors."""