collapsarr 0.1.3__py3-none-any.whl

collapsarr/downmix/apply.py

@@ -0,0 +1,241 @@
+"""Validate a produced remux temp file and atomically swap it in (COL-18).
+
+:func:`~collapsarr.downmix.remux.run_remux` (COL-17) writes a *temp* file —
+in the same directory as the original, containing every original stream plus
+the newly-encoded downmix track(s) — but deliberately stops short of touching
+the original. This module is that final, safety-critical step: it validates
+the temp file against the original and, **only** if it passes, atomically
+renames it over the original.
+
+This is the app's core data-safety guarantee. Collapsarr mutates users' real,
+often-irreplaceable media libraries in place, so the contract here is
+absolute: **on any outcome other than a fully-validated success, the original
+file is left byte-for-byte untouched and the temp file is discarded.** No
+long-term backup of the original is ever made — the operation is strictly
+additive and the temp/rename dance *is* the safety window (see
+``docs/plans/2026-07-20-collapsarr-v1-design.md``, "Remux safety").
+
+Two checks gate the swap, both via :func:`~collapsarr.downmix.probe.probe_media_summary`
+(real ffprobe, same injectable-runner seam as the rest of the engine):
+
+1. **Duration** — the temp's container duration must match the original's
+   within :data:`DEFAULT_DURATION_TOLERANCE_SECONDS`. Re-encoding one audio
+   track and remuxing legitimately shifts the container duration by a few
+   codec-frame boundaries (tens of milliseconds — an observed AC3 remux of a
+   0.428s source came out 0.512s, ~84ms longer). The tolerance sits an order
+   of magnitude above that yet far below any real truncation/corruption,
+   which manifests as seconds-to-minutes. Erring *tight* is the safe
+   direction: a false reject merely wastes the remux and leaves the original
+   intact, whereas a false accept could swap in a corrupt file — so the
+   tolerance is chosen to comfortably admit legitimate remuxes and nothing
+   looser.
+2. **Stream count** — the temp must have exactly ``original stream count +
+   added_track_count`` streams. All streams are counted (video/audio/
+   subtitle), so a remux that silently dropped or duplicated a stream is
+   caught even though its duration would look fine.
+
+The swap itself uses :meth:`Path.rename` (``rename(2)``), which on POSIX
+atomically replaces the destination in a single syscall. Collapsarr's target
+deployment is POSIX (Linux/macOS/Docker, the *arr ecosystem), and COL-17
+guarantees the temp file lives in the original's own directory — hence on the
+same filesystem — so the rename never degrades to a non-atomic cross-device
+copy. There is therefore never a moment where the original is partially
+written or missing.
+
+Mirrors the testing pattern of :mod:`collapsarr.downmix.remux`: real committed
+fixture media under ``tests/fixtures/downmix/`` driven through the actual
+ffmpeg/ffprobe binaries for the success path and each real failure path
+(a genuinely truncated temp for duration, a genuinely stream-dropped temp for
+stream count), plus an injectable ``runner`` for fast, binary-free unit tests.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from collapsarr.downmix.probe import (
+    MediaSummary,
+    probe_media_summary,
+)
+from collapsarr.downmix.remux import RemuxResult
+
+_DEFAULT_FFPROBE_PATH = "ffprobe"
+_DEFAULT_TIMEOUT = 30.0
+
+# See the module docstring for the full rationale. Sub-second, comfortably
+# above the tens-of-ms shift a legitimate re-encode/remux introduces, far
+# below any real truncation. Baked into the safety contract; override per-call
+# only with good reason (and never loosen it lightly).
+DEFAULT_DURATION_TOLERANCE_SECONDS = 0.5
+
+_Runner = Callable[[Sequence[str], float], "subprocess.CompletedProcess[str]"]
+
+
+class ApplyFailureReason(Enum):
+    """Why an :func:`apply_remux_result` validation refused to swap."""
+
+    DURATION_MISMATCH = "duration_mismatch"
+    STREAM_COUNT_MISMATCH = "stream_count_mismatch"
+
+
+@dataclass(frozen=True, slots=True)
+class ApplyResult:
+    """Outcome of an :func:`apply_remux_result` attempt, shaped for job history.
+
+    On success ``applied_path`` is the original path (now holding the remuxed
+    file) and ``failure_reason`` is ``None``. On a validation failure
+    ``applied_path`` is ``None``, ``failure_reason`` names the specific check
+    that failed, and — guaranteed — the original file is unchanged and the
+    temp file has been deleted. ``detail`` is always a human-readable summary
+    (the concrete durations/counts involved) suitable for logging.
+    """
+
+    success: bool
+    applied_path: Path | None
+    failure_reason: ApplyFailureReason | None
+    detail: str
+
+
+def apply_remux_result(
+    original_path: str | Path,
+    remux_result: RemuxResult,
+    added_track_count: int,
+    *,
+    duration_tolerance_seconds: float = DEFAULT_DURATION_TOLERANCE_SECONDS,
+    ffprobe_path: str = _DEFAULT_FFPROBE_PATH,
+    timeout: float = _DEFAULT_TIMEOUT,
+    runner: _Runner | None = None,
+) -> ApplyResult:
+    """Validate ``remux_result``'s temp file and atomically swap it over the original.
+
+    Re-probes both the (still-untouched) original and the temp file, then:
+
+    - if the temp's container duration is within
+      ``duration_tolerance_seconds`` of the original's **and** its total
+      stream count equals the original's plus ``added_track_count``, renames
+      the temp over the original (atomic on POSIX / same filesystem) and
+      returns ``ApplyResult(success=True, ...)``;
+    - otherwise deletes the temp file, leaves the original byte-for-byte
+      untouched, and returns ``ApplyResult(success=False, ...)`` naming the
+      failing check.
+
+    The original is never modified on any path except the successful atomic
+    rename, and no backup copy of it is ever created — the temp file is the
+    only extra artifact, and it is gone by the time this returns.
+
+    ``added_track_count`` is the number of new downmix tracks the remux was
+    asked to add (i.e. ``len(qualifying_targets)``); the original's own stream
+    count is measured fresh here rather than trusted from the caller.
+
+    Raises:
+        ValueError: ``remux_result`` did not succeed (so there is no temp
+            file to apply), or ``added_track_count`` is negative — both are
+            caller/programmer errors, mirroring
+            :func:`~collapsarr.downmix.remux.run_remux`'s use of ``ValueError``
+            for bad inputs.
+        collapsarr.downmix.probe.FfprobeError: either file could not be
+            probed (missing binary, timeout, non-zero exit, unparseable/
+            incomplete output). The temp file is deleted and the original left
+            untouched before the error propagates, so no orphan is left and no
+            unvalidated swap ever happens.
+    """
+    if not remux_result.success or remux_result.temp_file_path is None:
+        raise ValueError(
+            "apply_remux_result requires a successful RemuxResult with a temp file"
+        )
+    if added_track_count < 0:
+        raise ValueError(f"added_track_count must not be negative, got {added_track_count}")
+
+    original = Path(original_path)
+    temp = remux_result.temp_file_path
+
+    # Any inability to *validate* must never green-light a swap. Probe errors
+    # therefore clean up the temp (no orphan, matching run_remux's contract)
+    # and propagate, leaving the original untouched.
+    try:
+        original_summary = probe_media_summary(
+            original, ffprobe_path=ffprobe_path, timeout=timeout, runner=runner
+        )
+        temp_summary = probe_media_summary(
+            temp, ffprobe_path=ffprobe_path, timeout=timeout, runner=runner
+        )
+    except BaseException:
+        _remove_if_exists(temp)
+        raise
+
+    duration_delta = abs(temp_summary.duration_seconds - original_summary.duration_seconds)
+    if duration_delta > duration_tolerance_seconds:
+        _remove_if_exists(temp)
+        return ApplyResult(
+            success=False,
+            applied_path=None,
+            failure_reason=ApplyFailureReason.DURATION_MISMATCH,
+            detail=_duration_mismatch_detail(
+                original_summary, temp_summary, duration_delta, duration_tolerance_seconds
+            ),
+        )
+
+    expected_stream_count = original_summary.stream_count + added_track_count
+    if temp_summary.stream_count != expected_stream_count:
+        _remove_if_exists(temp)
+        return ApplyResult(
+            success=False,
+            applied_path=None,
+            failure_reason=ApplyFailureReason.STREAM_COUNT_MISMATCH,
+            detail=_stream_count_mismatch_detail(
+                original_summary, temp_summary, added_track_count, expected_stream_count
+            ),
+        )
+
+    # Both checks passed: atomically replace the original. On POSIX / same
+    # filesystem this is a single rename(2) — no partial-write window.
+    temp.rename(original)
+    return ApplyResult(
+        success=True,
+        applied_path=original,
+        failure_reason=None,
+        detail=(
+            f"applied remux over {str(original)!r}: "
+            f"{original_summary.stream_count}->{temp_summary.stream_count} streams, "
+            f"duration {original_summary.duration_seconds:.3f}s->"
+            f"{temp_summary.duration_seconds:.3f}s "
+            f"(delta {duration_delta:.3f}s within {duration_tolerance_seconds:.3f}s)"
+        ),
+    )
+
+
+def _duration_mismatch_detail(
+    original: MediaSummary,
+    temp: MediaSummary,
+    delta: float,
+    tolerance: float,
+) -> str:
+    return (
+        f"duration mismatch: original {original.duration_seconds:.3f}s vs "
+        f"remux {temp.duration_seconds:.3f}s (delta {delta:.3f}s exceeds "
+        f"tolerance {tolerance:.3f}s); original left untouched, temp discarded"
+    )
+
+
+def _stream_count_mismatch_detail(
+    original: MediaSummary,
+    temp: MediaSummary,
+    added_track_count: int,
+    expected: int,
+) -> str:
+    return (
+        f"stream-count mismatch: remux has {temp.stream_count} streams, expected "
+        f"{expected} (original {original.stream_count} + {added_track_count} added); "
+        f"original left untouched, temp discarded"
+    )
+
+
+def _remove_if_exists(path: Path) -> None:
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass

collapsarr/downmix/pipeline.py

@@ -0,0 +1,235 @@
+"""End-to-end single-file downmix pipeline (COL-19).
+
+The demoable tracer bullet for the Downmix Engine: wires the four prior
+modules — :mod:`~collapsarr.downmix.probe` (COL-15),
+:mod:`~collapsarr.downmix.targets` (COL-16),
+:mod:`~collapsarr.downmix.remux` (COL-17), and
+:mod:`~collapsarr.downmix.apply` (COL-18) — into one callable pipeline for a
+single file: probe -> detect qualifying targets -> (no-op if none) -> remux
+-> validate/apply.
+
+Enabled targets, the language allow-list, and codec/bitrate overrides come
+from a caller-supplied :class:`~collapsarr.downmix.targets.DownmixSettings`.
+There is no persisted Settings model yet (that's future work); this pipeline
+simply takes one as an argument, the same way :func:`detect_qualifying_targets`
+and :func:`run_remux` already do.
+
+:func:`run_downmix_pipeline` never raises for a *runtime* failure at any
+stage (ffprobe/ffmpeg missing, non-zero exit, timeout, or a failed
+validate-and-apply) — every outcome, success or failure, comes back as one
+:class:`PipelineResult` shaped for job history: which stage produced it
+(:class:`PipelineOutcome`), the tracks added on success, and — on failure —
+the underlying :class:`~collapsarr.downmix.remux.RemuxResult` or
+:class:`~collapsarr.downmix.apply.ApplyResult` (whichever stage failed),
+reusing their exit-code/stderr/failure-reason fields rather than
+re-inventing them. A file with no qualifying targets is reported as a
+distinct, non-error outcome (:attr:`PipelineOutcome.NOTHING_TO_DO`), never
+as a failure.
+
+Not yet wired into a job queue — that's COL-20's concern. This module is the
+callable, single-file seam a job runner will later invoke per file.
+
+Tests mirror the rest of the engine: real committed fixture media under
+``tests/fixtures/downmix/`` driven through the actual ffmpeg/ffprobe binaries
+end-to-end for the success, nothing-to-do, and real-ffmpeg-failure paths
+(skipped when ffmpeg/ffprobe aren't installed), plus an injectable ``runner``
+for fast, environment-independent unit tests of the stage-by-stage control
+flow.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from collapsarr.downmix.apply import (
+    DEFAULT_DURATION_TOLERANCE_SECONDS,
+    ApplyResult,
+    apply_remux_result,
+)
+from collapsarr.downmix.probe import FfprobeError, probe_audio_streams
+from collapsarr.downmix.remux import RemuxResult, run_remux
+from collapsarr.downmix.targets import DownmixSettings, QualifyingTarget, detect_qualifying_targets
+
+_DEFAULT_FFPROBE_PATH = "ffprobe"
+_DEFAULT_FFMPEG_PATH = "ffmpeg"
+_DEFAULT_PROBE_TIMEOUT = 30.0
+_DEFAULT_REMUX_TIMEOUT = 3600.0
+
+_Runner = Callable[[Sequence[str], float], "subprocess.CompletedProcess[str]"]
+
+
+class PipelineOutcome(Enum):
+    """Which stage of the pipeline a :class:`PipelineResult` came from."""
+
+    SUCCESS = "success"
+    NOTHING_TO_DO = "nothing_to_do"
+    PROBE_FAILED = "probe_failed"
+    REMUX_FAILED = "remux_failed"
+    APPLY_FAILED = "apply_failed"
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineResult:
+    """Structured outcome of one end-to-end :func:`run_downmix_pipeline` run.
+
+    Shaped for job history. ``success`` is ``True`` only for
+    :attr:`PipelineOutcome.SUCCESS` — a no-op (nothing to do) is reported
+    separately via ``outcome`` rather than folded into either success or
+    failure, since it is neither: nothing was attempted, nothing failed.
+
+    ``tracks_added`` is populated (non-empty) only on success — the
+    ``(language, target)`` pairs that were added.
+
+    ``remux_result``/``apply_result`` carry the raw result from whichever
+    stage ran, so a caller gets the ffmpeg exit code/stderr
+    (:class:`~collapsarr.downmix.remux.RemuxResult`) or the validation
+    failure reason/detail
+    (:class:`~collapsarr.downmix.apply.ApplyResult`) straight from the
+    source rather than this module re-deriving them. Both are ``None`` when
+    the pipeline never reached that stage (e.g. a probe failure, or nothing
+    to do).
+
+    ``detail`` is always a human-readable one-line summary suitable for
+    logging, regardless of outcome.
+    """
+
+    outcome: PipelineOutcome
+    success: bool
+    detail: str
+    tracks_added: tuple[QualifyingTarget, ...] = ()
+    remux_result: RemuxResult | None = None
+    apply_result: ApplyResult | None = None
+
+
+def run_downmix_pipeline(
+    file_path: str | Path,
+    settings: DownmixSettings,
+    *,
+    ffprobe_path: str = _DEFAULT_FFPROBE_PATH,
+    ffmpeg_path: str = _DEFAULT_FFMPEG_PATH,
+    probe_timeout: float = _DEFAULT_PROBE_TIMEOUT,
+    remux_timeout: float = _DEFAULT_REMUX_TIMEOUT,
+    duration_tolerance_seconds: float = DEFAULT_DURATION_TOLERANCE_SECONDS,
+    runner: _Runner | None = None,
+) -> PipelineResult:
+    """Run the full downmix pipeline for a single file, end to end.
+
+    In order: :func:`~collapsarr.downmix.probe.probe_audio_streams`,
+    :func:`~collapsarr.downmix.targets.detect_qualifying_targets`,
+    :func:`~collapsarr.downmix.remux.run_remux`, and
+    :func:`~collapsarr.downmix.apply.apply_remux_result` — stopping early
+    (and reporting why) as soon as a stage has nothing left to hand the
+    next one.
+
+    ``runner`` overrides how every subprocess call across all three stages
+    is invoked (signature ``(command, timeout) -> subprocess.CompletedProcess``,
+    the same seam :func:`~collapsarr.downmix.probe.probe_audio_streams`,
+    :func:`~collapsarr.downmix.remux.run_remux`, and
+    :func:`~collapsarr.downmix.apply.apply_remux_result` each already
+    accept); it defaults to real subprocesses and exists so tests can drive
+    the whole pipeline's control flow without the ``ffmpeg``/``ffprobe``
+    binaries installed.
+
+    Never raises for a runtime failure at any stage:
+
+    - a probing failure (missing binary, non-zero exit, unparseable output)
+      is reported as :attr:`PipelineOutcome.PROBE_FAILED`;
+    - no qualifying targets is reported as
+      :attr:`PipelineOutcome.NOTHING_TO_DO` (``success=True`` — this is not
+      an error);
+    - an ffmpeg remux failure is reported as
+      :attr:`PipelineOutcome.REMUX_FAILED`, carrying the
+      :class:`~collapsarr.downmix.remux.RemuxResult` (exit code + stderr);
+      the original file is untouched (:func:`run_remux`'s own guarantee);
+    - a failed validate-and-apply (duration/stream-count mismatch, or the
+      temp/original becoming unprobeable after the remux) is reported as
+      :attr:`PipelineOutcome.APPLY_FAILED`, carrying the
+      :class:`~collapsarr.downmix.apply.ApplyResult` when one was produced;
+      the original file is untouched
+      (:func:`~collapsarr.downmix.apply.apply_remux_result`'s own
+      guarantee).
+
+    On success, the original file has been atomically replaced by the
+    remuxed version (all original streams intact, plus the newly added
+    downmix track(s)), and ``tracks_added`` lists what was added.
+    """
+    path = Path(file_path)
+
+    try:
+        streams = probe_audio_streams(
+            path, ffprobe_path=ffprobe_path, timeout=probe_timeout, runner=runner
+        )
+    except FfprobeError as exc:
+        return PipelineResult(
+            outcome=PipelineOutcome.PROBE_FAILED,
+            success=False,
+            detail=f"failed to probe audio streams of {str(path)!r}: {exc}",
+        )
+
+    targets = detect_qualifying_targets(streams, settings)
+    if not targets:
+        return PipelineResult(
+            outcome=PipelineOutcome.NOTHING_TO_DO,
+            success=True,
+            detail=f"no qualifying downmix targets for {str(path)!r}; nothing to do",
+        )
+
+    remux_result = run_remux(
+        path,
+        streams,
+        targets,
+        settings,
+        ffmpeg_path=ffmpeg_path,
+        timeout=remux_timeout,
+        runner=runner,
+    )
+    if not remux_result.success:
+        return PipelineResult(
+            outcome=PipelineOutcome.REMUX_FAILED,
+            success=False,
+            detail=(
+                f"ffmpeg remux failed for {str(path)!r} "
+                f"(exit code {remux_result.returncode}): {remux_result.stderr.strip()}"
+            ),
+            remux_result=remux_result,
+        )
+
+    try:
+        apply_result = apply_remux_result(
+            path,
+            remux_result,
+            added_track_count=len(targets),
+            duration_tolerance_seconds=duration_tolerance_seconds,
+            ffprobe_path=ffprobe_path,
+            timeout=probe_timeout,
+            runner=runner,
+        )
+    except FfprobeError as exc:
+        return PipelineResult(
+            outcome=PipelineOutcome.APPLY_FAILED,
+            success=False,
+            detail=f"failed to validate remux result for {str(path)!r}: {exc}",
+            remux_result=remux_result,
+        )
+
+    if not apply_result.success:
+        return PipelineResult(
+            outcome=PipelineOutcome.APPLY_FAILED,
+            success=False,
+            detail=apply_result.detail,
+            remux_result=remux_result,
+            apply_result=apply_result,
+        )
+
+    return PipelineResult(
+        outcome=PipelineOutcome.SUCCESS,
+        success=True,
+        detail=apply_result.detail,
+        tracks_added=tuple(targets),
+        remux_result=remux_result,
+        apply_result=apply_result,
+    )