videopython 0.43.1__tar.gz → 0.44.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.43.1
+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/
@@ -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.1}/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.1}/pyproject.toml

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

{videopython-0.43.1 → 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.43.1 → 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.43.1 → 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.43.1 → videopython-0.44.1}/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.1}/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.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.43.1 → 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.43.1 → 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.video import FrameIterator, Video, VideoMetadata
-from videopython.editing._ass import escape_filter_value
+from videopython.base._ffmpeg import escape_filter_value
+from videopython.base.video import FrameIterator, VideoMetadata
 from videopython.editing.operation import FilterCtx, OpCategory, Operation
 
 logger = logging.getLogger(__name__)
@@ -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.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.43.1 → videopython-0.44.1}/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.1}/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.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.43.1 → 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.43.1 → 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.43.1 → 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.43.1 → videopython-0.44.1}/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
@@ -33,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]],
     *,
@@ -75,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):
@@ -122,7 +142,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 +167,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 +198,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``