videopython 0.43.1__tar.gz → 0.44.0__tar.gz

{videopython-0.43.1 → videopython-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.43.1
+Version: 0.44.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -133,7 +133,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. Use `edit.run()` to get a `Video` back in memory instead.
+`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
 
 ### AI generation
 

{videopython-0.43.1 → videopython-0.44.0}/README.md

@@ -47,7 +47,7 @@ edit.validate()                  # dry-run via metadata, no frames loaded
 edit.run_to_file("output.mp4")   # streams ffmpeg decode → effects → encode
 ```
 
-`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. Use `edit.run()` to get a `Video` back in memory instead.
+`run_to_file()` streams ffmpeg decode → per-frame effects → encode, so memory stays bounded even for hour-long sources. If you need the frames back in memory, load the rendered file: `Video.from_path(str(edit.run_to_file("output.mp4")))`.
 
 ### AI generation
 

{videopython-0.43.1 → videopython-0.44.0}/pyproject.toml

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

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/ai/dubbing/dubber.py

@@ -239,9 +239,7 @@ class VideoDubber:
         video_duration = video.total_seconds
 
         if video_duration > speech_duration:
-            from videopython.editing.transforms import CutSeconds
-
-            output_video = CutSeconds(start=0, end=speech_duration).apply(video)
+            output_video = video[: round(speech_duration * video.fps)]
         else:
             output_video = video
 

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/ai/effects.py

@@ -33,9 +33,9 @@ class ObjectDetectionOverlay(Effect):
     *memory*-bound: ``"streamable"`` here means bounded memory, not bounded
     compute. On long clips, cap cost with ``window`` (limit the time range),
     a larger ``detection_interval``, a ``class_filter``, and/or the smaller
-    ``model_size``. Because only ``streaming_init`` and ``process_frame`` are
-    overridden, the base ``Effect._apply`` replays the identical contract for
-    in-memory execution, so eager and streaming results cannot drift.
+    ``model_size``. Only ``streaming_init`` and ``process_frame`` are
+    overridden; the streaming engine drives that contract for bounded-memory
+    execution.
     """
 
     op: Literal["object_detection_overlay"] = "object_detection_overlay"

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/ai/transforms.py

@@ -15,7 +15,7 @@ from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
-from videopython.base.video import FrameIterator, Video, VideoMetadata
+from videopython.base.video import FrameIterator, VideoMetadata
 from videopython.editing._ass import escape_filter_value
 from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
@@ -94,8 +94,8 @@ class FaceTrackingCrop(Operation):
         """Output ``(width, height)`` -- the fixed crop-window size.
 
         The largest ``target_aspect`` box that fits the frame, even-floored.
-        A pure function of the input dimensions, shared by :meth:`apply`,
-        :meth:`predict_metadata`, and :meth:`to_ffmpeg_filter`, so the
+        A pure function of the input dimensions, shared by
+        :meth:`predict_metadata` and :meth:`to_ffmpeg_filter`, so the
         dry-run cannot disagree with the render.
         """
         target_ratio = self.target_aspect[0] / self.target_aspect[1]
@@ -131,9 +131,8 @@ class FaceTrackingCrop(Operation):
         """Per-frame crop top-left positions for a fixed-size crop window.
 
         The single source of the tracking math (detection cadence, EMA
-        smoothing, framing offset, speed clamp, frame clamping), shared by
-        the eager :meth:`apply` and the compile-time detection pass so the
-        two paths cannot drift.
+        smoothing, framing offset, speed clamp, frame clamping), run by the
+        compile-time detection pass to build the per-frame crop command file.
         """
         out_w, out_h = self._resolved_output_dims(frame_w, frame_h)
         tracker = FaceTracker(
@@ -166,23 +165,6 @@ class FaceTrackingCrop(Operation):
                 positions.append(default)
         return positions
 
-    def apply(self, video: Video) -> Video:
-        h, w = video.frame_shape[:2]
-        out_w, out_h = self._resolved_output_dims(w, h)
-        logger.info(
-            "Face tracking crop: %dx%d -> %dx%d (%d:%d, framing=%s)",
-            w,
-            h,
-            out_w,
-            out_h,
-            self.target_aspect[0],
-            self.target_aspect[1],
-            self.framing_rule,
-        )
-        positions = self._track_crop_positions(tqdm(video.frames, desc="Face tracking crop"), w, h)
-        video.frames = np.stack([video.frames[i][y : y + out_h, x : x + out_w] for i, (x, y) in enumerate(positions)])
-        return video
-
     def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
         """Compile the face track to a per-frame ``crop`` position command file.
 

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/ai/video_analysis/analyzer.py

@@ -331,9 +331,8 @@ class VideoAnalyzer:
             return None
         if source_path is not None:
             return Video.from_path(str(source_path), start_second=start_second, end_second=end_second)
-        from videopython.editing.transforms import CutSeconds
-
-        return CutSeconds(start=start_second, end=end_second).apply(stages.require_video(video))
+        v = stages.require_video(video)
+        return v[round(start_second * v.fps) : round(end_second * v.fps)]
 
     def _default_scene_boundaries(self, metadata: VideoMetadata) -> list[SceneBoundary]:
         if metadata.total_seconds <= 0 or metadata.frame_count <= 0:

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/audio/audio.py

@@ -23,8 +23,8 @@ def atempo_chain(speed: float) -> list[str]:
     factor outside that range is decomposed into a chain of capped stages
     (``atempo=2.0`` repeated for speedups, ``atempo=0.5`` for slowdowns) times
     a final remainder stage. The single source of truth shared by
-    :meth:`Audio.time_stretch` (the in-memory WAV round-trip used by the eager
-    ``apply`` path) and ``SpeedChange.to_ffmpeg_audio_filter`` (the streaming
+    :meth:`Audio.time_stretch` (the in-memory WAV round-trip used by dubbing's
+    timing alignment) and ``SpeedChange.to_ffmpeg_audio_filter`` (the streaming
     filter graph), so both stretch by exactly the same chain. Returns an empty
     list for ``speed == 1`` (a no-op the caller maps to ``anull``).
     """

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/editing/audio_ops.py

@@ -7,9 +7,8 @@ assembled timeline, not of any one segment. It is mixed in a FINAL ffmpeg pass
 assembled program audio plus the bed input.
 
 :class:`MusicBed` is a frozen, closed pydantic model carried on
-:attr:`VideoEdit.music_bed`. Both ``run`` and ``run_to_file`` route through the
-single :func:`build_music_bed_filter_complex` builder so the in-memory and
-file paths cannot diverge on the mix.
+:attr:`VideoEdit.music_bed`. ``run_to_file`` routes through the
+single :func:`build_music_bed_filter_complex` builder for the mix.
 
 Ducking is *transcription-derived* and deterministic: when ``duck`` is set the
 bed is lowered under the speech windows derived from the context transcription
@@ -122,7 +121,7 @@ class MusicBed(BaseModel):
 
         Mirrors :meth:`ImageOverlay.predict_metadata`: a cheap ffprobe header
         probe (no decode) catches a missing / non-audio file at validate time,
-        before ``run()`` would crash mid-stream after assembling the program.
+        before ``run_to_file()`` would crash mid-stream after assembling the program.
         """
         try:
             info = _ffmpeg.probe(self.source)
@@ -147,8 +146,8 @@ class MusicBed(BaseModel):
         bed is scaled to ``gain``, faded, ducked under ``speech`` (when given and
         ``duck`` is set), then pinned to exactly ``program_seconds`` (``atrim``
         end + ``apad`` whole_dur) so a looped bed neither truncates early nor
-        extends the output past the program. Shared by the in-memory and file
-        mix paths via :func:`build_music_bed_filter_complex`.
+        extends the output past the program. Used by the file
+        mix path via :func:`build_music_bed_filter_complex`.
         """
         stages: list[str] = [f"volume={self.gain:.6f}"]
         if self.fade_in > 0:
@@ -178,8 +177,7 @@ def build_music_bed_filter_complex(
 ) -> tuple[list[str], list[str], str]:
     """Compile the music-bed input args + ``filter_complex`` mix graph.
 
-    The single source of the bed mix, shared by ``run`` (in-memory PCM pass) and
-    ``run_to_file`` (file pass) so the two cannot diverge. Returns
+    The single source of the bed mix, used by ``run_to_file`` (file pass). Returns
     ``(input_args, graph_statements, out_label)``:
 
     - ``input_args`` are the ffmpeg ``-i`` argv for the bed: ``-stream_loop -1``

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/editing/effects.py

@@ -3,16 +3,13 @@
 An ``Effect`` is an ``Operation`` that preserves video shape and frame count.
 Subclasses implement the streaming contract -- :meth:`Effect.process_frame`
 (plus :meth:`Effect.streaming_init` for any precomputed state) -- which is the
-single source of truth for the effect's pixel logic. The base
-:meth:`Effect._apply` replays that contract over the in-memory frames, so
-in-memory execution comes for free and cannot drift from streaming.
-
-A few effects override the eager path deliberately: ``FullImageOverlay`` and
-``Vignette`` keep a hand-written :meth:`Effect._apply` (extra validation /
-batched vectorisation), and the audio effects (``Fade``, ``VolumeAdjust``)
-override :meth:`Effect.apply` directly so the audio splice stays coherent with
-the window. Anchored RGBA overlays (``TextOverlay``, ``ImageOverlay``) share
-their placement and blend via :class:`_AnchoredOverlay`.
+single source of truth for the effect's pixel logic and the only execution
+path. Audio effects (``Fade``, ``VolumeAdjust``) instead express their gain
+envelope via :meth:`Effect.to_ffmpeg_audio_filter`. Effects that need
+run-time validation beyond the field constraints (``FullImageOverlay``)
+override :meth:`Effect.predict_metadata`. Anchored RGBA overlays
+(``TextOverlay``, ``ImageOverlay``) share their placement and blend via
+:class:`_AnchoredOverlay`.
 """
 
 from __future__ import annotations
@@ -26,7 +23,6 @@ import cv2
 import numpy as np
 from PIL import Image, ImageDraw, ImageFont
 from pydantic import Field, PrivateAttr, model_validator
-from tqdm import tqdm
 
 from videopython.base.description import BoundingBox
 from videopython.base.exceptions import PlanError, PlanErrorCode, PlanValidationError
@@ -35,8 +31,7 @@ from videopython.editing._easing import ease, ease_out
 from videopython.editing.operation import Effect, FilterCtx
 
 if TYPE_CHECKING:
-    from videopython.audio import Audio
-    from videopython.base.video import Video, VideoMetadata
+    from videopython.base.video import VideoMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -121,24 +116,23 @@ class FullImageOverlay(Effect):
         fade_alpha = 1.0 if dist_from_end >= self._stream_fade_frames else dist_from_end / self._stream_fade_frames
         return self._overlay_frame(frame, fade_alpha)
 
-    def _apply(self, video: Video, **_context: Any) -> Video:
+    def predict_metadata(self, meta: VideoMetadata, **_context: Any) -> VideoMetadata:
+        """Reject an overlay that cannot composite onto this video at run time.
+
+        Two failures ``run_to_file()`` cannot survive are caught at ``validate()``
+        time instead of mid-stream: (a) the overlay's pixel dimensions must match
+        the video frame exactly (this op is full-frame, unlike
+        :class:`ImageOverlay`), and (b) the combined fade-in + fade-out cannot
+        exceed the clip length. Both checks come from the deleted eager path; the
+        overlay header is read once here (no per-frame work).
+        """
         overlay = self._load_overlay()
-        if video.frame_shape != overlay[:, :, :3].shape:
-            raise ValueError(f"Mismatch of overlay shape `{overlay.shape}` with video shape: `{video.frame_shape}`!")
-        if not (0 <= 2 * self.fade_time <= video.total_seconds):
-            raise ValueError(f"Video is only {video.total_seconds}s long, but fade time is {self.fade_time}s!")
-
-        logger.info("Overlaying video...")
-        n = len(video.frames)
-        num_fade_frames = round(self.fade_time * video.fps) if self.fade_time > 0 else 0
-        for i in tqdm(range(n), desc="Overlaying frames"):
-            if num_fade_frames == 0:
-                video.frames[i] = self._overlay_frame(video.frames[i])
-            else:
-                dist_from_end = min(i, n - i)
-                fade_alpha = 1.0 if dist_from_end >= num_fade_frames else dist_from_end / num_fade_frames
-                video.frames[i] = self._overlay_frame(video.frames[i], fade_alpha)
-        return video
+        frame_shape = (meta.height, meta.width, 3)
+        if frame_shape != overlay[:, :, :3].shape:
+            raise ValueError(f"Mismatch of overlay shape `{overlay.shape}` with video shape: `{frame_shape}`!")
+        if not (0 <= 2 * self.fade_time <= meta.total_seconds):
+            raise ValueError(f"Video is only {meta.total_seconds}s long, but fade time is {self.fade_time}s!")
+        return meta
 
 
 class Blur(Effect):
@@ -326,18 +320,6 @@ class Vignette(Effect):
         assert self._stream_mask_3d is not None
         return (frame.astype(np.float32) * self._stream_mask_3d).astype(np.uint8)
 
-    def _apply(self, video: Video, **_context: Any) -> Video:
-        logger.info("Applying vignette effect...")
-        height, width = video.frame_shape[:2]
-        if self._mask is None or self._mask.shape != (height, width):
-            self._mask = self._create_mask(height, width)
-        mask_3d = self._mask[:, :, np.newaxis]
-        batch_size = 64
-        for start in range(0, len(video.frames), batch_size):
-            end = min(start + batch_size, len(video.frames))
-            video.frames[start:end] = (video.frames[start:end].astype(np.float32) * mask_3d).astype(np.uint8)
-        return video
-
 
 class KenBurns(Effect):
     """Cinematic pan-and-zoom that smoothly animates between two crop regions.
@@ -473,29 +455,6 @@ class Fade(Effect):
             return frame
         return (frame.astype(np.float32) * a).astype(np.uint8)
 
-    def apply(self, video: Video, **context: Any) -> Video:
-        start_s, stop_s = self._resolved_window(video.total_seconds)
-        start_f = round(start_s * video.fps)
-        end_f = round(stop_s * video.fps)
-        n_effect = end_f - start_f
-        alpha = self._fade_envelope(n_effect, video.fps)
-
-        batch_size = 64
-        for batch_start in range(0, n_effect, batch_size):
-            batch_end = min(batch_start + batch_size, n_effect)
-            batch_alpha = alpha[batch_start:batch_end, np.newaxis, np.newaxis, np.newaxis]
-            if np.all(batch_alpha == 1.0):
-                continue
-            abs_start = start_f + batch_start
-            abs_end = start_f + batch_end
-            video.frames[abs_start:abs_end] = (video.frames[abs_start:abs_end].astype(np.float32) * batch_alpha).astype(
-                np.uint8
-            )
-
-        if video.audio is not None and not video.audio.is_silent:
-            self._audio_apply(video.audio, start_s, stop_s)
-        return video
-
     def _curve_expr(self, progress: str) -> str:
         """ffmpeg gain sub-expression for a 0->1 ramp ``progress``, per ``self.curve``.
 
@@ -513,8 +472,9 @@ class Fade(Effect):
         """Express the fade's gain envelope as a windowed ``volume`` expression.
 
         The audio twin of the video fade (which scales pixels by the same alpha
-        envelope). It must mirror :func:`_fade_envelope` / :meth:`_audio_apply`:
-        the ramp applies only WITHIN ``[start, stop]`` and the gain is 1.0
+        envelope in :meth:`process_frame`). It must mirror
+        :func:`_fade_envelope`: the ramp applies only WITHIN ``[start, stop]``
+        and the gain is 1.0
         everywhere else -- so a *windowed* fade-out returns to full volume after
         the window (matching the video, which resumes full brightness), instead
         of staying muted. Native ``afade`` cannot express this (it holds 0
@@ -531,8 +491,8 @@ class Fade(Effect):
         if stop_s <= start_s:
             return None
         window_len = stop_s - start_s
-        # Halve the ramp for in_out so the lead and trailing ramps cannot overlap
-        # (the eager path takes their min; a clamped half-window avoids it).
+        # Halve the ramp for in_out so the lead and trailing ramps cannot
+        # overlap; a clamped half-window keeps them disjoint.
         both = self.mode == "in_out"
         ramp = min(self.duration, window_len / 2 if both else window_len)
         if ramp <= 0:
@@ -550,19 +510,6 @@ class Fade(Effect):
             expr = f"if({cond},{gain},{expr})"
         return f"volume=volume='{expr}':eval=frame"
 
-    def _audio_apply(self, audio: Audio, start_s: float, stop_s: float) -> None:
-        """Eager (in-memory) fade for ``Video.apply``; streaming uses ``afade``."""
-        sample_rate = audio.metadata.sample_rate
-        audio_start = round(start_s * sample_rate)
-        audio_end = min(round(stop_s * sample_rate), len(audio.data))
-        alpha = self._fade_envelope(audio_end - audio_start, sample_rate)
-
-        if audio.data.ndim == 1:
-            audio.data[audio_start:audio_end] *= alpha
-        else:
-            audio.data[audio_start:audio_end] *= alpha[:, np.newaxis]
-        np.clip(audio.data, -1.0, 1.0, out=audio.data)
-
 
 class VolumeAdjust(Effect):
     """Changes audio volume within a time range without affecting video frames."""
@@ -585,12 +532,6 @@ class VolumeAdjust(Effect):
     def process_frame(self, frame: np.ndarray, frame_index: int) -> np.ndarray:
         return frame
 
-    def apply(self, video: Video, **context: Any) -> Video:
-        start_s, stop_s = self._resolved_window(video.total_seconds)
-        if video.audio is not None and not video.audio.is_silent:
-            self._audio_apply(video.audio, start_s, stop_s)
-        return video
-
     def to_ffmpeg_audio_filter(self, ctx: FilterCtx) -> str | None:
         """Apply the volume change over the window via the ``volume`` filter.
 
@@ -598,8 +539,8 @@ class VolumeAdjust(Effect):
         multiplier compiles to ``volume=<v>:enable='between(t,start,stop)'``.
         When ``ramp_duration>0`` the gain is a time-piecewise expression
         (``volume=eval=frame``) that ramps ``1 -> volume`` over the first
-        ``ramp_duration`` of the window and back over the last, mirroring the
-        eager ``1 + (volume-1)*sqrt(t)`` edge ramps. The window resolves
+        ``ramp_duration`` of the window and back over the last, following the
+        ``1 + (volume-1)*sqrt(t)`` edge-ramp shape. The window resolves
         against the segment duration (``ctx.frame_count / ctx.fps``); ``None``
         for a degenerate window or a no-op (``volume == 1`` with no ramp).
         """
@@ -632,35 +573,13 @@ class VolumeAdjust(Effect):
         )
         return f"volume=volume='{expr}':eval=frame"
 
-    def _audio_apply(self, audio: Audio, start_s: float, stop_s: float) -> None:
-        """Eager (in-memory) volume change for ``Video.apply``; streaming uses ``volume``."""
-        sample_rate = audio.metadata.sample_rate
-        start_sample = round(start_s * sample_rate)
-        end_sample = min(round(stop_s * sample_rate), len(audio.data))
-        n_samples = end_sample - start_sample
-        envelope = np.full(n_samples, self.volume, dtype=np.float32)
-
-        if self.ramp_duration > 0:
-            ramp_samples = min(round(self.ramp_duration * sample_rate), n_samples // 2)
-            if ramp_samples > 0:
-                t = np.linspace(0, 1, ramp_samples, dtype=np.float32)
-                envelope[:ramp_samples] = 1.0 + (self.volume - 1.0) * np.sqrt(t)
-                t = np.linspace(1, 0, ramp_samples, dtype=np.float32)
-                envelope[-ramp_samples:] = 1.0 + (self.volume - 1.0) * np.sqrt(t)
-
-        if audio.data.ndim == 1:
-            audio.data[start_sample:end_sample] *= envelope
-        else:
-            audio.data[start_sample:end_sample] *= envelope[:, np.newaxis]
-        np.clip(audio.data, -1.0, 1.0, out=audio.data)
-
 
 class _AnchoredOverlay(Effect):
     """Shared base for anchored RGBA overlays (:class:`TextOverlay`, :class:`ImageOverlay`).
 
-    Owns anchored placement, off-frame clipping, and alpha blending, so the
-    eager and streaming paths share one ``_blend_params`` source of truth (the
-    parity-hole class of bug fixed in 0.34.1). Subclasses declare their own
+    Owns anchored placement, off-frame clipping, and alpha blending in one
+    ``_blend_params`` source of truth (consolidated when the eager/streaming
+    parity-hole class of bug was fixed in 0.34.1). Subclasses declare their own
     ``position``/``anchor`` field defaults and implement
     :meth:`_overlay_for_frame` to produce the RGBA bitmap; everything
     downstream is shared. It declares no ``op`` ``Literal``, so it is an
@@ -723,11 +642,11 @@ class _AnchoredOverlay(Effect):
     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.
+        """Placement + blend inputs for the streaming path.
 
-        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).
+        Single source of truth for placement and blending (consolidated when the
+        eager/stream parity-hole class of bug was fixed in 0.34.1). Returns
+        ``None`` when the overlay lands fully off-frame (the effect is a no-op).
         """
         overlay = self._overlay_for_frame(frame_w, frame_h)
         oh, ow = overlay.shape[:2]
@@ -942,7 +861,7 @@ class ImageOverlay(_AnchoredOverlay):
     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
+        An unreadable source is the one failure ``run_to_file()`` 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

{videopython-0.43.1 → videopython-0.44.0}/src/videopython/editing/operation.py

@@ -2,9 +2,9 @@
 
 Every editing primitive is an ``Operation`` subclass -- a Pydantic model whose
 fields ARE the JSON wire format. Validation, schema, and serialisation come for
-free; subclasses just declare fields and implement ``apply``. Auto-registration
-via ``__pydantic_init_subclass__`` builds the ``op_id -> class`` registry as
-modules are imported.
+free; subclasses just declare fields and implement the streaming contract.
+Auto-registration via ``__pydantic_init_subclass__`` builds the
+``op_id -> class`` registry as modules are imported.
 
 Subclass contract::
 
@@ -23,7 +23,6 @@ Subclass contract::
         width: int | None = Field(None, gt=0)
         height: int | None = Field(None, gt=0)
 
-        def apply(self, video: Video) -> Video: ...
         def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata: ...
         def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None: ...
 """
@@ -38,10 +37,9 @@ from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, NamedTuple,
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Discriminator, Field, TypeAdapter
-from tqdm import tqdm
 
 if TYPE_CHECKING:
-    from videopython.base.video import Video, VideoMetadata
+    from videopython.base.video import VideoMetadata
 
 __all__ = [
     "OpCategory",
@@ -72,8 +70,9 @@ class TimeRange(BaseModel):
     *shape*; the numeric bounds (``>= 0``, ``stop >= start``, in-duration) are
     owned by :meth:`VideoEdit.validate` / :meth:`VideoEdit.check`, which report
     them as structured, collectable, repairable :class:`PlanError`s instead of
-    aborting at ``from_dict``. :meth:`Effect._resolved_window` still clamps at
-    run time, so a plan run without validation degrades rather than crashes.
+    aborting at ``from_dict``. The window is still clamped to
+    ``min(stop, total_seconds)`` at run time, so a plan run without validation
+    degrades rather than crashes.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
@@ -238,8 +237,8 @@ class Operation(BaseModel):
     wire and the registry key. Subclasses may override the ``category``,
     ``streamable``, and ``requires`` ClassVars.
 
-    The default ``apply`` raises ``NotImplementedError``; ``predict_metadata``
-    defaults to identity; ``to_ffmpeg_filter`` defaults to ``None`` (no filter compilation).
+    ``predict_metadata`` defaults to identity; ``to_ffmpeg_filter`` defaults to
+    ``None`` (no filter compilation).
     """
 
     model_config = ConfigDict(extra="forbid", validate_assignment=True)
@@ -380,24 +379,14 @@ class Operation(BaseModel):
         """
         return _strip_llm_hidden(cls.model_json_schema())
 
-    def apply(self, video: Video) -> Video:
-        """Run this operation on ``video``.
-
-        The runner passes pipeline-context values listed in ``cls.requires``
-        as keyword arguments (e.g. ``transcription=...``). Subclasses that
-        declare ``requires`` widen the signature accordingly -- e.g.
-        ``def apply(self, video, transcription=None) -> Video``.
-        """
-        raise NotImplementedError(f"{type(self).__name__}.apply not implemented")
-
     def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
         """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.
+        or do unrecoverable / expensive work in** ``run_to_file()``;
+        anything ``run_to_file()`` 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
@@ -450,18 +439,16 @@ class Effect(Operation):
 
     Subclasses implement the streaming contract -- :meth:`process_frame` (and
     :meth:`streaming_init` for any precomputed per-stream state) -- which is the
-    single source of truth for the effect's pixel logic. The base
-    :meth:`_apply` runs that same contract over the in-memory frames, so
-    in-memory execution comes for free; the same code path feeds
-    ``editing/streaming.py`` for bounded-memory streaming. The base
-    :meth:`apply` resolves :attr:`window`, slices the video, runs ``_apply`` on
-    the slice, splices the result back, and asserts the shape-preserving
-    invariant.
-
-    Override :meth:`_apply` only when eager execution must genuinely differ from
-    a frame-by-frame replay -- e.g. extra validation, a batched vectorisation,
-    or audio handling (``Fade``/``VolumeAdjust`` override :meth:`apply` outright
-    so the audio splice stays coherent with the window).
+    single source of truth for the effect's pixel logic. The streaming engine
+    in ``editing/streaming.py`` drives that contract for bounded-memory
+    execution, resolving :attr:`window` against the segment timeline so frames
+    outside the window pass through untouched.
+
+    Effects that compile to a native ffmpeg filter instead set
+    :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.
     """
 
     category: ClassVar[OpCategory] = OpCategory.EFFECT
@@ -493,67 +480,15 @@ class Effect(Operation):
         """
         return False
 
-    def apply(self, video: Video, **context: Any) -> Video:
-        from videopython.base.video import Video as _Video
-
-        original_shape = video.video_shape
-
-        if self.window is None or (self.window.start is None and self.window.stop is None):
-            result = self._apply(video, **context)
-        else:
-            start_s, stop_s = self._resolved_window(video.total_seconds)
-            start_f = round(start_s * video.fps)
-            end_f = round(stop_s * video.fps)
-            inner = self._apply(video[start_f:end_f], **context)
-            old_audio = video.audio
-            result = _Video.from_frames(
-                np.r_["0,2", video.frames[:start_f], inner.frames, video.frames[end_f:]],
-                fps=video.fps,
-            )
-            result.audio = old_audio
-
-        if result.video_shape != original_shape:
-            raise RuntimeError(
-                f"{type(self).__name__} changed video shape from {original_shape} "
-                f"to {result.video_shape}; effects must preserve shape and frame count."
-            )
-        return result
-
     def predict_metadata(self, meta: VideoMetadata, **_context: Any) -> VideoMetadata:
         """Effects preserve shape and frame count, so the prediction is identity.
 
         Accepts ``**_context`` so requires-aware effects (``TranscriptionOverlay``)
         validate without subclasses needing to override just to widen the
-        signature. Mirrors :meth:`Effect.apply`'s ``**context`` accept-all.
+        signature. Mirrors :meth:`Effect.streaming_init`'s ``**_context`` accept-all.
         """
         return meta
 
-    def _resolved_window(self, total_seconds: float) -> tuple[float, float]:
-        win = self.window or TimeRange()
-        start_s = 0.0 if win.start is None else float(win.start)
-        stop_s = total_seconds if win.stop is None else float(win.stop)
-        start_s = min(start_s, total_seconds)
-        stop_s = min(stop_s, total_seconds)
-        if stop_s < start_s:
-            raise ValueError(f"Effect stop ({stop_s}) must be >= start ({start_s})")
-        return start_s, stop_s
-
-    def _apply(self, video: Video, **context: Any) -> Video:
-        """Apply the effect to ``video`` in memory by replaying the streaming path.
-
-        Runs :meth:`streaming_init` once, then :meth:`process_frame` over every
-        frame in order -- the same logic streaming uses, so eager and streaming
-        cannot drift. ``context`` carries resolved ``requires`` values through
-        to :meth:`streaming_init`, mirroring the streaming scheduler.
-        Subclasses that need a genuinely different eager path (extra
-        validation, batched vectorisation) override this.
-        """
-        height, width = video.frame_shape[:2]
-        self.streaming_init(len(video.frames), video.fps, width, height, **context)
-        for i in tqdm(range(len(video.frames)), desc=type(self).__name__):
-            video.frames[i] = self.process_frame(video.frames[i], i)
-        return video
-
     def streaming_init(self, total_frames: int, fps: float, width: int, height: int, **_context: Any) -> None:
         """Hook for per-stream precomputation (per-frame alphas, sigma curves...).