videopython 0.43.0__tar.gz → 0.44.0__tar.gz

{videopython-0.43.0 → videopython-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.43.0
+Version: 0.44.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -133,7 +133,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. Use `edit.run()` to get a `Video` back in memory instead.
+`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
 
 ### AI generation
 

{videopython-0.43.0 → videopython-0.44.0}/README.md

@@ -47,7 +47,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. Use `edit.run()` to get a `Video` back in memory instead.
+`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
 
 ### AI generation
 

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

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

videopython-0.44.0/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.44.0/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.0 → videopython-0.44.0}/src/videopython/ai/dubbing/dubber.py

@@ -239,9 +239,7 @@ class VideoDubber:
         video_duration = video.total_seconds
 
         if video_duration > speech_duration:
-            from videopython.editing.transforms import CutSeconds
-
-            output_video = CutSeconds(start=0, end=speech_duration).apply(video)
+            output_video = video[: round(speech_duration * video.fps)]
         else:
             output_video = video
 

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/effects.py

@@ -33,9 +33,9 @@ class ObjectDetectionOverlay(Effect):
     *memory*-bound: ``"streamable"`` here means bounded memory, not bounded
     compute. On long clips, cap cost with ``window`` (limit the time range),
     a larger ``detection_interval``, a ``class_filter``, and/or the smaller
-    ``model_size``. Because only ``streaming_init`` and ``process_frame`` are
-    overridden, the base ``Effect._apply`` replays the identical contract for
-    in-memory execution, so eager and streaming results cannot drift.
+    ``model_size``. Only ``streaming_init`` and ``process_frame`` are
+    overridden; the streaming engine drives that contract for bounded-memory
+    execution.
     """
 
     op: Literal["object_detection_overlay"] = "object_detection_overlay"

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/generation/audio.py

@@ -5,13 +5,15 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.audio import Audio, AudioMetadata
 
 if TYPE_CHECKING:
     from pathlib import Path
 
 
-class TextToSpeech:
+class TextToSpeech(ManagedPredictor):
     """Generates speech audio from text using Chatterbox Multilingual.
 
     Backed by Chatterbox Multilingual (Resemble AI). When ``voice_sample`` is
@@ -42,6 +44,8 @@ class TextToSpeech:
         requested_device = self.device
         device = select_device(self.device, mps_allowed=False)
 
+        # No repo id to key a revision on: Chatterbox resolves its own repo +
+        # revision internally, so there is nothing to pass revision= to.
         self._model = ChatterboxMultilingualTTS.from_pretrained(device=device)
         self.device = device
         log_device_initialization(
@@ -146,7 +150,7 @@ class TextToSpeech:
         release_device_memory(self.device)
 
 
-class TextToMusic:
+class TextToMusic(ManagedPredictor):
     """Generates music from text descriptions using MusicGen."""
 
     def __init__(self, device: str | None = None):
@@ -170,8 +174,8 @@ class TextToMusic:
         device = select_device(self.device, mps_allowed=True)
 
         model_name = "facebook/musicgen-small"
-        self._processor = AutoProcessor.from_pretrained(model_name)
-        self._model = MusicgenForConditionalGeneration.from_pretrained(model_name)
+        self._processor = AutoProcessor.from_pretrained(model_name, revision=pinned(model_name))
+        self._model = MusicgenForConditionalGeneration.from_pretrained(model_name, revision=pinned(model_name))
         self._model.to(device)
         self.device = device
         log_device_initialization(

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/generation/image.py

@@ -7,9 +7,11 @@ from typing import Any
 from PIL import Image
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 
 
-class TextToImage:
+class TextToImage(ManagedPredictor):
     """Generates images from text descriptions using local models."""
 
     def __init__(self, device: str | None = None):
@@ -32,6 +34,7 @@ class TextToImage:
         model_name = "stabilityai/stable-diffusion-xl-base-1.0"
         self._pipeline = DiffusionPipeline.from_pretrained(
             model_name,
+            revision=pinned(model_name),
             torch_dtype=dtype,
             variant=variant,
             use_safetensors=True,

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/generation/qwen3.py

@@ -22,6 +22,8 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable
 
 from videopython.ai._device import release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.ai.generation.translation import (
     LANGUAGE_NAMES,
     MarianTranslator,
@@ -208,7 +210,7 @@ def _parse_jsonl_response(raw: str) -> dict[int, str]:
     return parsed
 
 
-class Qwen3Translator:
+class Qwen3Translator(ManagedPredictor):
     """Qwen3-Instruct translation via llama-cpp-python (GGUF).
 
     Args:
@@ -277,7 +279,7 @@ class Qwen3Translator:
             )
 
         logger.info("Qwen3Translator: loading %s", self.filename)
-        model_path = Path(hf_hub_download(repo_id=self.repo_id, filename=self.filename))
+        model_path = Path(hf_hub_download(repo_id=self.repo_id, filename=self.filename, revision=pinned(self.repo_id)))
 
         # n_gpu_layers=-1 offloads everything to GPU when one is available;
         # 0 forces CPU. llama-cpp-python's Metal/CUDA support detects and

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/generation/translation.py

@@ -17,6 +17,8 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Callable, Protocol, runtime_checkable
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.base.transcription import TranscriptionSegment
 
 # Imported under TYPE_CHECKING to avoid a circular dep through
@@ -123,7 +125,7 @@ LANGUAGE_NAMES = {
 }
 
 
-class MarianTranslator:
+class MarianTranslator(ManagedPredictor):
     """Translates text between languages using local Helsinki-NLP MarianMT models."""
 
     # Languages without a direct opus-mt-{src}-{tgt} model. Maps (source, target)
@@ -181,8 +183,10 @@ class MarianTranslator:
         requested_device = self.device
         device = select_device(self.device, mps_allowed=True)
 
-        self._tokenizer = MarianTokenizer.from_pretrained(model_name)
-        self._model = MarianMTModel.from_pretrained(model_name).to(device)
+        # Marian model names are dynamic per language pair, so pinned() returns
+        # None for them by design (revision=None tracks main, the safe default).
+        self._tokenizer = MarianTokenizer.from_pretrained(model_name, revision=pinned(model_name))
+        self._model = MarianMTModel.from_pretrained(model_name, revision=pinned(model_name)).to(device)
         self.device = device
         log_device_initialization(
             "MarianTranslator",

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/generation/video.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING, Any
 import numpy as np
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.base.video import Video
 
 if TYPE_CHECKING:
@@ -23,7 +25,7 @@ def _get_torch_device_and_dtype(device: str | None) -> tuple[str, Any]:
     return selected_device, torch.float32
 
 
-class TextToVideo:
+class TextToVideo(ManagedPredictor):
     """Generates videos from text descriptions using local diffusion models."""
 
     def __init__(self, device: str | None = None):
@@ -39,7 +41,7 @@ class TextToVideo:
         device, dtype = _get_torch_device_and_dtype(self.device)
 
         model_name = "THUDM/CogVideoX1.5-5B"
-        self._pipeline = CogVideoXPipeline.from_pretrained(model_name, torch_dtype=dtype)
+        self._pipeline = CogVideoXPipeline.from_pretrained(model_name, revision=pinned(model_name), torch_dtype=dtype)
         self._pipeline.to(device)
         self.device = device
         log_device_initialization(
@@ -77,7 +79,7 @@ class TextToVideo:
         release_device_memory(self.device)
 
 
-class ImageToVideo:
+class ImageToVideo(ManagedPredictor):
     """Generates videos from static images using local video diffusion."""
 
     def __init__(self, device: str | None = None):
@@ -95,7 +97,9 @@ class ImageToVideo:
         device, dtype = _get_torch_device_and_dtype(self.device)
 
         model_name = "THUDM/CogVideoX1.5-5B-I2V"
-        self._pipeline = CogVideoXImageToVideoPipeline.from_pretrained(model_name, torch_dtype=dtype)
+        self._pipeline = CogVideoXImageToVideoPipeline.from_pretrained(
+            model_name, revision=pinned(model_name), torch_dtype=dtype
+        )
         self._pipeline.to(device)
         self.device = device
         log_device_initialization(

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/transforms.py

@@ -15,7 +15,7 @@ from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
-from videopython.base.video import FrameIterator, Video, VideoMetadata
+from videopython.base.video import FrameIterator, VideoMetadata
 from videopython.editing._ass import escape_filter_value
 from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
@@ -94,8 +94,8 @@ class FaceTrackingCrop(Operation):
         """Output ``(width, height)`` -- the fixed crop-window size.
 
         The largest ``target_aspect`` box that fits the frame, even-floored.
-        A pure function of the input dimensions, shared by :meth:`apply`,
-        :meth:`predict_metadata`, and :meth:`to_ffmpeg_filter`, so the
+        A pure function of the input dimensions, shared by
+        :meth:`predict_metadata` and :meth:`to_ffmpeg_filter`, so the
         dry-run cannot disagree with the render.
         """
         target_ratio = self.target_aspect[0] / self.target_aspect[1]
@@ -131,9 +131,8 @@ class FaceTrackingCrop(Operation):
         """Per-frame crop top-left positions for a fixed-size crop window.
 
         The single source of the tracking math (detection cadence, EMA
-        smoothing, framing offset, speed clamp, frame clamping), shared by
-        the eager :meth:`apply` and the compile-time detection pass so the
-        two paths cannot drift.
+        smoothing, framing offset, speed clamp, frame clamping), run by the
+        compile-time detection pass to build the per-frame crop command file.
         """
         out_w, out_h = self._resolved_output_dims(frame_w, frame_h)
         tracker = FaceTracker(
@@ -166,23 +165,6 @@ class FaceTrackingCrop(Operation):
                 positions.append(default)
         return positions
 
-    def apply(self, video: Video) -> Video:
-        h, w = video.frame_shape[:2]
-        out_w, out_h = self._resolved_output_dims(w, h)
-        logger.info(
-            "Face tracking crop: %dx%d -> %dx%d (%d:%d, framing=%s)",
-            w,
-            h,
-            out_w,
-            out_h,
-            self.target_aspect[0],
-            self.target_aspect[1],
-            self.framing_rule,
-        )
-        positions = self._track_crop_positions(tqdm(video.frames, desc="Face tracking crop"), w, h)
-        video.frames = np.stack([video.frames[i][y : y + out_h, x : x + out_w] for i, (x, y) in enumerate(positions)])
-        return video
-
     def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
         """Compile the face track to a per-frame ``crop`` position command file.
 

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/audio.py

@@ -6,6 +6,8 @@ import logging
 from typing import Any, Literal
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.audio import Audio
 from videopython.base.description import AudioClassification, AudioEvent
 from videopython.base.transcription import Transcription, TranscriptionSegment, TranscriptionWord
@@ -105,7 +107,7 @@ def _attach_confidence_by_overlap(
             tgt.compression_ratio = best_src.compression_ratio
 
 
-class AudioToText:
+class AudioToText(ManagedPredictor):
     """Transcription service for audio and video using local Whisper models.
 
     Uses openai-whisper for transcription (with word-level timestamps) and
@@ -187,6 +189,9 @@ class AudioToText:
 
         whisper = require("whisper", "asr", feature="AudioToText")
 
+        # No revision pin: openai-whisper downloads weights by name from OpenAI's
+        # own CDN, not via a HF from_pretrained repo, so there is no HF commit
+        # SHA to pin (see videopython.ai._revisions module docstring).
         self._model = whisper.load_model(name=self.model_name, device=self.device)
 
     def _init_diarization(self) -> None:
@@ -197,7 +202,9 @@ class AudioToText:
 
         Pipeline = require("pyannote.audio", "asr", feature="AudioToText diarization").Pipeline
 
-        self._diarization_pipeline = Pipeline.from_pretrained(self.PYANNOTE_DIARIZATION_MODEL)
+        self._diarization_pipeline = Pipeline.from_pretrained(
+            self.PYANNOTE_DIARIZATION_MODEL, revision=pinned(self.PYANNOTE_DIARIZATION_MODEL)
+        )
         self._diarization_pipeline.to(torch.device(self.device))
 
     def _init_vad(self) -> None:
@@ -486,7 +493,7 @@ class AudioToText:
         return self._transcribe_local(audio, effective_vocab)
 
 
-class AudioClassifier:
+class AudioClassifier(ManagedPredictor):
     """Audio event and sound classification using AST."""
 
     SUPPORTED_MODELS: list[str] = ["MIT/ast-finetuned-audioset-10-10-0.4593"]
@@ -526,8 +533,8 @@ class AudioClassifier:
         ASTFeatureExtractor = _transformers.ASTFeatureExtractor
         ASTForAudioClassification = _transformers.ASTForAudioClassification
 
-        self._processor = ASTFeatureExtractor.from_pretrained(self.model_name)
-        self._model = ASTForAudioClassification.from_pretrained(self.model_name)
+        self._processor = ASTFeatureExtractor.from_pretrained(self.model_name, revision=pinned(self.model_name))
+        self._model = ASTForAudioClassification.from_pretrained(self.model_name, revision=pinned(self.model_name))
         self._model.to(self.device)
         self._model.eval()
 

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/faces.py

@@ -17,6 +17,7 @@ from typing import Any, Literal
 import numpy as np
 
 from videopython.ai._device import select_device
+from videopython.ai._revisions import pinned
 from videopython.base.description import BoundingBox, DetectedFace, FaceTrack
 
 logger = logging.getLogger(__name__)
@@ -82,6 +83,7 @@ class _FaceDetector:
         model_path = hf_hub_download(
             repo_id="arnabdhar/YOLOv8-Face-Detection",
             filename="model.pt",
+            revision=pinned("arnabdhar/YOLOv8-Face-Detection"),
         )
         self._yolo_model = YOLO(model_path)
 

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/image.py

@@ -12,6 +12,8 @@ import numpy as np
 from PIL import Image
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
+from videopython.ai._revisions import pinned
 from videopython.base.description import SceneDescription
 
 logger = logging.getLogger(__name__)
@@ -74,7 +76,7 @@ _RETRY_PROMPT = (
 )
 
 
-class SceneVLM:
+class SceneVLM(ManagedPredictor):
     """Generates structured scene descriptions with local Qwen3.5.
 
     ``model_size`` maps to Qwen3.5 dense vision-capable variants:
@@ -162,13 +164,15 @@ class SceneVLM:
         requested_device = self.device
         resolved_device = select_device(self.device, mps_allowed=True)
 
-        self._processor = AutoProcessor.from_pretrained(self.model_name)
+        self._processor = AutoProcessor.from_pretrained(self.model_name, revision=pinned(self.model_name))
         # Save and restore default dtype -- transformers torch_dtype="auto" can
         # mutate torch.get_default_dtype(), which breaks concurrent models
         # (e.g. Whisper) that expect float32.
         saved_dtype = torch.get_default_dtype()
         try:
-            self._model = AutoModelForImageTextToText.from_pretrained(self.model_name, torch_dtype="auto")
+            self._model = AutoModelForImageTextToText.from_pretrained(
+                self.model_name, torch_dtype="auto", revision=pinned(self.model_name)
+            )
         finally:
             torch.set_default_dtype(saved_dtype)
         self._model.to(resolved_device)

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/objects.py

@@ -87,6 +87,9 @@ class ObjectDetector:
 
         YOLO = require("ultralytics", "vision", feature="ObjectDetector").YOLO
 
+        # No revision pin: ultralytics resolves/downloads this asset from its own
+        # GitHub release assets, not a HF repo, and YOLO() takes no revision arg
+        # (see videopython.ai._revisions module docstring).
         self._yolo_model = YOLO(self.model_name)
         self._class_names = dict(self._yolo_model.names)
 

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/separation.py

@@ -6,6 +6,7 @@ import logging
 from typing import Any
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
 from videopython.ai.dubbing.models import SeparatedAudio
 from videopython.audio import Audio, AudioMetadata
 
@@ -55,7 +56,7 @@ def _merge_regions(
     return merged
 
 
-class AudioSeparator:
+class AudioSeparator(ManagedPredictor):
     """Separates audio into vocals and background components using Demucs."""
 
     SUPPORTED_MODELS: list[str] = ["htdemucs", "htdemucs_ft", "htdemucs_6s", "mdx_extra"]

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/understanding/temporal.py

@@ -10,13 +10,14 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from videopython.ai._device import log_device_initialization, release_device_memory, select_device
+from videopython.ai._predictor import ManagedPredictor
 from videopython.base.description import SceneBoundary
 
 if TYPE_CHECKING:
     from videopython.base.video import Video
 
 
-class SemanticSceneDetector:
+class SemanticSceneDetector(ManagedPredictor):
     """ML-based scene detection using TransNetV2.
 
     TransNetV2 is a neural network specifically designed for shot boundary

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/ai/video_analysis/analyzer.py

@@ -331,9 +331,8 @@ class VideoAnalyzer:
             return None
         if source_path is not None:
             return Video.from_path(str(source_path), start_second=start_second, end_second=end_second)
-        from videopython.editing.transforms import CutSeconds
-
-        return CutSeconds(start=start_second, end=end_second).apply(stages.require_video(video))
+        v = stages.require_video(video)
+        return v[round(start_second * v.fps) : round(end_second * v.fps)]
 
     def _default_scene_boundaries(self, metadata: VideoMetadata) -> list[SceneBoundary]:
         if metadata.total_seconds <= 0 or metadata.frame_count <= 0:

{videopython-0.43.0 → videopython-0.44.0}/src/videopython/audio/audio.py

@@ -23,8 +23,8 @@ def atempo_chain(speed: float) -> list[str]:
     factor outside that range is decomposed into a chain of capped stages
     (``atempo=2.0`` repeated for speedups, ``atempo=0.5`` for slowdowns) times
     a final remainder stage. The single source of truth shared by
-    :meth:`Audio.time_stretch` (the in-memory WAV round-trip used by the eager
-    ``apply`` path) and ``SpeedChange.to_ffmpeg_audio_filter`` (the streaming
+    :meth:`Audio.time_stretch` (the in-memory WAV round-trip used by dubbing's
+    timing alignment) and ``SpeedChange.to_ffmpeg_audio_filter`` (the streaming
     filter graph), so both stretch by exactly the same chain. Returns an empty
     list for ``speed == 1`` (a no-op the caller maps to ``anull``).
     """