videopython 0.44.0__tar.gz → 0.44.1__tar.gz

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

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

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

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

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/__init__.py

@@ -16,9 +16,10 @@ runtime.
 
 from __future__ import annotations
 
-import importlib
 from typing import TYPE_CHECKING
 
+from videopython.ai._optional import lazy_exports
+
 if TYPE_CHECKING:
     # Redundant aliases mark these as intentional re-exports (mypy/IDE see the
     # symbols; ruff doesn't flag them as unused). Runtime resolution is lazy via
@@ -43,7 +44,7 @@ if TYPE_CHECKING:
 # Public symbol -> submodule (relative to this package) that defines it. The
 # submodule's own (lazy) __init__ resolves the symbol; we only import the
 # submodule, never its siblings.
-_SYMBOL_MODULES: dict[str, str] = {
+_exports: dict[str, str] = {
     # Generation
     "TextToVideo": ".generation",
     "ImageToVideo": ".generation",
@@ -67,16 +68,6 @@ _SYMBOL_MODULES: dict[str, str] = {
     "VideoAnalyzer": ".video_analysis",
 }
 
-__all__ = list(_SYMBOL_MODULES)
-
-
-def __getattr__(name: str) -> object:
-    module_name = _SYMBOL_MODULES.get(name)
-    if module_name is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    module = importlib.import_module(module_name, __name__)
-    return getattr(module, name)
-
+__all__ = list(_exports)
 
-def __dir__() -> list[str]:
-    return sorted(__all__)
+__getattr__, __dir__ = lazy_exports(__name__, _exports)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/_optional.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 
 import importlib
 from types import ModuleType
+from typing import Callable
 
 
 def require(module: str, extra: str, *, feature: str | None = None) -> ModuleType:
@@ -45,3 +46,42 @@ def require(module: str, extra: str, *, feature: str | None = None) -> ModuleTyp
     except ImportError as exc:
         label = feature or module.split(".")[0]
         raise ImportError(f"{label} requires the '{extra}' extra: pip install 'videopython[{extra}]'") from exc
+
+
+def lazy_exports(package: str, exports: dict[str, str]) -> tuple[Callable[[str], object], Callable[[], list[str]]]:
+    """Build the PEP 562 lazy ``__getattr__``/``__dir__`` pair for a package.
+
+    Re-exports a set of public symbols lazily: the submodule backing a symbol is
+    imported only on first attribute access, so importing the package does not
+    pull in any sibling leaf module (this is what keeps the granular ``ai``
+    extras independently installable).
+
+    Args:
+        package: The ``__name__`` of the package defining the re-exports. Used
+            both for the ``AttributeError`` message and as the anchor for
+            resolving relative ``exports`` values.
+        exports: Mapping of public symbol name to the module that defines it.
+            Values may be relative (``".audio"`` — resolved against ``package``)
+            or absolute (``"videopython.ai.dubbing.config"``).
+
+    Returns:
+        A ``(__getattr__, __dir__)`` tuple to assign in the package namespace.
+        ``__getattr__`` imports the backing module and returns the symbol,
+        raising ``AttributeError`` for unknown names; ``__dir__`` returns the
+        sorted export names.
+    """
+
+    def __getattr__(name: str) -> object:
+        module_name = exports.get(name)
+        if module_name is None:
+            raise AttributeError(f"module {package!r} has no attribute {name!r}")
+        if module_name.startswith("."):
+            module = importlib.import_module(module_name, package)
+        else:
+            module = importlib.import_module(module_name)
+        return getattr(module, name)
+
+    def __dir__() -> list[str]:
+        return sorted(exports)
+
+    return __getattr__, __dir__

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/dubbing/__init__.py

@@ -11,9 +11,10 @@ symbols visible to mypy and IDEs.
 
 from __future__ import annotations
 
-import importlib
 from typing import TYPE_CHECKING
 
+from videopython.ai._optional import lazy_exports
+
 if TYPE_CHECKING:
     # Redundant aliases = intentional re-exports (visible to mypy/IDE, not
     # flagged by ruff). Runtime resolution is lazy via __getattr__ below.
@@ -32,7 +33,7 @@ if TYPE_CHECKING:
     from videopython.ai.generation.translation import UnsupportedLanguageError as UnsupportedLanguageError
 
 # Public symbol -> fully-qualified module that defines it.
-_SYMBOL_MODULES: dict[str, str] = {
+_exports: dict[str, str] = {
     "DubbingConfig": "videopython.ai.dubbing.config",
     "VideoDubber": "videopython.ai.dubbing.dubber",
     "DubbingResult": "videopython.ai.dubbing.models",
@@ -48,16 +49,6 @@ _SYMBOL_MODULES: dict[str, str] = {
     "UnsupportedLanguageError": "videopython.ai.generation.translation",
 }
 
-__all__ = list(_SYMBOL_MODULES)
-
-
-def __getattr__(name: str) -> object:
-    module_name = _SYMBOL_MODULES.get(name)
-    if module_name is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    module = importlib.import_module(module_name)
-    return getattr(module, name)
-
+__all__ = list(_exports)
 
-def __dir__() -> list[str]:
-    return sorted(__all__)
+__getattr__, __dir__ = lazy_exports(__name__, _exports)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/generation/__init__.py

@@ -8,9 +8,10 @@ Each symbol's backing leaf module is imported only on first access, so
 
 from __future__ import annotations
 
-import importlib
 from typing import TYPE_CHECKING
 
+from videopython.ai._optional import lazy_exports
+
 if TYPE_CHECKING:
     # Redundant aliases = intentional re-exports (visible to mypy/IDE, not
     # flagged by ruff). Runtime resolution is lazy via __getattr__ below.
@@ -20,7 +21,7 @@ if TYPE_CHECKING:
     from .video import ImageToVideo as ImageToVideo
     from .video import TextToVideo as TextToVideo
 
-_SYMBOL_MODULES: dict[str, str] = {
+_exports: dict[str, str] = {
     "TextToSpeech": ".audio",
     "TextToMusic": ".audio",
     "TextToImage": ".image",
@@ -28,16 +29,6 @@ _SYMBOL_MODULES: dict[str, str] = {
     "TextToVideo": ".video",
 }
 
-__all__ = list(_SYMBOL_MODULES)
-
-
-def __getattr__(name: str) -> object:
-    module_name = _SYMBOL_MODULES.get(name)
-    if module_name is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    module = importlib.import_module(module_name, __name__)
-    return getattr(module, name)
-
+__all__ = list(_exports)
 
-def __dir__() -> list[str]:
-    return sorted(__all__)
+__getattr__, __dir__ = lazy_exports(__name__, _exports)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/generation/_tts_backend.py

@@ -10,7 +10,7 @@ local ``TextToSpeech`` (which pulls ``chatterbox-tts`` via the ``[tts]`` extra)
 satisfies this protocol structurally — no changes needed there. A consumer that
 can't or won't install chatterbox (e.g. a service running synthesis in a
 separate process or on a remote/Modal function) supplies its own object
-implementing :meth:`SpeechBackend.synthesize` and injects it; the pipeline never
+implementing :meth:`SpeechBackend.generate_audio` and injects it; the pipeline never
 imports chatterbox in that case. videopython ships ONLY this protocol plus the
 local backend — no reference remote/HTTP backend.
 """

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

@@ -15,8 +15,8 @@ from tqdm import tqdm
 
 from videopython.ai.understanding.faces import FaceTracker
 from videopython.base._dimensions import floor_to_even
+from videopython.base._ffmpeg import escape_filter_value
 from videopython.base.video import FrameIterator, VideoMetadata
-from videopython.editing._ass import escape_filter_value
 from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
 logger = logging.getLogger(__name__)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/ai/understanding/__init__.py

@@ -8,9 +8,10 @@ does not pull in ``audio`` (whisper/pyannote — ``[asr]``). The
 
 from __future__ import annotations
 
-import importlib
 from typing import TYPE_CHECKING
 
+from videopython.ai._optional import lazy_exports
+
 if TYPE_CHECKING:
     # Redundant aliases = intentional re-exports (visible to mypy/IDE, not
     # flagged by ruff). Runtime resolution is lazy via __getattr__ below.
@@ -21,7 +22,7 @@ if TYPE_CHECKING:
     from .objects import ObjectDetector as ObjectDetector
     from .temporal import SemanticSceneDetector as SemanticSceneDetector
 
-_SYMBOL_MODULES: dict[str, str] = {
+_exports: dict[str, str] = {
     "AudioToText": ".audio",
     "AudioClassifier": ".audio",
     "FaceTracker": ".faces",
@@ -30,16 +31,6 @@ _SYMBOL_MODULES: dict[str, str] = {
     "SemanticSceneDetector": ".temporal",
 }
 
-__all__ = list(_SYMBOL_MODULES)
-
-
-def __getattr__(name: str) -> object:
-    module_name = _SYMBOL_MODULES.get(name)
-    if module_name is None:
-        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-    module = importlib.import_module(module_name, __name__)
-    return getattr(module, name)
-
+__all__ = list(_exports)
 
-def __dir__() -> list[str]:
-    return sorted(__all__)
+__getattr__, __dir__ = lazy_exports(__name__, _exports)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/base/_ffmpeg.py

@@ -150,3 +150,14 @@ def popen_encode(cmd: Sequence[str]) -> Iterator[subprocess.Popen[bytes]]:
     _, stderr = proc.communicate()
     if proc.returncode != 0:
         raise FFmpegRunError(f"ffmpeg failed (exit {proc.returncode}): {stderr.decode(errors='replace')}")
+
+
+def escape_filter_value(value: str) -> str:
+    """Quote a string for use as an ffmpeg filter option value.
+
+    Escapes the option-value level metacharacters (``\\``, ``'``, ``:``) and
+    wraps the result in single quotes so the filtergraph-level separators
+    (``,``, ``;``, ``[``, ``]``) pass through untouched.
+    """
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'").replace(":", "\\:")
+    return f"'{escaped}'"

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/base/exceptions.py

@@ -116,7 +116,6 @@ class PlanError:
     field: str | None = None
     value: float | None = None
     limit: float | None = None
-    predicted_duration: float | None = None
     detail: str | None = None
 
     def to_prompt_line(self) -> str:
@@ -131,8 +130,7 @@ class PlanError:
         ``None`` fields are skipped)::
 
             <CODE_NAME> [at <location>] [(op '<op>')]: [<field>=<value>]
-            [(limit <limit>)] [(predicted duration <predicted_duration>s)]
-            [-- <detail>]
+            [(limit <limit>)] [-- <detail>]
 
         Every :class:`PlanErrorCode` yields a non-empty line: the code name is
         always present, so a code carrying no other fields still renders
@@ -155,8 +153,6 @@ class PlanError:
             clauses.append(f"value={_fmt_num(self.value)}")
         if self.limit is not None:
             clauses.append(f"limit {_fmt_num(self.limit)}")
-        if self.predicted_duration is not None:
-            clauses.append(f"predicted duration {_fmt_num(self.predicted_duration)}s")
 
         if clauses:
             line += ": " + ", ".join(clauses)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/base/video.py

@@ -177,6 +177,23 @@ class VideoMetadata:
             total_seconds=round(seconds, 4),
         )
 
+    def with_frame_count(self, frame_count: int) -> VideoMetadata:
+        """Return new metadata with updated frame count.
+
+        Args:
+            frame_count: New frame count.
+
+        Returns:
+            New VideoMetadata with updated frame count and duration.
+        """
+        return VideoMetadata(
+            height=self.height,
+            width=self.width,
+            fps=self.fps,
+            frame_count=frame_count,
+            total_seconds=round(frame_count / self.fps, 4),
+        )
+
     def with_dimensions(self, width: int, height: int) -> VideoMetadata:
         """Return new metadata with updated dimensions.
 

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/editing/_ass.py

@@ -27,7 +27,7 @@ from enum import Enum
 
 from videopython.base.transcription import Transcription
 
-__all__ = ["AnchorPoint", "AssLook", "build_ass", "escape_filter_value"]
+__all__ = ["AnchorPoint", "AssLook", "build_ass"]
 
 RGBColor = tuple[int, int, int]
 RGBAColor = tuple[int, int, int, int]
@@ -117,17 +117,6 @@ def _escape_text(text: str) -> str:
     return text.replace("\\", "/").replace("{", "(").replace("}", ")").replace("\n", " ")
 
 
-def escape_filter_value(value: str) -> str:
-    """Quote a string for use as an ffmpeg filter option value.
-
-    Escapes the option-value level metacharacters (``\\``, ``'``, ``:``) and
-    wraps the result in single quotes so the filtergraph-level separators
-    (``,``, ``;``, ``[``, ``]``) pass through untouched.
-    """
-    escaped = value.replace("\\", "\\\\").replace("'", "\\'").replace(":", "\\:")
-    return f"'{escaped}'"
-
-
 def _word_state_intervals(
     start: float, end: float, word_spans: list[tuple[float, float]]
 ) -> list[tuple[int, int, int | None]]:

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

@@ -32,9 +32,33 @@ __all__ = [
     "MusicBed",
     "build_music_bed_filter_complex",
     "duck_volume_expression",
+    "volume_envelope",
 ]
 
 
+def volume_envelope(terms: list[tuple[str, str]]) -> str:
+    """Build a nested-if gain envelope expression for volume automation.
+
+    Takes a list of ``(condition, gain_expr)`` tuples and folds them into a
+    nested ``if()`` expression evaluated outermost-first (the terms in
+    chronological order), with each condition mapping to its gain expression and
+    ``"1"`` as the final fallback (no change). The result is wrapped in the
+    ffmpeg ``volume`` filter format.
+
+    Args:
+        terms: List of ``(condition_str, gain_expr_str)`` tuples, where each
+            condition is an ffmpeg expression (e.g. ``"between(t,0,1)"``) and
+            ``gain_expr`` is the volume multiplier for that condition.
+
+    Returns:
+        Complete ffmpeg volume filter string: ``volume=volume='...':eval=frame``.
+    """
+    expr = "1"
+    for cond, gain in reversed(terms):
+        expr = f"if({cond},{gain},{expr})"
+    return f"volume=volume='{expr}':eval=frame"
+
+
 def duck_volume_expression(
     speech: list[tuple[float, float]],
     *,
@@ -74,10 +98,7 @@ def duck_volume_expression(
         # Release: linearly rise from floor back to 1 across [e, rel_end].
         rel = f"({floor:.6f}+{duck:.6f}*(t-{e:.6f})/{release:.6f})"
         terms.append((f"between(t,{e:.6f},{rel_end:.6f})", rel))
-    expr = "1"
-    for cond, gain in reversed(terms):
-        expr = f"if({cond},{gain},{expr})"
-    return f"volume=volume='{expr}':eval=frame"
+    return volume_envelope(terms)
 
 
 class MusicBed(BaseModel):

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

@@ -28,6 +28,7 @@ from videopython.base.description import BoundingBox
 from videopython.base.exceptions import PlanError, PlanErrorCode, PlanValidationError
 from videopython.base.fonts import load_font
 from videopython.editing._easing import ease, ease_out
+from videopython.editing.audio_ops import volume_envelope
 from videopython.editing.operation import Effect, FilterCtx
 
 if TYPE_CHECKING:
@@ -505,10 +506,7 @@ class Fade(Effect):
         if self.mode in ("out", "in_out"):
             out_start = stop_s - ramp
             terms.append((f"between(t,{out_start:.6f},{stop_s:.6f})", self._curve_expr(f"({stop_s:.6f}-t)/{ramp:.6f}")))
-        expr = "1"
-        for cond, gain in reversed(terms):
-            expr = f"if({cond},{gain},{expr})"
-        return f"volume=volume='{expr}':eval=frame"
+        return volume_envelope(terms)
 
 
 class VolumeAdjust(Effect):
@@ -566,12 +564,12 @@ class VolumeAdjust(Effect):
         down_start = stop_s - ramp
         up = f"(1+({v:.6f}-1)*sqrt((t-{start_s:.6f})/{ramp:.6f}))"
         down = f"(1+({v:.6f}-1)*sqrt(({stop_s:.6f}-t)/{ramp:.6f}))"
-        expr = (
-            f"if(between(t,{start_s:.6f},{up_end:.6f}),{up},"
-            f"if(between(t,{up_end:.6f},{down_start:.6f}),{v:.6f},"
-            f"if(between(t,{down_start:.6f},{stop_s:.6f}),{down},1)))"
-        )
-        return f"volume=volume='{expr}':eval=frame"
+        terms = [
+            (f"between(t,{start_s:.6f},{up_end:.6f})", up),
+            (f"between(t,{up_end:.6f},{down_start:.6f})", f"{v:.6f}"),
+            (f"between(t,{down_start:.6f},{stop_s:.6f})", down),
+        ]
+        return volume_envelope(terms)
 
 
 class _AnchoredOverlay(Effect):

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/editing/streaming.py

@@ -115,10 +115,10 @@ def analyze_streamability(
     ``streamable`` ClassVar as the authoritative declaration (a flag-False
     transform never streams, even with a working ``to_ffmpeg_filter``); the
     one divergence the flag cannot express -- flag True but the filter
-    compiles to ``None`` -- is caught at runtime by the strict-mode drift
-    guard, and a registry test pins flag-True transforms to an actual
-    ``to_ffmpeg_filter`` override. Purely structural: no disk access and no
-    runtime context.
+    compiles to ``None`` -- is caught at runtime by the ``STREAMING_FALLBACK``
+    raise in ``_compile_streaming_plans``, and a registry test pins flag-True
+    transforms to an actual ``to_ffmpeg_filter`` override. Purely structural:
+    no disk access and no runtime context.
 
     Segment transitions (``SegmentConfig.transition_in``) do not appear here:
     a transition is a native ffmpeg ``xfade``/``acrossfade`` pass over two

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/editing/transcription_overlay.py

@@ -24,9 +24,10 @@ from typing import ClassVar, Literal
 from PIL import ImageFont
 from pydantic import Field
 
+from videopython.base._ffmpeg import escape_filter_value
 from videopython.base.fonts import BUNDLED_FONT_FAMILIES, bundled_fonts_dir, load_font
 from videopython.base.transcription import Transcription
-from videopython.editing._ass import AnchorPoint, AssLook, build_ass, escape_filter_value
+from videopython.editing._ass import AnchorPoint, AssLook, build_ass
 from videopython.editing.operation import Effect, FilterCtx
 
 __all__ = ["TranscriptionOverlay", "SubtitleStyle", "SubtitleRegion"]

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/editing/transforms.py

@@ -128,7 +128,6 @@ class CutSeconds(Operation):
                         field="end",
                         value=self.end,
                         limit=meta.total_seconds,
-                        predicted_duration=meta.total_seconds,
                     )
                 ],
             )
@@ -369,15 +368,7 @@ class SpeedChange(Operation):
                     )
                 ],
             )
-        from videopython.base.video import VideoMetadata as _Meta
-
-        return _Meta(
-            height=meta.height,
-            width=meta.width,
-            fps=meta.fps,
-            frame_count=new_count,
-            total_seconds=round(new_count / meta.fps, 4),
-        )
+        return meta.with_frame_count(new_count)
 
 
 class FreezeFrame(Operation):
@@ -487,7 +478,6 @@ class FreezeFrame(Operation):
                         field="timestamp",
                         value=self.timestamp,
                         limit=meta.total_seconds,
-                        predicted_duration=meta.total_seconds,
                     )
                 ],
             )
@@ -498,15 +488,7 @@ class FreezeFrame(Operation):
             frame_idx = min(round(self.timestamp * meta.fps), meta.frame_count - 1)
             replace_end = min(frame_idx + freeze_count, meta.frame_count)
             new_count = meta.frame_count - (replace_end - frame_idx) + freeze_count
-        from videopython.base.video import VideoMetadata as _Meta
-
-        return _Meta(
-            height=meta.height,
-            width=meta.width,
-            fps=meta.fps,
-            frame_count=new_count,
-            total_seconds=round(new_count / meta.fps, 4),
-        )
+        return meta.with_frame_count(new_count)
 
 
 class SilenceRemoval(Operation):
@@ -636,12 +618,4 @@ class SilenceRemoval(Operation):
         if keep is None:
             return meta
         new_count = sum(e - s for s, e in keep)
-        from videopython.base.video import VideoMetadata as _Meta
-
-        return _Meta(
-            height=meta.height,
-            width=meta.width,
-            fps=meta.fps,
-            frame_count=new_count,
-            total_seconds=round(new_count / meta.fps, 4),
-        )
+        return meta.with_frame_count(new_count)

{videopython-0.44.0 → videopython-0.44.1}/src/videopython/editing/video_edit.py

@@ -73,6 +73,10 @@ assert set(get_args(TransitionType)) == set(TRANSITION_TYPES), "TransitionType L
 # (``validate``, byte-stable prose) or accumulate them all (``check``).
 _LocatedError = tuple[str, PlanError]
 
+# Sentinel marking "caller did not pass decode_filters" so a FilterCtx builder
+# can fall back to FilterCtx's own default instead of forcing a value.
+_DECODE_FILTERS_DEFAULT = object()
+
 
 def _resolve_operation(value: Any) -> Operation:
     """BeforeValidator: turn a dict into the right :class:`Operation` subclass.
@@ -282,7 +286,6 @@ def _segment_end_exceeds_source(index: int, seg: SegmentConfig, meta: VideoMetad
         field="end",
         value=seg.end,
         limit=meta.total_seconds,
-        predicted_duration=meta.total_seconds,
     )
 
 
@@ -391,7 +394,6 @@ def _window_errors(op: Operation, duration: float, location: str) -> list[_Locat
                     field="window.start",
                     value=start,
                     limit=duration,
-                    predicted_duration=duration,
                 ),
             )
         )
@@ -406,7 +408,6 @@ def _window_errors(op: Operation, duration: float, location: str) -> list[_Locat
                     field="window.stop",
                     value=stop,
                     limit=duration,
-                    predicted_duration=duration,
                 ),
             )
         )
@@ -470,6 +471,35 @@ def _transition_structure_errors(segments: list[SegmentConfig]) -> list[_Located
     return out
 
 
+def _transition_too_long_error(
+    index: int,
+    spec: TransitionSpec,
+    overlap: int,
+    limit_frames: int,
+    limit_seconds: float,
+    remedy: str,
+) -> _LocatedError:
+    """The located ``TRANSITION_TOO_LONG`` error for an overlap that fills a segment.
+
+    Shared by the validation pass (:func:`_transition_duration_errors`) and the
+    pre-decode guard (:meth:`VideoEdit._assert_transitions_runnable`); each call
+    site resolves its own ``overlap``/``limit_frames``/``limit_seconds`` from its
+    own fps source, then supplies the trailing ``remedy`` prose.
+    """
+    message = (
+        f"Segment {index}: transition_in overlaps {overlap} frames ({spec.duration}s) but must overlap "
+        f"fewer frames than the shorter adjacent segment ({limit_frames} frames, {limit_seconds}s); "
+        f"{remedy}"
+    )
+    return message, PlanError(
+        code=PlanErrorCode.TRANSITION_TOO_LONG,
+        location=f"segments[{index}]",
+        field="transition_in.duration",
+        value=spec.duration,
+        limit=limit_seconds,
+    )
+
+
 def _transition_duration_errors(
     segments: list[SegmentConfig],
     outputs: list[VideoMetadata],
@@ -496,18 +526,13 @@ def _transition_duration_errors(
         if overlap >= limit_frames:
             limit_seconds = round(limit_frames / fps, 4) if fps else 0.0
             out.append(
-                (
-                    f"Segment {i}: transition_in overlaps {overlap} frames ({spec.duration}s) but must overlap "
-                    f"fewer frames than the shorter adjacent segment ({limit_frames} frames, {limit_seconds}s); "
+                _transition_too_long_error(
+                    i,
+                    spec,
+                    overlap,
+                    limit_frames,
+                    limit_seconds,
                     "a transition cannot consume a whole segment.",
-                    PlanError(
-                        code=PlanErrorCode.TRANSITION_TOO_LONG,
-                        location=f"segments[{i}]",
-                        field="transition_in.duration",
-                        value=spec.duration,
-                        limit=limit_seconds,
-                        predicted_duration=limit_seconds,
-                    ),
                 )
             )
     return out
@@ -891,31 +916,21 @@ class VideoEdit(BaseModel):
             prop["default"] = []
             return prop
 
-        def _transition_field() -> dict[str, Any]:
-            # `transition_in` is `TransitionSpec | None`; Pydantic emits it as an
-            # `anyOf` with a `$ref` to a buried `$defs/TransitionSpec`. Inline a
-            # self-contained closed object (titles dropped, descriptions kept) so
-            # the field needs no external `$defs` -- the same self-containment
-            # the op union relies on.
-            ts = TransitionSpec.model_json_schema()
-            ts.pop("title", None)
-            ts.pop("$defs", None)
-            for sub in ts.get("properties", {}).values():
+        def _optional_model_field(
+            inline_model: type[BaseModel], parent: type[BaseModel], field_name: str
+        ) -> dict[str, Any]:
+            # An optional `Model | None` slot (`transition_in`, `music_bed`):
+            # Pydantic emits it as an `anyOf` with a `$ref` to a buried
+            # `$defs/Model`. Inline a self-contained closed object (titles
+            # dropped, descriptions kept) so the field needs no external `$defs`
+            # -- the same self-containment the op union relies on.
+            inline = inline_model.model_json_schema()
+            inline.pop("title", None)
+            inline.pop("$defs", None)
+            for sub in inline.get("properties", {}).values():
                 sub.pop("title", None)
-            prop = _field(SegmentConfig, "transition_in")
-            prop["anyOf"] = [ts, {"type": "null"}]
-            return prop
-
-        def _music_bed_field() -> dict[str, Any]:
-            # `music_bed` is `MusicBed | None`; like `transition_in`, inline a
-            # self-contained closed object so the field needs no external `$defs`.
-            mb = MusicBed.model_json_schema()
-            mb.pop("title", None)
-            mb.pop("$defs", None)
-            for sub in mb.get("properties", {}).values():
-                sub.pop("title", None)
-            prop = _field(cls, "music_bed")
-            prop["anyOf"] = [mb, {"type": "null"}]
+            prop = _field(parent, field_name)
+            prop["anyOf"] = [inline, {"type": "null"}]
             return prop
 
         segment_schema: dict[str, Any] = {
@@ -926,7 +941,7 @@ class VideoEdit(BaseModel):
                 "start": _field(SegmentConfig, "start"),
                 "end": _field(SegmentConfig, "end"),
                 "operations": _array(SegmentConfig, "operations", op_schema),
-                "transition_in": _transition_field(),
+                "transition_in": _optional_model_field(TransitionSpec, SegmentConfig, "transition_in"),
             },
             "required": ["source", "start", "end"],
             "additionalProperties": False,
@@ -942,7 +957,7 @@ class VideoEdit(BaseModel):
                 "post_operations": _array(cls, "post_operations", op_schema),
                 "match_to_lowest_fps": _field(cls, "match_to_lowest_fps"),
                 "match_to_lowest_resolution": _field(cls, "match_to_lowest_resolution"),
-                "music_bed": _music_bed_field(),
+                "music_bed": _optional_model_field(MusicBed, cls, "music_bed"),
             },
             "required": ["segments"],
             "additionalProperties": False,
@@ -1950,6 +1965,28 @@ class VideoEdit(BaseModel):
             for f in owned_files:
                 f.unlink(missing_ok=True)
 
+        def make_ctx(decode_filters: tuple[str, ...] | None | object = _DECODE_FILTERS_DEFAULT) -> FilterCtx:
+            """A :class:`FilterCtx` snapshot of the current ``running`` state.
+
+            Captures the per-op pipeline geometry (dims/fps/frame-count) and the
+            segment's location/context every op compiles against. ``decode_filters``
+            is the decode-stage filter prefix ahead of this op; left unset it keeps
+            :class:`FilterCtx`'s own default (the op consumes no decode pass).
+            """
+            kwargs: dict[str, Any] = {
+                "width": running.width,
+                "height": running.height,
+                "fps": running.fps,
+                "frame_count": running.frame_count,
+                "context": seg_context or {},
+                "source_path": segment.source,
+                "start_second": segment.start,
+                "end_second": segment.end,
+            }
+            if decode_filters is not _DECODE_FILTERS_DEFAULT:
+                kwargs["decode_filters"] = decode_filters
+            return FilterCtx(**kwargs)
+
         effect_schedule: list[EffectScheduleEntry] = []
         post_vf_filters: list[str] = []
         af_filters: list[str] = []
@@ -2002,17 +2039,7 @@ class VideoEdit(BaseModel):
                         # process_frame. Either way plan order is preserved. A
                         # None compile falls through to the frame-effect path.
                         encode_stage_effect = bool(effect_schedule or post_vf_filters)
-                        ctx = FilterCtx(
-                            width=running.width,
-                            height=running.height,
-                            fps=running.fps,
-                            frame_count=running.frame_count,
-                            context=seg_context or {},
-                            source_path=segment.source,
-                            start_second=segment.start,
-                            end_second=segment.end,
-                            decode_filters=None if encode_stage_effect else tuple(vf_filters),
-                        )
+                        ctx = make_ctx(decode_filters=None if encode_stage_effect else tuple(vf_filters))
                         filter_expr = op.to_ffmpeg_filter(ctx)
                         owned_files.extend(ctx.owned_files)
                         if filter_expr is not None:
@@ -2043,16 +2070,7 @@ class VideoEdit(BaseModel):
                     # at the decode stage (one after an encode-stage filter is
                     # rejected above), so its audio twin joins af_filters; its
                     # window resolves against this position's running metadata.
-                    effect_ctx = FilterCtx(
-                        width=running.width,
-                        height=running.height,
-                        fps=running.fps,
-                        frame_count=running.frame_count,
-                        context=seg_context or {},
-                        source_path=segment.source,
-                        start_second=segment.start,
-                        end_second=segment.end,
-                    )
+                    effect_ctx = make_ctx()
                     compile_audio_twin(op, effect_ctx, encode_stage=False)
                     continue
                 if op.requires and (duration_changed or not op.streamable):
@@ -2084,17 +2102,7 @@ class VideoEdit(BaseModel):
                     # compile time -- not streamable (rejected as UNSTREAMABLE).
                     abandon()
                     return None
-                ctx = FilterCtx(
-                    width=running.width,
-                    height=running.height,
-                    fps=running.fps,
-                    frame_count=running.frame_count,
-                    context=seg_context or {},
-                    source_path=segment.source,
-                    start_second=segment.start,
-                    end_second=segment.end,
-                    decode_filters=None if encode_stage else tuple(vf_filters),
-                )
+                ctx = make_ctx(decode_filters=None if encode_stage else tuple(vf_filters))
                 filter_expr = op.to_ffmpeg_filter(ctx)
                 owned_files.extend(ctx.owned_files)
                 if filter_expr is None:
@@ -2103,8 +2111,8 @@ class VideoEdit(BaseModel):
                 if encode_stage:
                     # A transform following frame effects joins the encode
                     # chain (FrameEncoder -vf), which runs after every
-                    # process_frame -- plan order is preserved without the
-                    # whole-plan fallback this shape used to force.
+                    # process_frame -- plan order is preserved because this
+                    # shape places the filter without the whole-plan fallback.
                     pipe_meta = pipe_meta or running
                     post_vf_filters.append(filter_expr)
                 else:
@@ -2174,24 +2182,15 @@ class VideoEdit(BaseModel):
             limit_frames = min(left_frames, right_frames)
             if overlap >= limit_frames:
                 limit_seconds = round(limit_frames / fps, 4) if fps else 0.0
-                message = (
-                    f"Segment {i}: transition_in overlaps {overlap} frames ({spec.duration}s) but must overlap "
-                    f"fewer frames than the shorter adjacent segment ({limit_frames} frames, {limit_seconds}s); "
-                    "repair the plan or shorten the transition."
-                )
-                raise PlanValidationError(
-                    message,
-                    [
-                        PlanError(
-                            code=PlanErrorCode.TRANSITION_TOO_LONG,
-                            location=f"segments[{i}]",
-                            field="transition_in.duration",
-                            value=spec.duration,
-                            limit=limit_seconds,
-                            predicted_duration=limit_seconds,
-                        )
-                    ],
+                message, err = _transition_too_long_error(
+                    i,
+                    spec,
+                    overlap,
+                    limit_frames,
+                    limit_seconds,
+                    "repair the plan or shorten the transition.",
                 )
+                raise PlanValidationError(message, [err])
 
 
 def _plan_output_frames(plan: StreamingSegmentPlan) -> tuple[int, float]:
@@ -2210,12 +2209,6 @@ def _plan_output_frames(plan: StreamingSegmentPlan) -> tuple[int, float]:
     return frames, fps
 
 
-def _plan_output_seconds(plan: StreamingSegmentPlan) -> float:
-    """A compiled segment plan's predicted post-op duration in seconds."""
-    frames, fps = _plan_output_frames(plan)
-    return frames / fps if fps else 0.0
-
-
 def _effect_frame_range(op: Effect, fps: float, total_frames: int) -> tuple[int, int]:
     """Resolve an effect's ``window`` to a ``(start_frame, end_frame)`` pair."""
     if op.window is None: