videopython 0.41.0__tar.gz → 0.42.0__tar.gz

{videopython-0.41.0 → videopython-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.41.0
+Version: 0.42.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -117,9 +117,9 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 ## Features
 
-- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
-- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, reverse, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
+- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
 - **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
 

{videopython-0.41.0 → videopython-0.42.0}/README.md

@@ -68,9 +68,9 @@ See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/)
 
 ## Features
 
-- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `ImageText`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
+- **`videopython.base`** — `Video`, `VideoMetadata`, `FrameIterator`, `Transcription`, and shared result types (`BoundingBox`, `FaceTrack`, `SceneBoundary`, ...). No AI dependencies.
 - **`videopython.audio`** — `Audio` with overlay, concat, normalize, time-stretch, silence detection, segment classification.
-- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, reverse, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
+- **`videopython.editing`** — `Operation`/`Effect` foundation, `VideoEdit` plan runner with JSON Schema + streaming execution. Transforms (cut, resize, crop, fps, speed, freeze, silence removal) and effects (blur, zoom, color grading, vignette, Ken Burns, fade, overlays, animated subtitles).
 - **`videopython.ai`** *(install with `[ai]`)* — generation (`TextToVideo`, `ImageToVideo`, `TextToImage`, `TextToSpeech`, `TextToMusic`), understanding (`AudioToText`, `AudioClassifier`, `SceneVLM`, `FaceTracker`, `ObjectDetector`, `SemanticSceneDetector`), the `FaceTrackingCrop` transform, the `ObjectDetectionOverlay` effect (per-frame bounding boxes + labels), and the full-pipeline `VideoAnalyzer`.
 - **`videopython.ai.dubbing`** — `VideoDubber` for voice-cloned revoicing with timing sync.
 

{videopython-0.41.0 → videopython-0.42.0}/pyproject.toml

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

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/ai/transforms.py

@@ -3,17 +3,21 @@
 from __future__ import annotations
 
 import logging
+import tempfile
+import uuid
+from collections.abc import Iterable
+from pathlib import Path
 from typing import ClassVar, Literal
 
-import cv2
 import numpy as np
 from pydantic import Field
 from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
-from videopython.base.video import Video, VideoMetadata
-from videopython.editing.operation import OpCategory, Operation
+from videopython.base.video import FrameIterator, Video, VideoMetadata
+from videopython.editing._ass import escape_filter_value
+from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
 logger = logging.getLogger(__name__)
 
@@ -29,13 +33,19 @@ class FaceTrackingCrop(Operation):
     Useful for creating vertical (9:16) content from horizontal (16:9) video
     by tracking the speaker's face and keeping it framed.
 
-    Supports GPU acceleration for faster processing with optional frame sampling
-    and simple cinematographic framing rules (headroom / thirds) plus optional
-    movement speed clamping.
+    The crop window has a fixed size -- the largest ``target_aspect`` box
+    that fits the frame (also the output size, so no resampling happens) --
+    and its position follows the smoothed face track. On the streaming path
+    the detection pass runs at plan-compile time over a bounded decode of
+    exactly the frames the filter will see, and the track compiles to a
+    per-frame ``crop`` position command file (ffmpeg ``sendcmd``): zero
+    per-frame Python at render time.
     """
 
     op: Literal["face_crop"] = "face_crop"
     category: ClassVar[OpCategory] = OpCategory.TRANSFORM
+    streamable: ClassVar[bool] = True
+    compiles_from_source: ClassVar[bool] = True
 
     target_aspect: tuple[int, int] = Field((9, 16), description="Output aspect ratio as (width, height).")
     face_selection: Literal["largest", "centered", "index"] = Field(
@@ -58,7 +68,11 @@ class FaceTrackingCrop(Operation):
     smoothing: float = Field(0.8, ge=0, le=1, description="Position smoothing factor (0-1, higher = smoother).")
     max_speed: float | None = Field(None, gt=0, description="Optional max camera movement per frame (normalized).")
     fallback: Literal["center", "last_position", "full_frame"] = Field(
-        "last_position", description="Behavior when no face detected."
+        "last_position",
+        description=(
+            'Behavior when no face detected. "center" and "full_frame" both center the crop '
+            '("full_frame" kept for plan compatibility); "last_position" holds the last tracked crop.'
+        ),
     )
     detection_interval: int = Field(3, ge=1, description="Frames between face detections.")
     backend: Literal["cpu", "gpu", "auto"] = Field("auto", description='Detection backend - "cpu", "gpu", or "auto".')
@@ -77,13 +91,12 @@ class FaceTrackingCrop(Operation):
         return (face_cx, face_cy - self.headroom)
 
     def _resolved_output_dims(self, w: int, h: int) -> tuple[int, int]:
-        """Output ``(width, height)`` after the crop + resize.
+        """Output ``(width, height)`` -- the fixed crop-window size.
 
-        Every frame is resized to this size regardless of the per-frame face
-        position, so it is a pure function of the input dimensions and
-        ``target_aspect``. Single source of truth shared by :meth:`apply` and
-        :meth:`predict_metadata` (mirrors ``Resize._resolve_dims`` /
-        ``Crop._resolve_box``), so the dry-run cannot disagree with the render.
+        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
+        dry-run cannot disagree with the render.
         """
         target_ratio = self.target_aspect[0] / self.target_aspect[1]
         if target_ratio < w / h:
@@ -109,44 +122,20 @@ class FaceTrackingCrop(Operation):
         scale = self.max_speed / distance
         return (current[0] + dx * scale, current[1] + dy * scale)
 
-    def _calculate_crop_region(
+    def _track_crop_positions(
         self,
-        face_cx: float,
-        face_cy: float,
-        face_w: float,
-        face_h: float,
+        frames: Iterable[np.ndarray],
         frame_w: int,
         frame_h: int,
-        center_position: tuple[float, float] | None = None,
-    ) -> tuple[int, int, int, int]:
-        target_ratio = self.target_aspect[0] / self.target_aspect[1]
-        frame_ratio = frame_w / frame_h
-
-        if target_ratio < frame_ratio:
-            crop_h = floor_to_even(frame_h)
-            crop_w = floor_to_even(int(crop_h * target_ratio))
-        else:
-            crop_w = floor_to_even(frame_w)
-            crop_h = floor_to_even(int(crop_w / target_ratio))
-
-        min_face_dim = max(face_w * frame_w, face_h * frame_h)
-        min_crop_dim = min_face_dim * (1 + 2 * self.padding)
-        if crop_w < min_crop_dim * target_ratio:
-            crop_w = floor_to_even(min(int(min_crop_dim * target_ratio), frame_w))
-            crop_h = floor_to_even(min(int(crop_w / target_ratio), frame_h))
-
-        if center_position is None:
-            center_position = self._apply_framing_offset(face_cx, face_cy, face_h)
-
-        center_x = center_position[0] * frame_w
-        center_y = center_position[1] * frame_h
-        x = int(center_x - crop_w / 2)
-        y = int(center_y - crop_h / 2)
-        x = max(0, min(x, frame_w - crop_w))
-        y = max(0, min(y, frame_h - crop_h))
-        return (x, y, crop_w, crop_h)
+    ) -> list[tuple[int, int]]:
+        """Per-frame crop top-left positions for a fixed-size crop window.
 
-    def apply(self, video: Video) -> Video:
+        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.
+        """
+        out_w, out_h = self._resolved_output_dims(frame_w, frame_h)
         tracker = FaceTracker(
             selection_strategy=self.face_selection,
             face_index=self.face_index,
@@ -155,16 +144,31 @@ class FaceTrackingCrop(Operation):
             backend=self.backend,
             sample_rate=self.sample_rate,
         )
+        default = ((frame_w - out_w) // 2, (frame_h - out_h) // 2)
+        last = default
+        current_position = (0.5, 0.5)
+        positions: list[tuple[int, int]] = []
+        for i, frame in enumerate(frames):
+            face_info = tracker.detect_and_track(frame, i)
+            if face_info:
+                cx, cy, _fw, fh = face_info
+                target = self._apply_framing_offset(cx, cy, fh)
+                current_position = self._clamp_speed(current_position, target)
+                x = int(current_position[0] * frame_w - out_w / 2)
+                y = int(current_position[1] * frame_h - out_h / 2)
+                x = max(0, min(x, frame_w - out_w))
+                y = max(0, min(y, frame_h - out_h))
+                last = (x, y)
+                positions.append((x, y))
+            elif self.fallback == "last_position":
+                positions.append(last)
+            else:  # "center" / "full_frame" (the latter kept for plan compat)
+                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)
-
-        default_x = (w - out_w) // 2
-        default_y = (h - out_h) // 2
-        last_crop = (default_x, default_y, out_w, out_h)
-        current_position = (0.5, 0.5)
-
-        framing_label = self.framing_rule if self.framing_rule != "offset" else "legacy-offset"
         logger.info(
             "Face tracking crop: %dx%d -> %dx%d (%d:%d, framing=%s)",
             w,
@@ -173,33 +177,55 @@ class FaceTrackingCrop(Operation):
             out_h,
             self.target_aspect[0],
             self.target_aspect[1],
-            framing_label,
+            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
 
-        new_frames = []
-        for i in tqdm(range(len(video.frames)), desc="Face tracking crop"):
-            frame = video.frames[i]
-            face_info = tracker.detect_and_track(frame, i)
+    def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
+        """Compile the face track to a per-frame ``crop`` position command file.
 
-            if face_info:
-                cx, cy, fw, fh = face_info
-                target_position = self._apply_framing_offset(cx, cy, fh)
-                current_position = self._clamp_speed(current_position, target_position)
-                crop = self._calculate_crop_region(cx, cy, fw, fh, w, h, center_position=current_position)
-                last_crop = crop
-            else:
-                if self.fallback == "center":
-                    crop = (default_x, default_y, out_w, out_h)
-                elif self.fallback == "last_position":
-                    crop = last_crop
-                else:  # full_frame
-                    crop = (0, 0, w, h)
-
-            x, y, cw, ch = crop
-            cropped = frame[y : y + ch, x : x + cw]
-            if cropped.shape[1] != out_w or cropped.shape[0] != out_h:
-                cropped = cv2.resize(cropped, (out_w, out_h), interpolation=cv2.INTER_AREA)
-            new_frames.append(cropped)
-
-        video.frames = np.array(new_frames, dtype=np.uint8)
-        return video
+        Runs the detection pass at plan-compile time over a bounded decode of
+        the segment (through the same decode-stage filter prefix the render
+        will use, so the detector sees identical frames), then emits one
+        ``sendcmd`` interval per frame driving a fixed-size ``crop``. Returns
+        ``None`` when the input frames are not reproducible at compile time
+        (``decode_filters is None`` -- the op sits behind per-frame Python
+        effects) or the source is unknown.
+        """
+        if ctx.source_path is None or ctx.decode_filters is None or ctx.frame_count <= 0:
+            return None
+        out_w, out_h = self._resolved_output_dims(ctx.width, ctx.height)
+
+        with FrameIterator(
+            ctx.source_path,
+            start_second=ctx.start_second,
+            end_second=ctx.end_second,
+            vf_filters=list(ctx.decode_filters),
+            output_width=ctx.width,
+            output_height=ctx.height,
+        ) as decoder:
+            frames = (frame for _, frame in decoder)
+            positions = self._track_crop_positions(
+                tqdm(frames, desc="Face tracking (compile)", total=ctx.frame_count), ctx.width, ctx.height
+            )
+        if not positions:
+            return None
+
+        label = f"fc{uuid.uuid4().hex[:8]}"
+        lines = []
+        for i, (x, y) in enumerate(positions):
+            t0 = i / ctx.fps
+            t1 = (i + 1) / ctx.fps
+            lines.append(f"{t0:.6f}-{t1:.6f} crop@{label} x {x}, crop@{label} y {y};")
+        tmp = tempfile.NamedTemporaryFile("w", suffix=".cmd", delete=False, encoding="utf-8")
+        try:
+            tmp.write("\n".join(lines) + "\n")
+        finally:
+            tmp.close()
+        cmd_path = Path(tmp.name)
+        ctx.owned_files.append(cmd_path)
+
+        x0, y0 = positions[0]
+        return f"sendcmd=f={escape_filter_value(str(cmd_path))},crop@{label}=w={out_w}:h={out_h}:x={x0}:y={y0}"

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/base/exceptions.py

@@ -92,7 +92,7 @@ class PlanErrorCode(str, Enum):
     UNKNOWN_OP = "unknown_op"
     CONCAT_MISMATCH = "concat_mismatch"
     POST_OP_REQUIRES_CONTEXT = "post_op_requires_context"
-    # Streaming strictness (opt-in via strict_streaming).
+    # Streaming: unstreamable op at its plan position (always reported).
     STREAMING_FALLBACK = "streaming_fallback"
 
 
@@ -103,7 +103,7 @@ class PlanError:
     ``location`` is a path into the plan (e.g. ``'segments[1].operations[0]'``);
     the remaining fields are populated when meaningful for the ``code``.
     ``detail`` carries a short human-readable cause when the code alone is not
-    actionable (e.g. *why* an op forces the eager fallback) -- prose meant for
+    actionable (e.g. *why* an op cannot stream at its plan position) -- prose meant for
     LLM refine-loop feedback, not for branching.
     """
 

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/base/video.py

@@ -234,12 +234,16 @@ class FrameIterator:
         if self.start_second > 0:
             cmd.extend(["-ss", str(self.start_second)])
 
-        cmd.extend(["-i", str(self.path)])
-
+        # Input-side -t: trim the SOURCE segment before the filter chain. As
+        # an output option it would instead cap the post-filter duration,
+        # silently truncating duration-extending filters (slow-motion setpts,
+        # freeze-frame loop).
         if self.end_second is not None:
             duration = self.end_second - self.start_second
             cmd.extend(["-t", str(duration)])
 
+        cmd.extend(["-i", str(self.path)])
+
         if self._vf_filters:
             cmd.extend(["-vf", ",".join(self._vf_filters)])
 

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/editing/__init__.py

@@ -33,7 +33,6 @@ from .transforms import (
     FreezeFrame,
     ResampleFPS,
     Resize,
-    Reverse,
     SilenceRemoval,
     SpeedChange,
 )
@@ -54,7 +53,6 @@ __all__ = [
     "Crop",
     "CropMode",
     "SpeedChange",
-    "Reverse",
     "FreezeFrame",
     "SilenceRemoval",
     # Effects

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/editing/effects.py

@@ -429,6 +429,7 @@ class Fade(Effect):
 
     op: Literal["fade"] = "fade"
     streamable: ClassVar[bool] = True
+    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.'),
@@ -513,6 +514,7 @@ class VolumeAdjust(Effect):
 
     op: Literal["volume_adjust"] = "volume_adjust"
     streamable: ClassVar[bool] = True
+    audio_coupled: ClassVar[bool] = True
 
     volume: float = Field(
         1.0,

{videopython-0.41.0 → videopython-0.42.0}/src/videopython/editing/operation.py

@@ -41,6 +41,7 @@ from pydantic import BaseModel, ConfigDict, Discriminator, Field, TypeAdapter
 from tqdm import tqdm
 
 if TYPE_CHECKING:
+    from videopython.audio import Audio
     from videopython.base.video import Video, VideoMetadata
 
 __all__ = [
@@ -102,6 +103,12 @@ class BoundedTimeField(NamedTuple):
 class FilterCtx:
     """Current pipeline state (post-prior-ops) when compiling to ffmpeg.
 
+    ``frame_count`` is the number of frames entering the filter at this chain
+    position (the plan builder folds ``predict_metadata`` through the chain),
+    so duration-aware compilations (a speed ramp's time-warp expression, a
+    freeze's frame indices) can be exact. ``0`` when unknown -- compilations
+    that need it must return ``None`` (no filter compilation) in that case.
+
     ``context`` carries the resolved, segment-local runtime context (the same
     re-based values ``streaming_init`` receives) so a context-consuming op can
     compile itself into the filter chain (e.g. ``add_subtitles`` consuming the
@@ -110,13 +117,26 @@ class FilterCtx:
     ``owned_files`` collects temp files a compilation creates (the ``.ass``
     file a ``subtitles=`` entry references); the plan runner deletes them once
     streaming finishes or the plan is abandoned.
+
+    ``source_path``/``start_second``/``end_second`` locate the segment on
+    disk, and ``decode_filters`` is the decode-stage filter prefix ahead of
+    this op -- together they let a compilation run its own bounded decode
+    pass over exactly the frames the filter will see (``face_crop``'s
+    detection). ``decode_filters`` is ``None`` when those frames are not
+    reproducible at compile time (the op sits at the encode stage, behind
+    per-frame Python effects); such compilations must return ``None``.
     """
 
     width: int
     height: int
     fps: float
+    frame_count: int = 0
     context: dict[str, Any] = field(default_factory=dict)
     owned_files: list[Path] = field(default_factory=list)
+    source_path: Path | None = None
+    start_second: float = 0.0
+    end_second: float | None = None
+    decode_filters: tuple[str, ...] | None = ()
 
 
 LLM_HIDDEN_KEY = "llm_hidden"
@@ -213,7 +233,7 @@ class Operation(BaseModel):
     ``streamable``, and ``requires`` ClassVars.
 
     The default ``apply`` raises ``NotImplementedError``; ``predict_metadata``
-    defaults to identity; ``to_ffmpeg_filter`` defaults to ``None`` (eager).
+    defaults to identity; ``to_ffmpeg_filter`` defaults to ``None`` (no filter compilation).
     """
 
     model_config = ConfigDict(extra="forbid", validate_assignment=True)
@@ -223,6 +243,22 @@ class Operation(BaseModel):
     category: ClassVar[OpCategory] = OpCategory.SPECIAL
     streamable: ClassVar[bool] = False
     requires: ClassVar[tuple[str, ...]] = ()
+    compiles_from_source: ClassVar[bool] = False
+    """Whether the op's filter compile decodes the source itself (face_crop's
+    detection pass). Such ops cannot sit at the encode stage -- the frames
+    behind per-frame Python effects are not reproducible at compile time --
+    so both the plan builder and the streamability report reject them as
+    UNSTREAMABLE there."""
+    changes_duration: ClassVar[bool] = False
+    """Whether the op's output duration differs from its input (speed, freeze).
+
+    The streaming plan builder folds ``predict_metadata`` through the chain
+    either way; this flag additionally gates time-based *context*: a
+    context-consuming op scheduled after a duration-changing transform would
+    receive timestamps on the wrong timeline, so such plans are rejected as
+    UNSTREAMABLE until context re-mapping exists. The streamability report
+    mirrors the same rule.
+    """
     llm_exposed: ClassVar[bool] = True
     time_fields: ClassVar[tuple[BoundedTimeField, ...]] = ()
     """Time-valued (seconds) fields :meth:`VideoEdit.repair` may clamp into range.
@@ -370,13 +406,29 @@ class Operation(BaseModel):
         return meta
 
     def to_ffmpeg_filter(self, ctx: FilterCtx) -> str | None:
-        """Compile to an ffmpeg ``-vf`` filter expression, or ``None`` for eager.
+        """Compile to an ffmpeg ``-vf`` filter expression, or ``None`` for no filter compilation.
 
         Streamable transforms override this. Effects use ``process_frame``
         instead -- they do not go through ffmpeg filters.
         """
         return None
 
+    def transform_audio(self, audio: Audio, output_duration: float, fps: float, **context: Any) -> Audio:
+        """The op's audio-domain twin for the streaming path.
+
+        Video streams through the ffmpeg filter chain, but segment audio is
+        processed in memory (``_load_segment_audio``); a duration-changing
+        transform must therefore transform the audio to match
+        (``speed_change`` time-stretches, ``freeze_frame`` inserts silence,
+        ``silence_removal`` cuts the same windows). ``output_duration`` is
+        the predicted post-op duration the result must fit; ``context``
+        carries the op's resolved ``requires`` values (segment-local), for
+        twins that need them. Identity by default -- the runner only replays
+        ops that override this. The eager ``apply`` should delegate its audio
+        handling here so the two paths cannot drift.
+        """
+        return audio
+
 
 class Effect(Operation):
     """Operation that preserves shape and frame count, driven by per-frame streaming.
@@ -398,6 +450,14 @@ class Effect(Operation):
     """
 
     category: ClassVar[OpCategory] = OpCategory.EFFECT
+    audio_coupled: ClassVar[bool] = False
+    """Whether the effect mutates audio alongside pixels (``_apply_audio``).
+
+    Audio-coupled effects cannot fold as post-operations across segment
+    boundaries: each segment's audio is processed independently, so a gain
+    envelope spanning a concat boundary would restart mid-ramp. The plan
+    builder and the streamability report both consult this.
+    """
 
     window: TimeRange | None = Field(
         None,