videopython 0.43.0__tar.gz → 0.43.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.43.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/

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

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

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.0 → videopython-0.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/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.43.1}/src/videopython/base/exceptions.py

@@ -119,6 +119,62 @@ class PlanError:
     predicted_duration: float | None = None
     detail: str | None = None
 
+    def to_prompt_line(self) -> str:
+        """Render this error as one deterministic, actionable feedback line.
+
+        Composes a single line from the structured fields so a *standalone*
+        :class:`PlanError` can reproduce a human message without the ad-hoc
+        prose built at the validation call sites. Intended for an LLM
+        refine-loop: feed these lines back so the model can repair the plan.
+
+        Format (each clause is appended only when its field is populated;
+        ``None`` fields are skipped)::
+
+            <CODE_NAME> [at <location>] [(op '<op>')]: [<field>=<value>]
+            [(limit <limit>)] [(predicted duration <predicted_duration>s)]
+            [-- <detail>]
+
+        Every :class:`PlanErrorCode` yields a non-empty line: the code name is
+        always present, so a code carrying no other fields still renders
+        (e.g. ``"SOURCE_UNREADABLE"``). Numeric fields are formatted with
+        :func:`_fmt_num`, which drops trailing zeros for readability.
+        """
+        line = self.code.name
+        if self.location is not None:
+            line += f" at {self.location}"
+        if self.op is not None:
+            line += f" (op '{self.op}')"
+
+        clauses: list[str] = []
+        if self.field is not None:
+            if self.value is not None:
+                clauses.append(f"{self.field}={_fmt_num(self.value)}")
+            else:
+                clauses.append(self.field)
+        elif self.value is not None:
+            clauses.append(f"value={_fmt_num(self.value)}")
+        if self.limit is not None:
+            clauses.append(f"limit {_fmt_num(self.limit)}")
+        if self.predicted_duration is not None:
+            clauses.append(f"predicted duration {_fmt_num(self.predicted_duration)}s")
+
+        if clauses:
+            line += ": " + ", ".join(clauses)
+        if self.detail is not None:
+            line += f" -- {self.detail}"
+        return line
+
+
+def _fmt_num(value: float) -> str:
+    """Format a numeric field readably: integers lose the ``.0``, floats keep it.
+
+    Keeps :meth:`PlanError.to_prompt_line` deterministic and free of noisy
+    trailing zeros (``3`` not ``3.0``, but ``2.5`` stays ``2.5``).
+    """
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
 
 @dataclass
 class PlanRepair:
@@ -156,3 +212,12 @@ class PlanValidationError(ValueError):
     def __init__(self, message: str, errors: list[PlanError]):
         super().__init__(message)
         self.errors = errors
+
+    def prompt_feedback(self) -> str:
+        """Every carried :class:`PlanError` as newline-joined feedback lines.
+
+        Joins :meth:`PlanError.to_prompt_line` over :attr:`errors`, one per
+        line -- a ready-to-feed block for an LLM refine loop. Returns an empty
+        string when no structured errors are attached.
+        """
+        return "\n".join(e.to_prompt_line() for e in self.errors)

{videopython-0.43.0 → videopython-0.43.1}/src/videopython/base/video.py

@@ -569,6 +569,16 @@ class Video:
         Returns:
             New Video with the audio added
         """
+        # When the incoming audio will be mixed with an existing (non-silent)
+        # track, reconcile sample rates first. concat()/overlay() require
+        # matching sample rates, and mixing at a mismatched rate would otherwise
+        # produce silent A/V drift. The existing track's sample rate is the
+        # canonical target (it is what gets encoded into the video). For a pure
+        # attach/replace (no existing audio, or overlay=False) the incoming rate
+        # is kept as-is.
+        if overlay and not self.audio.is_silent:
+            audio = audio.resample(self.audio.metadata.sample_rate)
+
         video_duration = self.total_seconds
         audio_duration = audio.metadata.duration_seconds