videopython 0.54.0__tar.gz → 0.55.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.54.0
+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/
@@ -24,11 +24,11 @@ Requires-Dist: resvg-py>=0.3.2
 Requires-Dist: tqdm>=4.66.3
 Provides-Extra: ai
 Requires-Dist: accelerate>=0.29.2; extra == 'ai'
-Requires-Dist: chatterbox-tts>=0.1.7; extra == 'ai'
 Requires-Dist: demucs>=4.0.0; extra == 'ai'
 Requires-Dist: diffusers>=0.35.0; extra == 'ai'
 Requires-Dist: ftfy>=6.1; extra == 'ai'
 Requires-Dist: imagehash>=4.3; extra == 'ai'
+Requires-Dist: numba>=0.62; extra == 'ai'
 Requires-Dist: ollama>=0.5.0; extra == 'ai'
 Requires-Dist: openai-whisper>=20240930; extra == 'ai'
 Requires-Dist: pyannote-audio>=4.0.0; extra == 'ai'
@@ -36,9 +36,11 @@ Requires-Dist: pyloudnorm>=0.1.1; extra == 'ai'
 Requires-Dist: silero-vad>=5.1; extra == 'ai'
 Requires-Dist: torch>=2.8.0; extra == 'ai'
 Requires-Dist: torchaudio>=2.8.0; extra == 'ai'
-Requires-Dist: torchvision<0.24.0,>=0.23.0; extra == 'ai'
+Requires-Dist: torchcodec>=0.7.0; extra == 'ai'
+Requires-Dist: torchvision>=0.23.0; extra == 'ai'
 Requires-Dist: transformers>=5.2.0; extra == 'ai'
 Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'ai'
+Requires-Dist: videopython-chatterbox>=0.1.7.post1; extra == 'ai'
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
 Description-Content-Type: text/markdown

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

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.54.0"
+version = "0.55.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -66,6 +66,13 @@ ai = ["videopython[ai]"]
 ai = [
     # Speech recognition / diarization (understanding/audio.py)
     "openai-whisper>=20240930",
+    # whisper imports numba (timing.py), and numba is version-coupled to numpy:
+    # each release declares a `numpy<X` cap that moves forward (0.62 -> <2.4,
+    # 0.66 -> <2.5). Without a floor a resolver can satisfy a newer numpy by
+    # backtracking numba to an ancient release instead, which then fails at
+    # `import whisper`. Floor it so numba's own cap does the work; 0.62 is the
+    # oldest release covering our full Python range (3.11-3.13).
+    "numba>=0.62",
     "pyannote-audio>=4.0.0",
     "silero-vad>=5.1",
     # Visual understanding: detection (D-FINE/YuNet via transformers + opencv core
@@ -75,9 +82,14 @@ ai = [
     "imagehash>=4.3",
     # Audio source separation (understanding/separation.py)
     "demucs>=4.0.0",
-    # Voice cloning TTS (generation/audio.py — Chatterbox); its strict pins drive
-    # the [tool.uv].override-dependencies block below.
-    "chatterbox-tts>=0.1.7",
+    # Voice cloning TTS (generation/audio.py — Chatterbox). Upstream chatterbox-tts
+    # 0.1.7 pins diffusers==0.29.0 / torch==2.6.0 / transformers==5.2.0 with `==`,
+    # which is unsatisfiable against pyannote-audio (torch>=2.8) and our
+    # diffusers>=0.35 — it made `pip install "videopython[ai]"` impossible for
+    # consumers. videopython-chatterbox is upstream's source with corrected
+    # metadata (identical apart from its self-version lookup); the import name is
+    # still `chatterbox`. See https://github.com/BartWojtowicz/videopython-chatterbox
+    "videopython-chatterbox>=0.1.7.post1",
     # Local media generation: Qwen-Image/Wan2.2 + MusicGen (generation/*).
     # >=0.35 is the floor that ships QwenImagePipeline + Wan2.2 support (tested on 0.37.1).
     "diffusers>=0.35.0",
@@ -94,9 +106,17 @@ ai = [
     # processor used by the D-FINE object detector (understanding/objects.py).
     "torch>=2.8.0",
     "torchaudio>=2.8.0",
-    # Capped to the torch-2.8-compatible line; torchvision<->torch are ABI-coupled
-    # and uv does not know it (0.23.x pairs with torch 2.8.x).
-    "torchvision>=0.23.0,<0.24.0",
+    # No upper bound: each torchvision release declares an exact `torch==X.Y.Z`
+    # pin, so resolvers co-select a valid pair unaided. Capping torchvision alone
+    # is actively harmful — it transitively pinned torch to 2.8 (cu12) while
+    # torchaudio floated to 2.11 (cu13), resolving cleanly and then dying at
+    # import with `OSError: libcudart.so.13`. Cap every member or none.
+    "torchvision>=0.23.0",
+    # torchaudio 2.11 routes save()/load() through torchcodec, and torchcodec is a
+    # native extension linked against libtorch that declares no torch requirement
+    # of its own. It arrives transitively via pyannote-audio; declare it so it is
+    # visible rather than incidental.
+    "torchcodec>=0.7.0",
 ]
 # MCP server (videopython/mcp/). Pin <2 — v2 is pre-release/breaking.
 mcp = ["mcp>=1.27,<2"]
@@ -136,12 +156,22 @@ module = [
 ignore_missing_imports = true
 
 [tool.uv]
-# chatterbox-tts 0.1.7 (in [ai]) pins strict torch/torchaudio/numpy/diffusers
-# that conflict with pyannote-audio (torch>=2.8) and CogVideoX (diffusers>=0.30).
-# These overrides let the combined [ai] resolve pick compatible versions; the
-# floors in [ai] are aligned with them so pip and uv resolve similar versions.
+# NOTE: overrides are a uv workspace feature — they do NOT ship in the built
+# wheel. Anything reconciled only here is invisible to `pip install videopython`,
+# so [ai] must be resolvable without this block. Keep it minimal.
+#
+# The torch/torchaudio/torchvision/diffusers overrides that used to live here
+# existed solely to paper over chatterbox-tts's `==` pins. They masked the
+# breakage from CI while every downstream consumer hit it, and an override
+# replaces a requirement *everywhere* — including torchvision's own exact
+# `torch==2.8.0` pin, which would have produced an ABI-invalid pair on the next
+# `uv lock --upgrade`. [ai] now depends on videopython-chatterbox, whose metadata
+# is correct, so none of them are needed.
+# The numpy>=2.0.0 override is gone for the same reason: it existed to counter
+# chatterbox-tts's `numpy<2.0.0` pin, and it also replaced numba's `numpy<2.5`
+# cap, resolving numpy 2.5 into an environment where `import whisper` dies with
+# "Numba needs NumPy 2.4 or less". numba IS version-coupled to numpy.
 override-dependencies = [
-    "torch>=2.8.0", "torchaudio>=2.8.0", "torchvision>=0.23.0,<0.24.0", "numpy>=2.0.0", "diffusers>=0.35.0",
     # Some transitive deps pull opencv-python, which conflicts with our
     # opencv-python-headless (both provide cv2). Exclude opencv-python so
     # only the headless variant is installed.

{videopython-0.54.0 → 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.0 → videopython-0.55.0}/src/videopython/ai/understanding/faces.py

@@ -236,7 +236,7 @@ class FaceSmoothingTracker(_FaceTrackerBase):
             frame_center = (0.5, 0.5)
             _, bbox = min(
                 faces_with_box,
-                key=lambda fb: ((fb[1].center[0] - frame_center[0]) ** 2 + (fb[1].center[1] - frame_center[1]) ** 2),
+                key=lambda fb: (fb[1].center[0] - frame_center[0]) ** 2 + (fb[1].center[1] - frame_center[1]) ** 2,
             )
         elif self.selection_strategy == "index":
             idx = self.face_index if self.face_index < len(faces_with_box) else 0

{videopython-0.54.0 → videopython-0.55.0}/src/videopython/audio/audio.py

@@ -224,16 +224,12 @@ class Audio:
                     if dtype is None:
                         raise AudioLoadError(f"Unsupported sample width: {sample_width}")
 
-                    data = np.frombuffer(raw_data, dtype=dtype)
+                    # Explicitly annotated: numpy>=2.5 shape-types ndarray, so the
+                    # 1-D frombuffer result cannot be rebound to a 2-D view below.
+                    data: np.ndarray[Any, np.dtype[np.float32]]
+                    data = np.frombuffer(raw_data, dtype=dtype).astype(np.float32)
 
-                    # Reshape if stereo
-                    if channels == 2:
-                        data = data.reshape(-1, 2)
-
-                    # Convert to float32
-                    data = data.astype(np.float32)
-
-                    # Reshape before normalization if stereo
+                    # Reshape to (frames, channels) if stereo
                     if channels == 2:
                         data = data.reshape(-1, 2)
 

{videopython-0.54.0 → videopython-0.55.0}/src/videopython/base/video.py

@@ -427,8 +427,9 @@ def extract_frames_at_indices(
     # Truncate to complete frames only
     raw_data = raw_data[: actual_frames * frame_size]
 
-    frames = np.frombuffer(raw_data, dtype=np.uint8).copy()
-    frames = frames.reshape(-1, metadata.height, metadata.width, 3)
+    # Chained rather than reshaped in place: numpy>=2.5 shape-types ndarray, so
+    # rebinding a 1-D frombuffer result to a 4-D view is an assignment error.
+    frames = np.frombuffer(raw_data, dtype=np.uint8).copy().reshape(-1, metadata.height, metadata.width, 3)
 
     # Reorder to match original frame_indices order if needed
     if unique_sorted_indices != frame_indices:

{videopython-0.54.0 → 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.0 → 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.0 → 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.0 → 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