videopython 0.34.1__tar.gz → 0.35.0__tar.gz

{videopython-0.34.1 → videopython-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.34.1
+Version: 0.35.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -12,15 +12,15 @@ Keywords: ai,editing,generation,movie,opencv,python,shorts,video,videopython
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: <3.14,>=3.10
+Requires-Python: <3.14,>=3.11
 Requires-Dist: numpy>=1.25.2
 Requires-Dist: opencv-python-headless>=4.9.0.80
 Requires-Dist: pillow>=12.1.1
 Requires-Dist: pydantic>=2.8.0
+Requires-Dist: resvg-py>=0.3.2
 Requires-Dist: tqdm>=4.66.3
 Provides-Extra: ai
 Requires-Dist: accelerate>=0.29.2; extra == 'ai'
@@ -67,7 +67,7 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + local AI features (GPU recommended)
 ```
 
-Python `>=3.10, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
+Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start
 

{videopython-0.34.1 → videopython-0.35.0}/README.md

@@ -18,7 +18,7 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + local AI features (GPU recommended)
 ```
 
-Python `>=3.10, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
+Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start
 

{videopython-0.34.1 → videopython-0.35.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.34.1"
+version = "0.35.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -9,7 +9,7 @@ authors = [
 ]
 license = { text = "Apache-2.0" }
 readme = "README.md"
-requires-python = ">=3.10, <3.14"
+requires-python = ">=3.11, <3.14"
 keywords = [
     "python",
     "videopython",
@@ -24,7 +24,6 @@ keywords = [
 classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -35,6 +34,7 @@ dependencies = [
     "numpy>=1.25.2",
     "opencv-python-headless>=4.9.0.80",
     "pillow>=12.1.1",
+    "resvg-py>=0.3.2",
     "tqdm>=4.66.3",
     "pydantic>=2.8.0",
 ]
@@ -203,7 +203,7 @@ markers = [
 
 [tool.ruff]
 line-length = 120
-target-version = "py310"
+target-version = "py311"
 
 [tool.ruff.lint]
 select = [

{videopython-0.34.1 → videopython-0.35.0}/src/videopython/editing/__init__.py

@@ -8,6 +8,7 @@ from .effects import (
     Flash,
     FullImageOverlay,
     Glitch,
+    ImageOverlay,
     Kaleidoscope,
     KenBurns,
     MirrorFlip,
@@ -56,6 +57,7 @@ __all__ = [
     "SilenceRemoval",
     # Effects
     "FullImageOverlay",
+    "ImageOverlay",
     "Blur",
     "Zoom",
     "ColorGrading",

{videopython-0.34.1 → videopython-0.35.0}/src/videopython/editing/effects.py

@@ -14,6 +14,7 @@ audio after ``_apply`` returns.
 from __future__ import annotations
 
 import logging
+from io import BytesIO
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Literal
 
@@ -29,13 +30,14 @@ from videopython.editing.operation import Effect
 
 if TYPE_CHECKING:
     from videopython.audio import Audio
-    from videopython.base.video import Video
+    from videopython.base.video import Video, VideoMetadata
 
 logger = logging.getLogger(__name__)
 
 __all__ = [
     "Effect",
     "FullImageOverlay",
+    "ImageOverlay",
     "Blur",
     "Zoom",
     "ColorGrading",
@@ -771,6 +773,220 @@ class TextOverlay(Effect):
         return video
 
 
+class ImageOverlay(Effect):
+    """Composites a scaled image at an anchored position on every frame in the window.
+
+    A resolution-independent watermark / logo / brand mark. Unlike
+    :class:`FullImageOverlay` (full-frame only, raises on size mismatch), the
+    image is scaled to a fraction of the frame *width* and placed at an
+    anchored normalized position, so one config works across 1080p / 4k /
+    vertical / square. Loaded just-in-time from ``source`` so the op stays
+    JSON-serialisable. Off-frame or oversized placement clips to a partial
+    paste or a no-op -- the same contract as :class:`TextOverlay`, never an
+    error; only an unreadable ``source`` is rejected (in ``predict_metadata``).
+
+    ``source`` may be a raster image (PNG/JPEG/WebP) or an SVG (detected by the
+    ``.svg`` extension). An SVG is rasterised by ``resvg`` *at the exact target
+    pixel width* -- crisp at any frame size, not a blurry upscale of a
+    fixed-size bitmap -- with a transparent background and no remote-resource
+    fetching (the local path only; no SSRF). SVGs containing text depend on the
+    fonts available at render time.
+    """
+
+    op: Literal["image_overlay"] = "image_overlay"
+    streamable: ClassVar[bool] = True
+
+    source: Path = Field(
+        description=(
+            "Path to an image file: a raster RGB/RGBA image (PNG/JPEG/WebP) or "
+            "an SVG (`.svg`, rasterised at the target resolution). Loaded at "
+            "apply time; kept JSON-serialisable as a path."
+        ),
+    )
+    scale: float = Field(
+        0.15,
+        gt=0,
+        le=1,
+        description=(
+            "Overlay width as a fraction of frame width (0-1). Height follows "
+            "the image's aspect ratio. Resolution-independent."
+        ),
+    )
+    opacity: float = Field(
+        1.0,
+        ge=0,
+        le=1,
+        description="Multiplies the image's own alpha. 0 = fully transparent, 1 = use the image alpha unchanged.",
+    )
+    position: tuple[float, float] = Field(
+        (0.95, 0.95),
+        description=(
+            "Where to place the overlay as normalized (x, y) coordinates. "
+            "(0, 0) = top-left corner, (1, 1) = bottom-right corner."
+        ),
+    )
+    anchor: Literal["center", "top_left", "top_center", "bottom_center", "bottom_left", "bottom_right"] = Field(
+        "bottom_right",
+        description="Which point of the overlay box sits at the position coordinate.",
+    )
+
+    _overlay_rgba: np.ndarray | None = PrivateAttr(default=None)
+    _svg_cache: dict[int, np.ndarray] = PrivateAttr(default_factory=dict)
+    _stream_noop: bool = PrivateAttr(default=False)
+    _stream_alpha: np.ndarray | None = PrivateAttr(default=None)
+    _stream_rgb: np.ndarray | None = PrivateAttr(default=None)
+    _stream_dst: tuple[int, int, int, int] = PrivateAttr(default=(0, 0, 0, 0))
+
+    @model_validator(mode="after")
+    def _validate_position(self) -> ImageOverlay:
+        if not (0.0 <= self.position[0] <= 1.0 and 0.0 <= self.position[1] <= 1.0):
+            raise ValueError("position values must be in range [0, 1]")
+        return self
+
+    def _is_svg(self) -> bool:
+        return self.source.suffix.lower() == ".svg"
+
+    def predict_metadata(self, meta: VideoMetadata, **_context: Any) -> VideoMetadata:
+        """Reject only a missing/unreadable ``source`` (see :meth:`Operation.predict_metadata`).
+
+        An unreadable source is the one failure ``run()`` cannot survive -- it
+        would raise mid-stream after expensive frame decode -- so it is caught
+        at ``validate()`` time, symmetric with ``TranscriptionOverlay``.
+        Geometry (oversized / off-frame) is deliberately *not* checked here: it
+        clips to a valid no-op like :class:`TextOverlay`, so rejecting it would
+        break that contract and the parity with the op this is modeled on. Both
+        checks are cheap (a header ``verify()`` / a 1px SVG parse, no full
+        decode), so ``validate()`` stays frame-free.
+        """
+        try:
+            if self._is_svg():
+                import resvg_py
+
+                resvg_py.svg_to_bytes(svg_path=str(self.source), width=1)
+            else:
+                with Image.open(self.source) as im:
+                    im.verify()
+        except (OSError, ValueError) as exc:
+            raise ValueError(f"image_overlay source {str(self.source)!r} is not a readable image: {exc}") from exc
+        return meta
+
+    def _rasterize_svg(self, target_w: int) -> np.ndarray:
+        cached = self._svg_cache.get(target_w)
+        if cached is not None:
+            return cached
+        # Lazy import: only when an SVG source is actually used. resvg renders
+        # at the exact target width (height proportional to the viewBox) with a
+        # transparent background and never fetches remote resources.
+        import resvg_py
+
+        png = resvg_py.svg_to_bytes(svg_path=str(self.source), width=target_w)
+        arr = np.array(Image.open(BytesIO(bytes(png))).convert("RGBA"), dtype=np.uint8)
+        self._svg_cache[target_w] = arr
+        return arr
+
+    def _load_overlay(self) -> np.ndarray:
+        if self._overlay_rgba is not None:
+            return self._overlay_rgba
+        img = Image.open(self.source).convert("RGBA")
+        self._overlay_rgba = np.array(img, dtype=np.uint8)
+        return self._overlay_rgba
+
+    def _compute_position(self, frame_width: int, frame_height: int, img_w: int, img_h: int) -> tuple[int, int]:
+        # Copied verbatim from TextOverlay: ImageOverlay's anchor Literal is
+        # deliberately the same set, so the geometry is shared by construction.
+        px = int(self.position[0] * frame_width)
+        py = int(self.position[1] * frame_height)
+
+        if self.anchor == "center":
+            return px - img_w // 2, py - img_h // 2
+        if self.anchor == "top_left":
+            return px, py
+        if self.anchor == "top_center":
+            return px - img_w // 2, py
+        if self.anchor == "bottom_center":
+            return px - img_w // 2, py - img_h
+        if self.anchor == "bottom_left":
+            return px, py - img_h
+        # bottom_right
+        return px - img_w, py - img_h
+
+    def _resized_overlay(self, frame_w: int) -> np.ndarray:
+        target_w = max(1, round(self.scale * frame_w))
+        if self._is_svg():
+            # Rasterise the vector at the target size (crisp) rather than
+            # upscaling a fixed bitmap. resvg derives height from the viewBox.
+            return self._rasterize_svg(target_w)
+        overlay = self._load_overlay()
+        src_h, src_w = overlay.shape[:2]
+        target_h = max(1, round(target_w * src_h / src_w))
+        if (target_w, target_h) == (src_w, src_h):
+            return overlay
+        resized = Image.fromarray(overlay).resize((target_w, target_h), Image.LANCZOS)
+        return np.array(resized, dtype=np.uint8)
+
+    def _blend_params(
+        self, frame_w: int, frame_h: int
+    ) -> tuple[np.ndarray, np.ndarray, tuple[int, int, int, int]] | None:
+        """Placement + blend inputs shared by the eager and streaming paths.
+
+        Single source of truth so the two paths cannot drift -- the
+        eager/stream parity-hole class of bug fixed in 0.34.1. Returns ``None``
+        when the overlay lands fully off-frame (the effect is a no-op).
+        """
+        overlay = self._resized_overlay(frame_w)
+        oh, ow = overlay.shape[:2]
+        x, y = self._compute_position(frame_w, frame_h, ow, oh)
+
+        src_x = max(0, -x)
+        src_y = max(0, -y)
+        dst_x = max(0, x)
+        dst_y = max(0, y)
+        paste_w = min(ow - src_x, frame_w - dst_x)
+        paste_h = min(oh - src_y, frame_h - dst_y)
+
+        if paste_w <= 0 or paste_h <= 0:
+            return None
+
+        region = overlay[src_y : src_y + paste_h, src_x : src_x + paste_w]
+        alpha = (region[:, :, 3:4].astype(np.float32) / 255.0) * self.opacity
+        rgb = region[:, :, :3].astype(np.float32)
+        return alpha, rgb, (dst_y, dst_x, paste_h, paste_w)
+
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int) -> None:
+        params = self._blend_params(width, height)
+        if params is None:
+            self._stream_noop = True
+            return
+        self._stream_noop = False
+        self._stream_alpha, self._stream_rgb, self._stream_dst = params
+
+    def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
+        if self._stream_noop:
+            return frame
+        assert self._stream_alpha is not None and self._stream_rgb is not None
+        dy, dx, ph, pw = self._stream_dst
+        region = frame[dy : dy + ph, dx : dx + pw]
+        blended = (
+            self._stream_rgb * self._stream_alpha + region.astype(np.float32) * (1.0 - self._stream_alpha)
+        ).astype(np.uint8)
+        frame[dy : dy + ph, dx : dx + pw] = blended
+        return frame
+
+    def _apply(self, video: Video) -> Video:
+        frame_h, frame_w = video.frame_shape[:2]
+        params = self._blend_params(frame_w, frame_h)
+        if params is None:
+            return video
+        alpha, rgb, (dy, dx, ph, pw) = params
+
+        logger.info("Applying image overlay...")
+        for frame in tqdm(video.frames, desc="Image overlay"):
+            region = frame[dy : dy + ph, dx : dx + pw]
+            blended = (rgb * alpha + region.astype(np.float32) * (1.0 - alpha)).astype(np.uint8)
+            frame[dy : dy + ph, dx : dx + pw] = blended
+        return video
+
+
 class Shake(Effect):
     """Per-frame camera shake: jitters every frame by a random or rhythmic offset.
 

{videopython-0.34.1 → videopython-0.35.0}/src/videopython/editing/operation.py

@@ -175,7 +175,18 @@ class Operation(BaseModel):
         raise NotImplementedError(f"{type(self).__name__}.apply not implemented")
 
     def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
-        """Predict output metadata from input metadata. Default: identity."""
+        """Predict output metadata from input metadata. Default: identity.
+
+        Run during ``VideoEdit.validate()``'s dry-run, before any frames are
+        decoded. Beyond predicting shape, this is the fail-fast gate, and it
+        has one contract: **reject exactly the plans that would otherwise crash
+        or do unrecoverable / expensive work in** :meth:`apply` **/** ``run()``;
+        anything ``run()`` can absorb by graceful degradation is NOT rejected.
+        ``TranscriptionOverlay`` rejects un-fittable subtitles (they used to
+        crash mid-render); ``TextOverlay``/``ImageOverlay`` do not reject
+        off-frame geometry (it clips to a valid no-op). Keep the check
+        metadata-cheap -- no frame decode.
+        """
         return meta
 
     def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None: