videopython 0.51.0__tar.gz → 0.52.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.51.0
+Version: 0.52.0
 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.0}/pyproject.toml

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

{videopython-0.51.0 → videopython-0.52.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0}/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.0/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.0}/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.0}/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.0}/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.0}/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)
 
@@ -253,7 +250,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,
@@ -368,9 +365,9 @@ class LocalDubbingPipeline:
             # 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
+            from videopython.ai.dubbing.separation import merge_regions
 
-            speech_regions = _merge_regions(
+            speech_regions = merge_regions(
                 [(s.start, s.end) for s in transcription.segments],
                 audio_duration=source_audio.metadata.duration_seconds,
             )
@@ -401,10 +398,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,
             )
@@ -534,9 +531,9 @@ class LocalDubbingPipeline:
             if self._separator is None:
                 self._init_separator()
 
-            from videopython.ai.understanding.separation import _merge_regions
+            from videopython.ai.dubbing.separation import merge_regions
 
-            speech_regions = _merge_regions(
+            speech_regions = merge_regions(
                 [(s.start, s.end) for s in transcription.segments],
                 audio_duration=source_audio.metadata.duration_seconds,
             )

{videopython-0.51.0 → videopython-0.52.0}/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.0}/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.0/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,
@@ -185,7 +185,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.0}/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.0/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."""

videopython-0.52.0/src/videopython/ai/keyframe.py

@@ -0,0 +1,43 @@
+"""Keyframe encoding helpers for LLM / MCP image payloads.
+
+Public so transport layers (the MCP server) and the shared Ollama client both
+reach for the same downscale + PNG-encode helpers instead of importing privates
+across package boundaries.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+
+import cv2
+import numpy as np
+from PIL import Image
+
+# Bound a keyframe's longest side before PNG-encoding for an MCP/LLM payload.
+KEYFRAME_MAX_DIM = 768
+
+
+def downscale_keyframe(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:
+    """PNG-encode an RGB frame and return base64 ascii. Full resolution (no downscale)."""
+    buffer = io.BytesIO()
+    Image.fromarray(frame).save(buffer, format="PNG")
+    return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def keyframe_to_png_b64(frame: np.ndarray, max_dim: int = KEYFRAME_MAX_DIM) -> str:
+    """Downscale a keyframe then PNG-encode it as base64 -- the MCP transport payload.
+
+    SceneVLM captioning and the local planner deliberately encode full-resolution
+    frames via :func:`encode_png_b64` instead.
+    """
+    return encode_png_b64(downscale_keyframe(frame, max_dim=max_dim))

{videopython-0.51.0 → videopython-0.52.0}/src/videopython/ai/transforms.py

@@ -13,7 +13,7 @@ import numpy as np
 from pydantic import Field
 from tqdm import tqdm
 
-from videopython.ai.understanding.faces import FaceTracker
+from videopython.ai.understanding.faces import FaceSmoothingTracker
 from videopython.base._dimensions import floor_to_even
 from videopython.base._ffmpeg import escape_filter_value
 from videopython.base.video import FrameIterator, VideoMetadata
@@ -134,7 +134,7 @@ class FaceTrackingCrop(Operation):
         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(
+        tracker = FaceSmoothingTracker(
             selection_strategy=self.face_selection,
             face_index=self.face_index,
             smoothing=self.smoothing,

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

@@ -15,17 +15,19 @@ from videopython.ai._optional import lazy_exports
 if TYPE_CHECKING:
     # Redundant aliases = intentional re-exports (visible to mypy/IDE, not
     # flagged by ruff). Runtime resolution is lazy via __getattr__ below.
-    from .audio import AudioClassifier as AudioClassifier
     from .audio import AudioToText as AudioToText
-    from .faces import FaceTracker as FaceTracker
+    from .classification import AudioClassifier as AudioClassifier
+    from .faces import FaceShotTracker as FaceShotTracker
+    from .faces import FaceSmoothingTracker as FaceSmoothingTracker
     from .image import SceneVLM as SceneVLM
     from .objects import ObjectDetector as ObjectDetector
     from .temporal import SemanticSceneDetector as SemanticSceneDetector
 
 _exports: dict[str, str] = {
     "AudioToText": ".audio",
-    "AudioClassifier": ".audio",
-    "FaceTracker": ".faces",
+    "AudioClassifier": ".classification",
+    "FaceShotTracker": ".faces",
+    "FaceSmoothingTracker": ".faces",
     "ObjectDetector": ".objects",
     "SceneVLM": ".image",
     "SemanticSceneDetector": ".temporal",