videopython 0.34.1__tar.gz → 0.35.1__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.34.1"
+version = "0.35.1"
 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.1}/src/videopython/ai/generation/qwen3.py

@@ -92,6 +92,56 @@ _SPEECH_CHARS_DEFAULT = 12.0
 _LOW_LOGPROB_HINT_THRESHOLD = -1.0
 
 
+# Conservative chars-per-token used to size chunks without invoking the
+# tokenizer. Morphologically rich languages land around 1.5-2.0
+# chars/token; ASCII is ~3-4. We use the low end so chunks stay safe for
+# any source language.
+_CHARS_PER_TOKEN = 2.0
+# Token reserve for the system prompt + user-prompt envelope ("Input
+# segments:" / "Translations (...)" wrappers). Empirical upper bound.
+_PROMPT_OVERHEAD_TOKENS = 300
+# Per-segment JSON wrapper cost (keys, braces, commas, index). Added on
+# top of len(seg.text) when sizing chunks.
+_SEGMENT_ENVELOPE_CHARS = 40
+
+
+def _chunk_segment_indices(
+    segments: list[TranscriptionSegment],
+    n_ctx: int,
+    max_tokens: int,
+) -> list[list[int]]:
+    """Group positions in ``segments`` into batches that fit one Qwen call.
+
+    Each batch must satisfy ``prompt_tokens + max_tokens <= n_ctx``, which
+    llama.cpp enforces. We approximate prompt token count from character
+    length using ``_CHARS_PER_TOKEN``; the conservative ratio means a chunk
+    estimated at the budget will tokenize to comfortably less.
+
+    A segment whose own serialized form exceeds the per-call budget goes in
+    its own chunk anyway — better to let llama.cpp report a clean overflow
+    on one giant segment than to silently swallow it.
+    """
+    prompt_token_budget = n_ctx - max_tokens - _PROMPT_OVERHEAD_TOKENS
+    if prompt_token_budget <= 0:
+        return [[i] for i in range(len(segments))]
+    char_budget = int(prompt_token_budget * _CHARS_PER_TOKEN)
+
+    chunks: list[list[int]] = []
+    current: list[int] = []
+    current_chars = 0
+    for i, seg in enumerate(segments):
+        seg_chars = len(seg.text) + _SEGMENT_ENVELOPE_CHARS
+        if current and current_chars + seg_chars > char_budget:
+            chunks.append(current)
+            current = []
+            current_chars = 0
+        current.append(i)
+        current_chars += seg_chars
+    if current:
+        chunks.append(current)
+    return chunks
+
+
 def _target_chars_for(duration_seconds: float, target_lang: str) -> int:
     """Character-count budget for a segment of ``duration_seconds`` in ``target_lang``."""
     rate = _SPEECH_CHARS_PER_SEC.get(target_lang, _SPEECH_CHARS_DEFAULT)
@@ -170,9 +220,12 @@ class Qwen3Translator:
             ``DEFAULT_REPO_ID``; override for eval harnesses.
         filename: GGUF filename within ``repo_id``. Defaults to
             ``DEFAULT_FILENAME``.
-        n_ctx: llama.cpp context window. 8192 is plenty for a 15-min source;
-            raise for very long sources. Hard cap is the model's training
-            context (262K for Qwen3-4B-Instruct-2507).
+        n_ctx: llama.cpp context window. ``translate_segments`` splits the
+            input across multiple calls when it doesn't fit, so 8192 stays
+            safe even for very long sources; raise to reduce the number of
+            calls (and gain cross-segment context per call) at the cost of
+            VRAM. Hard cap is the model's training context (262K for
+            Qwen3-4B-Instruct-2507).
         max_tokens: Generation cap per call. 4× the input character count
             is a safe upper bound for translation output.
         temperature: Decoding temperature. 0.1 keeps output structurally
@@ -257,6 +310,52 @@ class Qwen3Translator:
         raw = response["choices"][0]["text"]
         return _parse_jsonl_response(raw)
 
+    def _qwen_translate_chunked(
+        self,
+        segments: list[TranscriptionSegment],
+        target_lang: str,
+        source_lang: str,
+        progress_callback: Callable[[float], None] | None = None,
+        progress_start: float = 0.0,
+        progress_end: float = 1.0,
+    ) -> dict[int, str]:
+        """Translate ``segments`` across one or more Qwen calls.
+
+        Returns a dict keyed by position in ``segments``. Splitting into
+        chunks keeps each call under llama.cpp's ``n_ctx`` cap — without
+        chunking, a long source with hundreds of dense segments easily
+        blows past the default 8192 token window.
+
+        Progress is reported as a linear ramp from ``progress_start`` to
+        ``progress_end``, one tick per chunk completed.
+        """
+        results: dict[int, str] = {}
+        if not segments:
+            if progress_callback is not None:
+                progress_callback(progress_end)
+            return results
+
+        chunks = _chunk_segment_indices(segments, self.n_ctx, self.max_tokens)
+        if len(chunks) > 1:
+            logger.info(
+                "Qwen3Translator: splitting %d segments into %d chunks (n_ctx=%d)",
+                len(segments),
+                len(chunks),
+                self.n_ctx,
+            )
+        for chunk_num, chunk_positions in enumerate(chunks):
+            chunk_segments = [segments[p] for p in chunk_positions]
+            chunk_result = self._qwen_translate(chunk_segments, target_lang, source_lang)
+            # chunk_result keys are 0..len(chunk_positions)-1; map back to
+            # positions in the caller-provided ``segments`` list.
+            for local_idx, text in chunk_result.items():
+                if 0 <= local_idx < len(chunk_positions):
+                    results[chunk_positions[local_idx]] = text
+            if progress_callback is not None:
+                fraction = (chunk_num + 1) / len(chunks)
+                progress_callback(progress_start + (progress_end - progress_start) * fraction)
+        return results
+
     def translate_segments(
         self,
         segments: list[TranscriptionSegment],
@@ -266,10 +365,10 @@ class Qwen3Translator:
     ) -> list[TranslatedSegment]:
         """Translate segments via Qwen with parse-retry + optional Marian fallback.
 
-        The progress_callback fires three times: 0.5 after the first
-        Qwen call, 0.9 after the optional retry/fallback, 1.0 at the
-        end. M2.1 phase 2 confirmed smaller batches don't help on CPU,
-        so finer-grained progress isn't possible without fake ticks.
+        The progress_callback ramps from 0 to 0.5 across the first-pass
+        Qwen chunks, hits 0.9 after the optional retry/fallback, and 1.0
+        at the end. Input larger than the model's context window is split
+        across multiple Qwen calls (see ``_qwen_translate_chunked``).
         """
         effective_source = source_lang or "en"
         self._failures_last_call = []
@@ -277,13 +376,15 @@ class Qwen3Translator:
         translatable_indices = [i for i, seg in enumerate(segments) if _is_translatable_text(seg.text)]
         translatable_segments = [segments[i] for i in translatable_indices]
 
-        # First attempt.
-        if translatable_segments:
-            qwen_results = self._qwen_translate(translatable_segments, target_lang, effective_source)
-        else:
-            qwen_results = {}
-        if progress_callback is not None:
-            progress_callback(0.5)
+        # First attempt — chunked to fit n_ctx.
+        qwen_results = self._qwen_translate_chunked(
+            translatable_segments,
+            target_lang,
+            effective_source,
+            progress_callback=progress_callback,
+            progress_start=0.0,
+            progress_end=0.5,
+        )
 
         # Identify segments Qwen failed (unparseable or missing index).
         # Indices in qwen_results / translatable_segments are 0-based positions
@@ -299,11 +400,15 @@ class Qwen3Translator:
                 len(retry_segments),
                 len(translatable_segments),
             )
-            retry_results = self._qwen_translate(retry_segments, target_lang, effective_source)
-            # retry_results uses 0..len(retry_segments)-1 as keys; map back.
-            for retry_local, original_local in enumerate(missing_local_indices):
-                if retry_local in retry_results:
-                    qwen_results[original_local] = retry_results[retry_local]
+            retry_results = self._qwen_translate_chunked(
+                retry_segments,
+                target_lang,
+                effective_source,
+            )
+            # retry_results keys are positions in retry_segments; map back to
+            # translatable_segments.
+            for retry_local, translation in retry_results.items():
+                qwen_results[missing_local_indices[retry_local]] = translation
         if progress_callback is not None:
             progress_callback(0.9)
 

{videopython-0.34.1 → videopython-0.35.1}/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.1}/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.1}/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: