videopython 0.54.1__tar.gz → 0.55.0__tar.gz

{videopython-0.54.1 → videopython-0.55.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.54.1
+Version: 0.55.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/

{videopython-0.54.1 → videopython-0.55.0}/pyproject.toml

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

{videopython-0.54.1 → videopython-0.55.0}/src/videopython/ai/_ollama.py

@@ -23,6 +23,13 @@ class OllamaStructuredClient:
     must be served by a local Ollama daemon and support structured-output
     ``format`` (and vision, when images are passed); ``options`` are extra Ollama
     generation options merged over ``temperature=0``.
+
+    Reasoning models emit their chain-of-thought *before* the schema-constrained
+    answer, and that thinking counts against ``num_predict``. On a reasoning model
+    (the default ``qwen3.6:27b`` is one) a translation call spends its entire token
+    budget thinking, stops on ``length``, and returns empty content. None of these
+    callers want the chain-of-thought, so thinking is disabled on models that
+    support it.
     """
 
     def __init__(self, model: str, *, host: str | None = None, options: dict[str, Any] | None = None) -> None:
@@ -30,6 +37,7 @@ class OllamaStructuredClient:
         self.host = host
         self.options: dict[str, Any] = {"temperature": 0.0, **(options or {})}
         self._client: Any = None
+        self._thinking_capable: bool | None = None
 
     def _get_client(self) -> Any:
         if self._client is None:
@@ -37,6 +45,17 @@ class OllamaStructuredClient:
             self._client = ollama.Client(host=self.host)
         return self._client
 
+    def _supports_thinking(self) -> bool:
+        """Whether the model advertises Ollama's ``thinking`` capability (cached).
+
+        Passing ``think`` to a model that has no thinking capability is an error, so
+        this is checked rather than assumed.
+        """
+        if self._thinking_capable is None:
+            capabilities = self._get_client().show(self.model).capabilities or []
+            self._thinking_capable = "thinking" in capabilities
+        return self._thinking_capable
+
     def generate_json(
         self,
         *,
@@ -50,7 +69,12 @@ class OllamaStructuredClient:
         if 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)
+        kwargs: dict[str, Any] = {}
+        if self._supports_thinking():
+            kwargs["think"] = False
+        response = self._get_client().chat(
+            model=self.model, messages=messages, format=schema, options=self.options, **kwargs
+        )
         content = response.message.content
         try:
             data = json.loads(content)

{videopython-0.54.1 → videopython-0.55.0}/src/videopython/editing/effects.py

@@ -38,6 +38,15 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+GRAIN_POOL_PAD = 128
+"""Padding on each axis of :class:`FilmGrain`'s precomputed noise plane.
+
+Bounds both the per-frame offset range (``pad**2`` = 16384 distinct windows,
+far more than any realistic frame count reuses noticeably) and the pool's
+memory: ``(h + pad) * (w + pad) * 3 * 2`` bytes, ~15 MB at 1080p. Constant in
+clip duration, so the effect stays O(1)-memory.
+"""
+
 __all__ = [
     "Effect",
     "FullImageOverlay",
@@ -255,23 +264,66 @@ class ColorGrading(Effect):
         description="Shift color temperature. -1.0 = cool/blue tint, 0 = neutral, 1.0 = warm/orange tint.",
     )
 
-    def _grade_frame(self, frame: np.ndarray) -> np.ndarray:
-        img = frame.astype(np.float32) / 255.0
+    _lut_tone: np.ndarray | None = PrivateAttr(default=None)
+    _lut_temp: np.ndarray | None = PrivateAttr(default=None)
 
-        if self.brightness != 0:
-            img = img + self.brightness
+    @staticmethod
+    def _as_lut(channels: list[np.ndarray]) -> np.ndarray:
+        """Pack three 256-entry ramps into the ``(1, 256, 3)`` array cv2.LUT wants."""
+        return np.ascontiguousarray(np.stack(channels, axis=1).reshape(1, 256, 3).astype(np.uint8))
+
+    def _build_luts(self) -> None:
+        """Precompute the two point-operation lookup tables.
+
+        Brightness, contrast and temperature are all per-channel point
+        operations -- the output for an input byte depends on nothing else --
+        so they collapse into 256-entry tables built once instead of float
+        arithmetic over every pixel of every frame.
+
+        Two tables rather than one because saturation sits between them in the
+        documented order (brightness -> contrast -> saturation -> temperature)
+        and is *not* a point operation. Folding temperature into the first table
+        would silently reorder it ahead of saturation, and the two do not
+        commute.
+        """
+        x = np.arange(256, dtype=np.float32) / 255.0
+        tone = x + self.brightness if self.brightness != 0 else x
         if self.contrast != 1.0:
-            img = (img - 0.5) * self.contrast + 0.5
+            tone = (tone - 0.5) * self.contrast + 0.5
+        tone_u8 = np.clip(tone * 255.0, 0, 255)
+        self._lut_tone = self._as_lut([tone_u8, tone_u8, tone_u8])
+
+        shift = self.temperature * 0.1
+        self._lut_temp = self._as_lut(
+            [
+                np.clip((x + shift) * 255.0, 0, 255),
+                np.clip(x * 255.0, 0, 255),
+                np.clip((x - shift) * 255.0, 0, 255),
+            ]
+        )
+
+    def _grade_frame(self, frame: np.ndarray) -> np.ndarray:
+        if self._lut_tone is None or self._lut_temp is None:
+            self._build_luts()
+        assert self._lut_tone is not None and self._lut_temp is not None
+
+        out = frame
+        if self.brightness != 0 or self.contrast != 1.0:
+            out = cv2.LUT(out, self._lut_tone)
         if self.saturation != 1.0:
-            hsv = cv2.cvtColor(np.clip(img, 0, 1).astype(np.float32), cv2.COLOR_RGB2HSV)
-            hsv[:, :, 1] = np.clip(hsv[:, :, 1] * self.saturation, 0, 1)
-            img = cv2.cvtColor(hsv, cv2.COLOR_HSV2RGB).astype(np.float32)
+            # Saturation as a blend toward the luma-weighted greyscale of the
+            # frame. Replaces an RGB->HSV->RGB float32 round trip that cost more
+            # than every other stage of the grade combined (~42 of 56 ms/frame).
+            grey = cv2.cvtColor(out, cv2.COLOR_RGB2GRAY)
+            out = cv2.addWeighted(
+                out, self.saturation, cv2.cvtColor(grey, cv2.COLOR_GRAY2RGB), 1.0 - self.saturation, 0
+            )
         if self.temperature != 0:
-            temp_shift = self.temperature * 0.1
-            img[:, :, 0] = img[:, :, 0] + temp_shift
-            img[:, :, 2] = img[:, :, 2] - temp_shift
+            out = cv2.LUT(out, self._lut_temp)
+        return out if out is not frame else frame.copy()
 
-        return np.clip(img * 255, 0, 255).astype(np.uint8)
+    def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
+        self._build_luts()
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
         return self._grade_frame(frame)
@@ -299,7 +351,7 @@ class Vignette(Effect):
     )
 
     _mask: np.ndarray | None = PrivateAttr(default=None)
-    _stream_mask_3d: np.ndarray | None = PrivateAttr(default=None)
+    _stream_mask_u8: np.ndarray | None = PrivateAttr(default=None)
 
     def _create_mask(self, height: int, width: int) -> np.ndarray:
         y = np.linspace(-1, 1, height)
@@ -310,13 +362,28 @@ class Vignette(Effect):
         return mask.astype(np.float32)
 
     def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
+        """Bake the gain mask into a 3-channel uint8 lookup, once per stream.
+
+        The mask is static, so the only per-frame work should be one multiply.
+        Storing it as uint8 replicated across channels lets ``cv2.multiply`` run
+        the whole frame in a single SIMD pass with no float conversion --
+        ~10x faster than promoting every frame to float32, and the mask itself
+        is *smaller* than the float32 original (6.2 MB vs 8.3 MB at 1080p).
+
+        The clip to [0, 1] also fixes a real defect: ``_create_mask`` goes
+        NEGATIVE once ``strength`` is high enough (down to -1.0 at
+        ``strength=1.0``), and ``(frame * -1.0).astype(np.uint8)`` wraps around,
+        so the darkest corners rendered as mid-grey (200 -> 56) and the vignette
+        got *brighter* past the zero crossing instead of saturating to black.
+        """
         if self._mask is None or self._mask.shape != (height, width):
             self._mask = self._create_mask(height, width)
-        self._stream_mask_3d = self._mask[:, :, np.newaxis]
+        scaled = (np.clip(self._mask, 0.0, 1.0) * 255.0).astype(np.uint8)
+        self._stream_mask_u8 = np.ascontiguousarray(np.repeat(scaled[:, :, np.newaxis], 3, axis=2))
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
-        assert self._stream_mask_3d is not None
-        return (frame.astype(np.float32) * self._stream_mask_3d).astype(np.uint8)
+        assert self._stream_mask_u8 is not None
+        return cv2.multiply(frame, self._stream_mask_u8, scale=1.0 / 255.0, dtype=cv2.CV_8U)
 
 
 class KenBurns(Effect):
@@ -407,7 +474,6 @@ class Fade(Effect):
     """Fades video and audio to or from black."""
 
     op: Literal["fade"] = "fade"
-    audio_coupled: ClassVar[bool] = True
 
     mode: Literal["in", "out", "in_out"] = Field(
         description=('"in" fades from black at the start, "out" fades to black at the end, "in_out" does both.'),
@@ -505,10 +571,18 @@ class Fade(Effect):
 
 
 class VolumeAdjust(Effect):
-    """Changes audio volume within a time range without affecting video frames."""
+    """Changes audio volume within a time range without affecting video frames.
+
+    Pixel-passthrough by construction: the effect exists entirely on the audio
+    graph (:meth:`to_ffmpeg_audio_filter` -> ``volume``). It declares
+    :attr:`video_passthrough` so the plan builder places that audio filter and
+    leaves the video chain alone -- without it, the op would schedule per-frame
+    Python and drag the whole segment through a rawvideo decode/encode
+    round-trip to run an identity function over every pixel.
+    """
 
     op: Literal["volume_adjust"] = "volume_adjust"
-    audio_coupled: ClassVar[bool] = True
+    video_passthrough: ClassVar[bool] = True
 
     volume: float = Field(
         1.0,
@@ -521,8 +595,15 @@ class VolumeAdjust(Effect):
         description="Seconds to smoothly ramp volume at the start and end of the window, preventing audible clicks.",
     )
 
-    def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
-        return frame
+    @property
+    def compiles_to_filter(self) -> bool:
+        """Always filter-class: the whole effect is the audio twin.
+
+        Paired with :attr:`video_passthrough`, this routes the op down the
+        filter path, where :meth:`to_ffmpeg_filter` returning ``None`` is read
+        as "no video filter by design" rather than "failed to compile".
+        """
+        return True
 
     def to_ffmpeg_audio_filter(self, ctx: FilterCtx) -> str | None:
         """Apply the volume change over the window via the ``volume`` filter.
@@ -1343,21 +1424,41 @@ class FilmGrain(Effect):
     )
     seed: int = Field(0, description="Seed for the noise RNG. Same seed = same grain pattern.")
 
-    def _grain_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
-        rng = np.random.default_rng(self.seed + frame_index)
-        h, w = frame.shape[:2]
-        amp = self.intensity * 255.0
-        if self.monochrome:
-            noise = rng.standard_normal((h, w, 1), dtype=np.float32) * amp
-        else:
-            noise = rng.standard_normal((h, w, 3), dtype=np.float32) * amp
-        return np.clip(frame.astype(np.float32) + noise, 0, 255).astype(np.uint8)
+    _pool: np.ndarray | None = PrivateAttr(default=None)
+    _offsets: np.ndarray | None = PrivateAttr(default=None)
+    _geometry: tuple[int, int] = PrivateAttr(default=(0, 0))
 
     def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
-        return None
+        """Draw one oversized noise plane up front; each frame reads a random window of it.
+
+        Generating fresh Gaussian noise per frame meant ~2M ``standard_normal``
+        samples every frame, which dominated the effect (~31 ms/frame, more than
+        twice the encoder's whole per-frame budget). Sampling a
+        ``GRAIN_POOL_PAD``-padded plane once and taking a randomly offset window
+        per frame gives grain that still changes every frame -- offsets jump
+        rather than drift, so it scintillates like film rather than sliding --
+        for one saturating integer add.
+
+        Reproducibility is unchanged in contract (same ``seed`` -> same grain),
+        though the pattern itself differs from the per-frame-RNG version.
+        """
+        amp = self.intensity * 255.0
+        pad = GRAIN_POOL_PAD
+        shape: tuple[int, ...] = (height + pad, width + pad) if self.monochrome else (height + pad, width + pad, 3)
+        noise = (np.random.default_rng(self.seed).standard_normal(shape, dtype=np.float32) * amp).astype(np.int16)
+        if self.monochrome:
+            # Luma-only grain: the same sample in all three channels.
+            noise = np.repeat(noise[:, :, np.newaxis], 3, axis=2)
+        self._pool = np.ascontiguousarray(noise)
+        self._offsets = np.random.default_rng(self.seed + 1).integers(0, pad, size=(max(total_frames, 1), 2))
+        self._geometry = (height, width)
 
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
-        return self._grain_frame(frame, frame_index)
+        assert self._pool is not None and self._offsets is not None
+        height, width = self._geometry
+        oy, ox = self._offsets[frame_index % len(self._offsets)]
+        # cv2.add saturates at 0/255, so no separate clip and no float promotion.
+        return cv2.add(frame, self._pool[oy : oy + height, ox : ox + width], dtype=cv2.CV_8U)
 
 
 class Sharpen(Effect):

{videopython-0.54.1 → videopython-0.55.0}/src/videopython/editing/operation.py

@@ -474,12 +474,23 @@ class Effect(Operation):
     :attr:`compiles_to_filter` and implement :meth:`to_ffmpeg_filter` (and, for
     audio-coupled effects like ``Fade``/``VolumeAdjust``,
     :meth:`to_ffmpeg_audio_filter`) so the window stays coherent across the
-    decode/encode graph.
+    decode/encode graph. An effect may implement BOTH contracts: the filter is
+    the fast path and ``process_frame`` stays as the reference implementation,
+    with ``src/tests/editing/test_filter_parity.py`` pinning them together.
     """
 
     category: ClassVar[OpCategory] = OpCategory.EFFECT
-    audio_coupled: ClassVar[bool] = False
-    """Whether the effect mutates audio alongside pixels (``afade``/``volume``)."""
+    video_passthrough: ClassVar[bool] = False
+    """Whether a filter-class effect leaves pixels untouched (audio-only, e.g. ``volume_adjust``).
+
+    Only consulted when :attr:`compiles_to_filter` is True. It distinguishes the
+    two reasons :meth:`to_ffmpeg_filter` returns ``None``: "this op has no video
+    filter *by design*" (passthrough -- place the audio twin and move on) from
+    "this op failed to compile at this position" (fall through to the per-frame
+    path). Without it an audio-only effect is indistinguishable from a failed
+    compile and is forced onto the framewise pipeline, paying a full rawvideo
+    round-trip to run a no-op over every pixel.
+    """
 
     window: TimeRange | None = Field(
         None,

{videopython-0.54.1 → videopython-0.55.0}/src/videopython/editing/streaming.py

@@ -148,7 +148,11 @@ def _classify_op_list(ops: Sequence[Operation], location_prefix: str) -> list[Op
                 # order either way and does not block later transforms the way
                 # a scheduled frame effect does. The builder mirrors this.
                 entries.append(OpStreamability(location, op.op, StreamingClass.FILTER))
-                if seen_effect:
+                if seen_effect and not op.video_passthrough:
+                    # A video_passthrough effect (volume_adjust) places nothing
+                    # on the video chain, so it cannot open the encode stage --
+                    # a frame effect after it is still perfectly orderable.
+                    # The builder mirrors this by skipping post_vf_filters.
                     seen_encode_stage = True
                 continue
             if not op.streams():

{videopython-0.54.1 → videopython-0.55.0}/src/videopython/editing/video_edit.py

@@ -2078,13 +2078,14 @@ class VideoEdit(BaseModel):
                         abandon()
                         return None
                     if op.compiles_to_filter:
-                        # Filter-class effect (add_subtitles): consumes its
-                        # context at compile time and joins the filter chain at
-                        # this op's plan position -- the decode chain when no
-                        # frame effect precedes it, else the encode chain
-                        # (FrameEncoder -vf), which runs after every
-                        # process_frame. Either way plan order is preserved. A
-                        # None compile falls through to the frame-effect path.
+                        # Filter-class effect (add_subtitles, vignette, ...):
+                        # consumes its context at compile time and joins the
+                        # filter chain at this op's plan position -- the decode
+                        # chain when no frame effect precedes it, else the
+                        # encode chain (FrameEncoder -vf), which runs after
+                        # every process_frame. Either way plan order is
+                        # preserved. A None compile falls through to the
+                        # frame-effect path UNLESS the op is video_passthrough.
                         encode_stage_effect = bool(effect_schedule or post_vf_filters)
                         ctx = make_ctx(decode_filters=None if encode_stage_effect else tuple(vf_filters))
                         filter_expr = op.to_ffmpeg_filter(ctx)
@@ -2099,6 +2100,17 @@ class VideoEdit(BaseModel):
                             # none today; kept coupled for extensibility).
                             compile_audio_twin(op, ctx, encode_stage_effect)
                             continue
+                        if op.video_passthrough:
+                            # Audio-only filter effect (volume_adjust): there is
+                            # no video filter to place by design, but the audio
+                            # twin still lands -- at the stage a video filter
+                            # WOULD have landed, so audio/video stage placement
+                            # stays coupled. Deliberately does not touch
+                            # vf_filters/post_vf_filters/pipe_meta: the op is
+                            # invisible to the video chain, so it neither opens
+                            # the encode stage nor blocks a later frame effect.
+                            compile_audio_twin(op, ctx, encode_stage_effect)
+                            continue
                     if post_vf_filters:
                         # A frame effect after an encode-stage filter would run
                         # before it (process_frame precedes the encoder), so