videopython 0.40.0__tar.gz → 0.42.0__tar.gz

{videopython-0.40.0 → videopython-0.42.0}/PKG-INFO

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

{videopython-0.40.0 → videopython-0.42.0}/README.md

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

{videopython-0.40.0 → videopython-0.42.0}/pyproject.toml

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

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/ai/transforms.py

@@ -3,17 +3,21 @@
 from __future__ import annotations
 
 import logging
+import tempfile
+import uuid
+from collections.abc import Iterable
+from pathlib import Path
 from typing import ClassVar, Literal
 
-import cv2
 import numpy as np
 from pydantic import Field
 from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
-from videopython.base.video import Video, VideoMetadata
-from videopython.editing.operation import OpCategory, Operation
+from videopython.base.video import FrameIterator, Video, VideoMetadata
+from videopython.editing._ass import escape_filter_value
+from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
 logger = logging.getLogger(__name__)
 
@@ -29,13 +33,19 @@ class FaceTrackingCrop(Operation):
     Useful for creating vertical (9:16) content from horizontal (16:9) video
     by tracking the speaker's face and keeping it framed.
 
-    Supports GPU acceleration for faster processing with optional frame sampling
-    and simple cinematographic framing rules (headroom / thirds) plus optional
-    movement speed clamping.
+    The crop window has a fixed size -- the largest ``target_aspect`` box
+    that fits the frame (also the output size, so no resampling happens) --
+    and its position follows the smoothed face track. On the streaming path
+    the detection pass runs at plan-compile time over a bounded decode of
+    exactly the frames the filter will see, and the track compiles to a
+    per-frame ``crop`` position command file (ffmpeg ``sendcmd``): zero
+    per-frame Python at render time.
     """
 
     op: Literal["face_crop"] = "face_crop"
     category: ClassVar[OpCategory] = OpCategory.TRANSFORM
+    streamable: ClassVar[bool] = True
+    compiles_from_source: ClassVar[bool] = True
 
     target_aspect: tuple[int, int] = Field((9, 16), description="Output aspect ratio as (width, height).")
     face_selection: Literal["largest", "centered", "index"] = Field(
@@ -58,7 +68,11 @@ class FaceTrackingCrop(Operation):
     smoothing: float = Field(0.8, ge=0, le=1, description="Position smoothing factor (0-1, higher = smoother).")
     max_speed: float | None = Field(None, gt=0, description="Optional max camera movement per frame (normalized).")
     fallback: Literal["center", "last_position", "full_frame"] = Field(
-        "last_position", description="Behavior when no face detected."
+        "last_position",
+        description=(
+            'Behavior when no face detected. "center" and "full_frame" both center the crop '
+            '("full_frame" kept for plan compatibility); "last_position" holds the last tracked crop.'
+        ),
     )
     detection_interval: int = Field(3, ge=1, description="Frames between face detections.")
     backend: Literal["cpu", "gpu", "auto"] = Field("auto", description='Detection backend - "cpu", "gpu", or "auto".')
@@ -77,13 +91,12 @@ class FaceTrackingCrop(Operation):
         return (face_cx, face_cy - self.headroom)
 
     def _resolved_output_dims(self, w: int, h: int) -> tuple[int, int]:
-        """Output ``(width, height)`` after the crop + resize.
+        """Output ``(width, height)`` -- the fixed crop-window size.
 
-        Every frame is resized to this size regardless of the per-frame face
-        position, so it is a pure function of the input dimensions and
-        ``target_aspect``. Single source of truth shared by :meth:`apply` and
-        :meth:`predict_metadata` (mirrors ``Resize._resolve_dims`` /
-        ``Crop._resolve_box``), so the dry-run cannot disagree with the render.
+        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
+        dry-run cannot disagree with the render.
         """
         target_ratio = self.target_aspect[0] / self.target_aspect[1]
         if target_ratio < w / h:
@@ -109,44 +122,20 @@ class FaceTrackingCrop(Operation):
         scale = self.max_speed / distance
         return (current[0] + dx * scale, current[1] + dy * scale)
 
-    def _calculate_crop_region(
+    def _track_crop_positions(
         self,
-        face_cx: float,
-        face_cy: float,
-        face_w: float,
-        face_h: float,
+        frames: Iterable[np.ndarray],
         frame_w: int,
         frame_h: int,
-        center_position: tuple[float, float] | None = None,
-    ) -> tuple[int, int, int, int]:
-        target_ratio = self.target_aspect[0] / self.target_aspect[1]
-        frame_ratio = frame_w / frame_h
-
-        if target_ratio < frame_ratio:
-            crop_h = floor_to_even(frame_h)
-            crop_w = floor_to_even(int(crop_h * target_ratio))
-        else:
-            crop_w = floor_to_even(frame_w)
-            crop_h = floor_to_even(int(crop_w / target_ratio))
-
-        min_face_dim = max(face_w * frame_w, face_h * frame_h)
-        min_crop_dim = min_face_dim * (1 + 2 * self.padding)
-        if crop_w < min_crop_dim * target_ratio:
-            crop_w = floor_to_even(min(int(min_crop_dim * target_ratio), frame_w))
-            crop_h = floor_to_even(min(int(crop_w / target_ratio), frame_h))
-
-        if center_position is None:
-            center_position = self._apply_framing_offset(face_cx, face_cy, face_h)
-
-        center_x = center_position[0] * frame_w
-        center_y = center_position[1] * frame_h
-        x = int(center_x - crop_w / 2)
-        y = int(center_y - crop_h / 2)
-        x = max(0, min(x, frame_w - crop_w))
-        y = max(0, min(y, frame_h - crop_h))
-        return (x, y, crop_w, crop_h)
+    ) -> list[tuple[int, int]]:
+        """Per-frame crop top-left positions for a fixed-size crop window.
 
-    def apply(self, video: Video) -> Video:
+        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.
+        """
+        out_w, out_h = self._resolved_output_dims(frame_w, frame_h)
         tracker = FaceTracker(
             selection_strategy=self.face_selection,
             face_index=self.face_index,
@@ -155,16 +144,31 @@ class FaceTrackingCrop(Operation):
             backend=self.backend,
             sample_rate=self.sample_rate,
         )
+        default = ((frame_w - out_w) // 2, (frame_h - out_h) // 2)
+        last = default
+        current_position = (0.5, 0.5)
+        positions: list[tuple[int, int]] = []
+        for i, frame in enumerate(frames):
+            face_info = tracker.detect_and_track(frame, i)
+            if face_info:
+                cx, cy, _fw, fh = face_info
+                target = self._apply_framing_offset(cx, cy, fh)
+                current_position = self._clamp_speed(current_position, target)
+                x = int(current_position[0] * frame_w - out_w / 2)
+                y = int(current_position[1] * frame_h - out_h / 2)
+                x = max(0, min(x, frame_w - out_w))
+                y = max(0, min(y, frame_h - out_h))
+                last = (x, y)
+                positions.append((x, y))
+            elif self.fallback == "last_position":
+                positions.append(last)
+            else:  # "center" / "full_frame" (the latter kept for plan compat)
+                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)
-
-        default_x = (w - out_w) // 2
-        default_y = (h - out_h) // 2
-        last_crop = (default_x, default_y, out_w, out_h)
-        current_position = (0.5, 0.5)
-
-        framing_label = self.framing_rule if self.framing_rule != "offset" else "legacy-offset"
         logger.info(
             "Face tracking crop: %dx%d -> %dx%d (%d:%d, framing=%s)",
             w,
@@ -173,33 +177,55 @@ class FaceTrackingCrop(Operation):
             out_h,
             self.target_aspect[0],
             self.target_aspect[1],
-            framing_label,
+            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
 
-        new_frames = []
-        for i in tqdm(range(len(video.frames)), desc="Face tracking crop"):
-            frame = video.frames[i]
-            face_info = tracker.detect_and_track(frame, i)
+    def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
+        """Compile the face track to a per-frame ``crop`` position command file.
 
-            if face_info:
-                cx, cy, fw, fh = face_info
-                target_position = self._apply_framing_offset(cx, cy, fh)
-                current_position = self._clamp_speed(current_position, target_position)
-                crop = self._calculate_crop_region(cx, cy, fw, fh, w, h, center_position=current_position)
-                last_crop = crop
-            else:
-                if self.fallback == "center":
-                    crop = (default_x, default_y, out_w, out_h)
-                elif self.fallback == "last_position":
-                    crop = last_crop
-                else:  # full_frame
-                    crop = (0, 0, w, h)
-
-            x, y, cw, ch = crop
-            cropped = frame[y : y + ch, x : x + cw]
-            if cropped.shape[1] != out_w or cropped.shape[0] != out_h:
-                cropped = cv2.resize(cropped, (out_w, out_h), interpolation=cv2.INTER_AREA)
-            new_frames.append(cropped)
-
-        video.frames = np.array(new_frames, dtype=np.uint8)
-        return video
+        Runs the detection pass at plan-compile time over a bounded decode of
+        the segment (through the same decode-stage filter prefix the render
+        will use, so the detector sees identical frames), then emits one
+        ``sendcmd`` interval per frame driving a fixed-size ``crop``. Returns
+        ``None`` when the input frames are not reproducible at compile time
+        (``decode_filters is None`` -- the op sits behind per-frame Python
+        effects) or the source is unknown.
+        """
+        if ctx.source_path is None or ctx.decode_filters is None or ctx.frame_count <= 0:
+            return None
+        out_w, out_h = self._resolved_output_dims(ctx.width, ctx.height)
+
+        with FrameIterator(
+            ctx.source_path,
+            start_second=ctx.start_second,
+            end_second=ctx.end_second,
+            vf_filters=list(ctx.decode_filters),
+            output_width=ctx.width,
+            output_height=ctx.height,
+        ) as decoder:
+            frames = (frame for _, frame in decoder)
+            positions = self._track_crop_positions(
+                tqdm(frames, desc="Face tracking (compile)", total=ctx.frame_count), ctx.width, ctx.height
+            )
+        if not positions:
+            return None
+
+        label = f"fc{uuid.uuid4().hex[:8]}"
+        lines = []
+        for i, (x, y) in enumerate(positions):
+            t0 = i / ctx.fps
+            t1 = (i + 1) / ctx.fps
+            lines.append(f"{t0:.6f}-{t1:.6f} crop@{label} x {x}, crop@{label} y {y};")
+        tmp = tempfile.NamedTemporaryFile("w", suffix=".cmd", delete=False, encoding="utf-8")
+        try:
+            tmp.write("\n".join(lines) + "\n")
+        finally:
+            tmp.close()
+        cmd_path = Path(tmp.name)
+        ctx.owned_files.append(cmd_path)
+
+        x0, y0 = positions[0]
+        return f"sendcmd=f={escape_filter_value(str(cmd_path))},crop@{label}=w={out_w}:h={out_h}:x={x0}:y={y0}"

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/base/__init__.py

@@ -14,19 +14,16 @@ from .draw_detections import DetectionStyle, class_color, draw_detections
 from .exceptions import (
     AudioError,
     AudioLoadError,
-    OutOfBoundsError,
     PlanError,
     PlanErrorCode,
     PlanRepair,
     PlanValidationError,
-    TextRenderError,
     TransformError,
     VideoError,
     VideoLoadError,
     VideoMetadataError,
     VideoPythonError,
 )
-from .image_text import AnchorPoint, ImageText, TextAlign
 from .transcription import Transcription, TranscriptionSegment, TranscriptionWord
 from .video import FrameIterator, Video, VideoMetadata
 
@@ -43,17 +40,11 @@ __all__ = [
     "AudioError",
     "AudioLoadError",
     "TransformError",
-    "TextRenderError",
-    "OutOfBoundsError",
     # Structured plan validation / repair
     "PlanError",
     "PlanErrorCode",
     "PlanValidationError",
     "PlanRepair",
-    # Text rendering primitives
-    "ImageText",
-    "TextAlign",
-    "AnchorPoint",
     # Detection overlay renderer (AI-free)
     "draw_detections",
     "DetectionStyle",

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/base/exceptions.py

@@ -66,18 +66,6 @@ class TransformError(VideoPythonError):
     pass
 
 
-class TextRenderError(VideoPythonError):
-    """Base exception for text rendering errors."""
-
-    pass
-
-
-class OutOfBoundsError(TextRenderError):
-    """Raised when text would be rendered outside image bounds."""
-
-    pass
-
-
 class PlanErrorCode(str, Enum):
     """Machine-readable failure classes raised while validating a ``VideoEdit``.
 
@@ -103,9 +91,8 @@ class PlanErrorCode(str, Enum):
     # Assembly / structural.
     UNKNOWN_OP = "unknown_op"
     CONCAT_MISMATCH = "concat_mismatch"
-    SUBTITLE_UNFITTABLE = "subtitle_unfittable"
     POST_OP_REQUIRES_CONTEXT = "post_op_requires_context"
-    # Streaming strictness (opt-in via strict_streaming).
+    # Streaming: unstreamable op at its plan position (always reported).
     STREAMING_FALLBACK = "streaming_fallback"
 
 
@@ -116,7 +103,7 @@ class PlanError:
     ``location`` is a path into the plan (e.g. ``'segments[1].operations[0]'``);
     the remaining fields are populated when meaningful for the ``code``.
     ``detail`` carries a short human-readable cause when the code alone is not
-    actionable (e.g. *why* an op forces the eager fallback) -- prose meant for
+    actionable (e.g. *why* an op cannot stream at its plan position) -- prose meant for
     LLM refine-loop feedback, not for branching.
     """
 

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/base/fonts/__init__.py

@@ -12,10 +12,18 @@ unreadable font:
 from __future__ import annotations
 
 from importlib.resources import as_file, files
+from pathlib import Path
 
 from PIL import ImageFont
 
-__all__ = ["BUNDLED_FONTS", "DEFAULT_FONT_FILENAME", "FONT_NAMES", "load_font"]
+__all__ = [
+    "BUNDLED_FONTS",
+    "BUNDLED_FONT_FAMILIES",
+    "DEFAULT_FONT_FILENAME",
+    "FONT_NAMES",
+    "bundled_fonts_dir",
+    "load_font",
+]
 
 DEFAULT_FONT_FILENAME = "DejaVuSans.ttf"
 
@@ -31,6 +39,29 @@ BUNDLED_FONTS: dict[str, str] = {
 
 FONT_NAMES: list[str] = sorted(BUNDLED_FONTS)
 
+# Registered NAME (or None for the default) -> (family name, is-bold-face),
+# exactly as declared in each file's name table. Renderers that match fonts by
+# family name -- libass via the ffmpeg ``subtitles=`` filter's ``fontsdir`` --
+# need these, not the filenames. Verified against the bundled .ttf files
+# (PIL ``ImageFont.getname()``); a test pins them.
+BUNDLED_FONT_FAMILIES: dict[str | None, tuple[str, bool]] = {
+    None: ("DejaVu Sans", False),
+    "poppins-bold": ("Poppins", True),
+    "lato-bold": ("Lato", True),
+    "anton": ("Anton", False),
+    "bebas-neue": ("Bebas Neue", False),
+}
+
+
+def bundled_fonts_dir() -> Path:
+    """Filesystem directory holding the bundled .ttf files.
+
+    For ffmpeg/libass ``fontsdir`` wiring, which needs a real directory path.
+    Standard (non-zip) installs ship the package unpacked, so the resources
+    root is a plain directory.
+    """
+    return Path(str(files(__package__)))
+
 
 def _try_truetype(path: str, font_size: int) -> ImageFont.FreeTypeFont | None:
     try:

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/base/video.py

@@ -234,12 +234,16 @@ class FrameIterator:
         if self.start_second > 0:
             cmd.extend(["-ss", str(self.start_second)])
 
-        cmd.extend(["-i", str(self.path)])
-
+        # Input-side -t: trim the SOURCE segment before the filter chain. As
+        # an output option it would instead cap the post-filter duration,
+        # silently truncating duration-extending filters (slow-motion setpts,
+        # freeze-frame loop).
         if self.end_second is not None:
             duration = self.end_second - self.start_second
             cmd.extend(["-t", str(duration)])
 
+        cmd.extend(["-i", str(self.path)])
+
         if self._vf_filters:
             cmd.extend(["-vf", ",".join(self._vf_filters)])
 

{videopython-0.40.0 → videopython-0.42.0}/src/videopython/editing/__init__.py

@@ -1,3 +1,4 @@
+from ._ass import AnchorPoint
 from .effects import (
     Blur,
     ChromaticAberration,
@@ -32,7 +33,6 @@ from .transforms import (
     FreezeFrame,
     ResampleFPS,
     Resize,
-    Reverse,
     SilenceRemoval,
     SpeedChange,
 )
@@ -53,7 +53,6 @@ __all__ = [
     "Crop",
     "CropMode",
     "SpeedChange",
-    "Reverse",
     "FreezeFrame",
     "SilenceRemoval",
     # Effects
@@ -83,6 +82,8 @@ __all__ = [
     # Plan runner
     "VideoEdit",
     "SegmentConfig",
+    # Subtitle placement
+    "AnchorPoint",
     # Streamability report
     "StreamabilityReport",
     "OpStreamability",