videopython 0.45.0__tar.gz → 0.47.0__tar.gz

{videopython-0.45.0 → videopython-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.45.0
+Version: 0.47.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -158,7 +158,7 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 - **`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, 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 (resize, crop, fps, speed, freeze, silence removal; cutting is the segment's own start/end) 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.45.0 → videopython-0.47.0}/README.md

@@ -72,7 +72,7 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 - **`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, 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 (resize, crop, fps, speed, freeze, silence removal; cutting is the segment's own start/end) 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.45.0 → videopython-0.47.0}/pyproject.toml

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

{videopython-0.45.0 → videopython-0.47.0}/src/videopython/ai/effects.py

@@ -9,7 +9,7 @@ AI-free renderer in :mod:`videopython.base.draw_detections`.
 
 from __future__ import annotations
 
-from typing import Any, ClassVar, Literal
+from typing import Any, Literal
 
 import numpy as np
 from pydantic import Field, PrivateAttr
@@ -39,7 +39,6 @@ class ObjectDetectionOverlay(Effect):
     """
 
     op: Literal["object_detection_overlay"] = "object_detection_overlay"
-    streamable: ClassVar[bool] = True
 
     confidence_threshold: float = Field(0.5, ge=0, le=1, description="Minimum detection confidence to draw a box, 0-1.")
     class_filter: list[str] | None = Field(

{videopython-0.45.0 → videopython-0.47.0}/src/videopython/ai/transforms.py

@@ -44,7 +44,6 @@ class FaceTrackingCrop(Operation):
 
     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).")

{videopython-0.45.0 → videopython-0.47.0}/src/videopython/editing/effects.py

@@ -15,6 +15,7 @@ override :meth:`Effect.predict_metadata`. Anchored RGBA overlays
 from __future__ import annotations
 
 import logging
+import tempfile
 from io import BytesIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Literal
@@ -24,6 +25,7 @@ import numpy as np
 from PIL import Image, ImageDraw, ImageFont
 from pydantic import Field, PrivateAttr, model_validator
 
+from videopython.base._ffmpeg import escape_filter_value
 from videopython.base.description import BoundingBox
 from videopython.base.exceptions import PlanError, PlanErrorCode, PlanValidationError
 from videopython.base.fonts import load_font
@@ -70,7 +72,6 @@ class FullImageOverlay(Effect):
     """
 
     op: Literal["full_image_overlay"] = "full_image_overlay"
-    streamable: ClassVar[bool] = True
     llm_exposed: ClassVar[bool] = False
 
     source: Path = Field(
@@ -140,7 +141,6 @@ class Blur(Effect):
     """Applies Gaussian blur that can stay constant or ramp up/down over the clip."""
 
     op: Literal["blur_effect"] = "blur_effect"
-    streamable: ClassVar[bool] = True
 
     mode: Literal["constant", "ascending", "descending"] = Field(
         description=(
@@ -189,7 +189,6 @@ class Zoom(Effect):
     """Progressively zooms into or out of the frame center over the clip duration."""
 
     op: Literal["zoom_effect"] = "zoom_effect"
-    streamable: ClassVar[bool] = True
 
     zoom_factor: float = Field(
         gt=1,
@@ -230,7 +229,6 @@ class ColorGrading(Effect):
     """Adjusts color properties: brightness, contrast, saturation, and temperature."""
 
     op: Literal["color_adjust"] = "color_adjust"
-    streamable: ClassVar[bool] = True
 
     brightness: float = Field(
         0.0,
@@ -283,7 +281,6 @@ class Vignette(Effect):
     """Darkens the edges of the frame, drawing attention to the center."""
 
     op: Literal["vignette"] = "vignette"
-    streamable: ClassVar[bool] = True
 
     strength: float = Field(
         0.5,
@@ -331,7 +328,6 @@ class KenBurns(Effect):
     """
 
     op: Literal["ken_burns"] = "ken_burns"
-    streamable: ClassVar[bool] = True
 
     start_region: BoundingBox = Field(
         description="Starting crop region as a BoundingBox with normalized 0-1 coordinates."
@@ -411,7 +407,6 @@ class Fade(Effect):
     """Fades video and audio to or from black."""
 
     op: Literal["fade"] = "fade"
-    streamable: ClassVar[bool] = True
     audio_coupled: ClassVar[bool] = True
 
     mode: Literal["in", "out", "in_out"] = Field(
@@ -513,7 +508,6 @@ class VolumeAdjust(Effect):
     """Changes audio volume within a time range without affecting video frames."""
 
     op: Literal["volume_adjust"] = "volume_adjust"
-    streamable: ClassVar[bool] = True
     audio_coupled: ClassVar[bool] = True
 
     volume: float = Field(
@@ -690,7 +684,6 @@ class TextOverlay(_AnchoredOverlay):
     """Draws text on video frames, with auto word-wrap and optional background box."""
 
     op: Literal["text_overlay"] = "text_overlay"
-    streamable: ClassVar[bool] = True
 
     text: str = Field(min_length=1, description=r"The string to display. Use \n for line breaks.")
     position: tuple[float, float] = Field(
@@ -791,6 +784,91 @@ class TextOverlay(_AnchoredOverlay):
             self._rendered = self._render_text_image(frame_width, frame_height)
         return self._rendered
 
+    def _resolve_fontfile(self) -> Path | None:
+        """Filesystem path to the .ttf ``drawtext`` should render with, or ``None``.
+
+        Mirrors :func:`load_font`'s resolution down to a real file: a bundled
+        NAME -> its bundled .ttf; an explicit ``font_filename`` path that exists;
+        else the bundled DejaVu Sans default. ``None`` only when even DejaVu is
+        unreachable -- then ``load_font`` falls back to PIL's built-in bitmap
+        font, which ``drawtext`` cannot consume, so the op stays frame-only.
+        """
+        from videopython.base.fonts import BUNDLED_FONTS, DEFAULT_FONT_FILENAME, bundled_fonts_dir
+
+        name = self.font_filename or self.font
+        fonts_dir = bundled_fonts_dir()
+        if name:
+            bundled = BUNDLED_FONTS.get(name)
+            if bundled is not None:
+                candidate = fonts_dir / bundled
+                if candidate.is_file():
+                    return candidate
+            candidate = Path(name)
+            if candidate.is_file():
+                return candidate
+        default = fonts_dir / DEFAULT_FONT_FILENAME
+        return default if default.is_file() else None
+
+    @property
+    def compiles_to_filter(self) -> bool:
+        """Compile to ``drawtext`` when a real TrueType file resolves, else frame-only."""
+        return self._resolve_fontfile() is not None
+
+    def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
+        """Compile the anchored, word-wrapped text overlay to one ``drawtext`` entry.
+
+        The text is pre-wrapped with the SAME PIL metrics (:meth:`_wrap_text`)
+        the numpy twin uses and written to a ``textfile`` (registered on
+        ``ctx.owned_files`` for the runner to delete), so line breaks match
+        exactly -- drawtext has no pixel word-wrap. The box is
+        ``box=1:boxcolor=...:boxborderw=<padding>`` placed at the anchored
+        position :meth:`_compute_position` computes. Faithful *visual* twin
+        (freetype vs PIL metrics diverge a few px), re-baselined to ffmpeg.
+        Comma-join safe: every comma-bearing value is wrapped via
+        :func:`escape_filter_value`. yuv-safe (drawtext needs no rgb24).
+        """
+        fontfile = self._resolve_fontfile()
+        if fontfile is None:
+            return None
+
+        font = self._get_font()
+        max_px = int(self.max_width * ctx.width)
+        wrapped = self._wrap_text(self.text, font, max_px)
+
+        bbox = ImageDraw.Draw(Image.new("RGBA", (1, 1))).multiline_textbbox((0, 0), wrapped, font=font)
+        text_w = bbox[2] - bbox[0]
+        text_h = bbox[3] - bbox[1]
+        pad = self.background_padding
+        box_x, box_y = self._compute_position(ctx.width, ctx.height, text_w + 2 * pad, text_h + 2 * pad)
+
+        tmp = tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False, encoding="utf-8")
+        try:
+            tmp.write(wrapped)
+        finally:
+            tmp.close()
+        textfile = Path(tmp.name)
+        ctx.owned_files.append(textfile)
+
+        r, g, b = self.text_color
+        parts = [
+            f"textfile={escape_filter_value(str(textfile))}",
+            f"fontfile={escape_filter_value(str(fontfile))}",
+            f"fontsize={self.font_size}",
+            f"fontcolor={escape_filter_value(f'0x{r:02x}{g:02x}{b:02x}')}",
+            f"x={box_x + pad}",
+            f"y={box_y + pad}",
+        ]
+        if self.background_color is not None:
+            br, bg, bb, ba = self.background_color
+            parts.append("box=1")
+            parts.append(f"boxcolor={escape_filter_value(f'0x{br:02x}{bg:02x}{bb:02x}@{ba / 255:.4f}')}")
+            parts.append(f"boxborderw={pad}")
+        if self.window is not None:
+            start = 0.0 if self.window.start is None else float(self.window.start)
+            stop = ctx.frame_count / ctx.fps if self.window.stop is None else float(self.window.stop)
+            parts.append(f"enable={escape_filter_value(f'between(t,{start:g},{stop:g})')}")
+        return "drawtext=" + ":".join(parts)
+
 
 class ImageOverlay(_AnchoredOverlay):
     """Composites a scaled image at an anchored position on every frame in the window.
@@ -813,7 +891,6 @@ class ImageOverlay(_AnchoredOverlay):
     """
 
     op: Literal["image_overlay"] = "image_overlay"
-    streamable: ClassVar[bool] = True
     llm_exposed: ClassVar[bool] = False
 
     source: Path = Field(
@@ -935,7 +1012,6 @@ class Shake(Effect):
     """
 
     op: Literal["shake"] = "shake"
-    streamable: ClassVar[bool] = True
 
     intensity_px: float = Field(
         gt=0,
@@ -1001,7 +1077,6 @@ class PunchIn(Effect):
     """
 
     op: Literal["punch_in"] = "punch_in"
-    streamable: ClassVar[bool] = True
 
     zoom_factor: float = Field(
         gt=1.0,
@@ -1064,7 +1139,6 @@ class Flash(Effect):
     """
 
     op: Literal["flash"] = "flash"
-    streamable: ClassVar[bool] = True
 
     color: tuple[int, int, int] = Field(
         (255, 255, 255),
@@ -1128,7 +1202,6 @@ class ChromaticAberration(Effect):
     """
 
     op: Literal["chromatic_aberration"] = "chromatic_aberration"
-    streamable: ClassVar[bool] = True
 
     shift_px: int = Field(
         gt=0,
@@ -1196,7 +1269,6 @@ class Glitch(Effect):
     """
 
     op: Literal["glitch"] = "glitch"
-    streamable: ClassVar[bool] = True
 
     intensity: float = Field(
         0.5,
@@ -1258,7 +1330,6 @@ class FilmGrain(Effect):
     """
 
     op: Literal["film_grain"] = "film_grain"
-    streamable: ClassVar[bool] = True
 
     intensity: float = Field(
         0.1,
@@ -1297,7 +1368,6 @@ class Sharpen(Effect):
     """
 
     op: Literal["sharpen"] = "sharpen"
-    streamable: ClassVar[bool] = True
 
     amount: float = Field(
         1.0,
@@ -1339,7 +1409,6 @@ class Pixelate(Effect):
     """
 
     op: Literal["pixelate"] = "pixelate"
-    streamable: ClassVar[bool] = True
 
     block_size: int = Field(
         gt=1,
@@ -1388,7 +1457,6 @@ class MirrorFlip(Effect):
     """
 
     op: Literal["mirror_flip"] = "mirror_flip"
-    streamable: ClassVar[bool] = True
 
     mode: Literal[
         "horizontal",
@@ -1442,7 +1510,6 @@ class Kaleidoscope(Effect):
     """
 
     op: Literal["kaleidoscope"] = "kaleidoscope"
-    streamable: ClassVar[bool] = True
 
     segments: int = Field(
         6,

{videopython-0.45.0 → videopython-0.47.0}/src/videopython/editing/operation.py

@@ -18,7 +18,6 @@ Subclass contract::
 
         op: Literal["resize"] = "resize"
         category: ClassVar[OpCategory] = OpCategory.TRANSFORM
-        streamable: ClassVar[bool] = True
 
         width: int | None = Field(None, gt=0)
         height: int | None = Field(None, gt=0)
@@ -234,8 +233,8 @@ class Operation(BaseModel):
 
     Concrete subclasses MUST declare an ``op`` field with a single-value
     ``Literal[str]`` annotation; that value is the discriminator on the JSON
-    wire and the registry key. Subclasses may override the ``category``,
-    ``streamable``, and ``requires`` ClassVars.
+    wire and the registry key. Subclasses may override the ``category`` and
+    ``requires`` ClassVars.
 
     ``predict_metadata`` defaults to identity; ``to_ffmpeg_filter`` defaults to
     ``None`` (no filter compilation).
@@ -246,7 +245,6 @@ class Operation(BaseModel):
     op: str
 
     category: ClassVar[OpCategory] = OpCategory.SPECIAL
-    streamable: ClassVar[bool] = False
     requires: ClassVar[tuple[str, ...]] = ()
     compiles_from_source: ClassVar[bool] = False
     """Whether the op's filter compile decodes the source itself (face_crop's
@@ -265,6 +263,15 @@ class Operation(BaseModel):
     mirrors the same rule.
     """
     llm_exposed: ClassVar[bool] = True
+    internal_only: ClassVar[bool] = False
+    """Whether this op is engine-internal and must NOT be a chain op.
+
+    ``CutSeconds``/``CutFrames`` trim a segment, but trimming is the segment's own
+    ``start``/``end`` mechanism -- the engine constructs them directly. They have
+    no ffmpeg filter and no ``process_frame``, so this flag keeps them OUT of the
+    registry: they cannot appear in a plan's ``operations`` list or the LLM
+    schema, while direct construction (``CutSeconds(start=..., end=...)``) still
+    works. Default False (a normal chain op)."""
     time_fields: ClassVar[tuple[BoundedTimeField, ...]] = ()
     """Time-valued (seconds) fields :meth:`VideoEdit.repair` may clamp into range.
 
@@ -293,6 +300,12 @@ class Operation(BaseModel):
             raise TypeError(f"{cls.__name__}.op must be Literal of a single str, got {literal_values!r}")
         op_id = literal_values[0]
 
+        if cls.internal_only:
+            # Engine-internal op (CutSeconds/CutFrames): the op Literal is still
+            # validated above, but the op is kept out of the registry so it
+            # cannot be resolved as a chain op or exposed to the LLM.
+            return
+
         existing = Operation._registry.get(op_id)
         if existing is not None and existing is not cls:
             raise ValueError(
@@ -433,6 +446,19 @@ class Operation(BaseModel):
         """
         return None
 
+    def streams(self) -> bool:
+        """Whether this op streams in O(1) memory at its plan position.
+
+        Structural replacement for the former ``streamable`` ClassVar: a transform
+        streams iff it overrides :meth:`to_ffmpeg_filter`. :class:`Effect` widens
+        this (a frame effect streams via ``process_frame``; a filter effect via
+        ``compiles_to_filter``). The one case structure cannot express -- the
+        override exists but the filter compiles to ``None`` at this position -- is
+        caught at runtime by the ``STREAMING_UNSUPPORTED`` raise in
+        ``VideoEdit._compile_streaming_plans``.
+        """
+        return type(self).to_ffmpeg_filter is not Operation.to_ffmpeg_filter
+
 
 class Effect(Operation):
     """Operation that preserves shape and frame count, driven by per-frame streaming.
@@ -453,13 +479,7 @@ class Effect(Operation):
 
     category: ClassVar[OpCategory] = OpCategory.EFFECT
     audio_coupled: ClassVar[bool] = False
-    """Whether the effect mutates audio alongside pixels (``afade``/``volume``).
-
-    Audio-coupled effects cannot fold as post-operations across segment
-    boundaries: each segment's audio is processed independently, so a gain
-    envelope spanning a concat boundary would restart mid-ramp. The plan
-    builder and the streamability report both consult this.
-    """
+    """Whether the effect mutates audio alongside pixels (``afade``/``volume``)."""
 
     window: TimeRange | None = Field(
         None,
@@ -506,3 +526,14 @@ class Effect(Operation):
         ``frame_index`` is 0-based within this effect's active window.
         """
         raise NotImplementedError(f"{type(self).__name__} does not support streaming")
+
+    def streams(self) -> bool:
+        """An effect streams via per-frame Python (``process_frame``) or a filter.
+
+        Frame effects override :meth:`process_frame`; filter effects
+        (``add_subtitles``, ``vignette``, ...) instead set
+        :attr:`compiles_to_filter` and implement :meth:`to_ffmpeg_filter`.
+        ``add_subtitles`` streams *only* via the filter path (it does not override
+        ``process_frame``), so ``compiles_to_filter`` is consulted per-instance.
+        """
+        return type(self).process_frame is not Effect.process_frame or self.compiles_to_filter