@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-assemble/scripts/adoption/frozen_audio.py

@@ -0,0 +1,187 @@
+"""Probe and verify an adopted AAC stream without decoding or rewriting it."""
+
+import json
+from fractions import Fraction
+from pathlib import Path
+
+from lib import run_cmd
+
+
+def _fraction(value):
+    return Fraction(str(value))
+
+
+def _packet_span(audio):
+    """The stream duration proved by its packets: last packet end minus first packet start."""
+    packets = audio["packets"]
+    if not packets or packets[0]["pts"] is None or packets[-1]["pts"] is None \
+            or packets[-1]["duration"] is None:
+        return None
+    return Fraction(packets[-1]["pts"]) + Fraction(packets[-1]["duration"]) \
+        - Fraction(packets[0]["pts"])
+
+
+def _rational_ticks(value, time_base):
+    if value in (None, "N/A"):
+        return None
+    value = Fraction(int(value)) * Fraction(time_base)
+    return f"{value.numerator}/{value.denominator}"
+
+
+def _probe(path, *args):
+    result = run_cmd([
+        "ffprobe", "-v", "error", *args, "-of", "json", str(path),
+    ])
+    if result.returncode != 0:
+        raise RuntimeError(f"无法探测媒体 {path}: {result.stderr.strip()}")
+    try:
+        return json.loads(result.stdout)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeError(f"ffprobe 返回无效 JSON: {path}") from exc
+
+
+def probe_audio_packets(path, audio_stream_index):
+    """Return packet sizes and rational timestamps for one audio stream.
+
+    ``audio_stream_index`` is the zero-based audio-stream ordinal accepted by
+    ffmpeg's ``0:a:N`` selector, not the file-wide absolute stream index.
+    """
+    payload = _probe(
+        path,
+        "-select_streams", f"a:{audio_stream_index}",
+        "-show_streams", "-show_packets",
+        "-show_entries",
+        "stream=index,codec_name,time_base,start_pts,start_time,duration_ts,duration,sample_rate,channels,"
+        "channel_layout:packet=pts,dts,duration,size,side_data_list",
+    )
+    streams = payload.get("streams", [])
+    if len(streams) != 1:
+        raise RuntimeError(f"找不到音频流 a:{audio_stream_index}: {Path(path)}")
+    stream = streams[0]
+    time_base = stream.get("time_base")
+    if not time_base:
+        raise RuntimeError(f"音频流 a:{audio_stream_index} 缺少 time_base")
+    codec = stream.get("codec_name")
+    sample_rate = int(stream["sample_rate"]) if stream.get("sample_rate") else None
+    channels = int(stream["channels"]) if stream.get("channels") else None
+    channel_layout = stream.get("channel_layout")
+    decoder = {
+        "codec": codec,
+        "sample_rate": sample_rate,
+        "channels": channels,
+        "channel_layout": channel_layout,
+    }
+    packets = []
+    for packet in payload.get("packets", []):
+        if packet.get("size") is None:
+            raise RuntimeError(f"音频流 a:{audio_stream_index} 的 packet 缺少 size")
+        packets.append({
+            "size": int(packet["size"]),
+            "pts": _rational_ticks(packet.get("pts"), time_base),
+            "dts": _rational_ticks(packet.get("dts"), time_base),
+            "duration": _rational_ticks(packet.get("duration"), time_base),
+            "side_data_list": packet.get("side_data_list", []),
+        })
+    return {
+        "selected_audio_stream_index": audio_stream_index,
+        "absolute_stream_index": int(stream["index"]),
+        "codec": codec,
+        "time_base": time_base,
+        "start_time": stream.get("start_time"),
+        "duration": stream.get("duration"),
+        "sample_rate": sample_rate,
+        "channels": channels,
+        "channel_layout": channel_layout,
+        "decoder": decoder,
+        "packet_count": len(packets),
+        "payload_bytes": sum(packet["size"] for packet in packets),
+        "packets": packets,
+    }
+
+
+def _picture_interval(path):
+    payload = _probe(
+        path,
+        "-select_streams", "v:0", "-show_streams",
+        "-show_entries", "stream=time_base,start_pts,start_time,duration_ts,duration,avg_frame_rate",
+    )
+    streams = payload.get("streams", [])
+    if len(streams) != 1:
+        raise RuntimeError(f"找不到主画面流 v:0: {Path(path)}")
+    stream = streams[0]
+    start = _fraction(stream.get("start_time", "0"))
+    if stream.get("duration") in (None, "N/A"):
+        raise RuntimeError("主画面流缺少可验证时长")
+    duration = _fraction(stream["duration"])
+    frame_rate = Fraction(stream.get("avg_frame_rate", "0/1"))
+    frame = Fraction(1, 1000) if frame_rate <= 0 else 1 / frame_rate
+    return start, duration, frame
+
+
+def validate_adopted_source(path, audio_stream_index):
+    """Fail unless the selected input is copyable AAC spanning the picture interval."""
+    audio = probe_audio_packets(path, audio_stream_index)
+    if audio["codec"] != "aac":
+        raise RuntimeError(
+            f"adopted-packet-copy 当前只支持 MP4 AAC stream-copy；"
+            f"a:{audio_stream_index} 是 {audio['codec'] or 'unknown'}"
+        )
+    if not audio["packets"]:
+        raise RuntimeError(f"音频流 a:{audio_stream_index} 没有 packet，不能采用")
+    picture_start, picture_duration, frame_tolerance = _picture_interval(path)
+    if audio["start_time"] in (None, "N/A") or audio["duration"] in (None, "N/A"):
+        raise RuntimeError(f"音频流 a:{audio_stream_index} 缺少可验证起止时间")
+    audio_start = _fraction(audio["start_time"])
+    audio_duration = _fraction(audio["duration"])
+    packet_durations = [
+        _fraction(packet["duration"])
+        for packet in audio["packets"] if packet["duration"] is not None
+    ]
+    tolerance = max([frame_tolerance, Fraction(1, 1000), *packet_durations])
+    if (
+        abs(audio_start - picture_start) > tolerance
+        or abs(audio_duration - picture_duration) > tolerance
+    ):
+        raise RuntimeError(
+            "采用音频与画面时长/起点不兼容: "
+            f"picture={float(picture_start):.6f}+{float(picture_duration):.6f}s, "
+            f"audio={float(audio_start):.6f}+{float(audio_duration):.6f}s"
+        )
+    return audio
+
+
+def verify_adopted_audio(input_path, output_path, input_stream_index, output_stream_index=0):
+    """Probe the rendered output and check packet count, payload bytes, duration and timing."""
+    expected = probe_audio_packets(input_path, input_stream_index)
+    actual = probe_audio_packets(output_path, output_stream_index)
+    if expected["decoder"] != actual["decoder"]:
+        raise RuntimeError("采用音频 decoder 参数已改变")
+    if expected["packet_count"] != actual["packet_count"]:
+        raise RuntimeError(
+            f"采用音频 packet count 已改变: {expected['packet_count']} -> {actual['packet_count']}"
+        )
+    if expected["payload_bytes"] != actual["payload_bytes"]:
+        raise RuntimeError("采用音频 packet payload 总字节数不一致")
+    if _packet_span(expected) != _packet_span(actual):
+        raise RuntimeError("采用音频流时长已改变")
+    expected_packet_core = [
+        {key: value for key, value in packet.items() if key != "side_data_list"}
+        for packet in expected["packets"]
+    ]
+    actual_packet_core = [
+        {key: value for key, value in packet.items() if key != "side_data_list"}
+        for packet in actual["packets"]
+    ]
+    if expected_packet_core != actual_packet_core:
+        raise RuntimeError("采用音频 packet PTS/DTS/duration/size 不一致")
+    if [packet["side_data_list"] for packet in expected["packets"]] != [
+        packet["side_data_list"] for packet in actual["packets"]
+    ]:
+        raise RuntimeError("采用音频 packet side data 已改变")
+    return {
+        "verified": True,
+        "selected_audio_stream_index": input_stream_index,
+        "output_audio_stream_index": output_stream_index,
+        "input": expected,
+        "output": actual,
+    }

package/lib/video-recap/skills/video-assemble/scripts/adoption/narration_binding.py

@@ -0,0 +1,323 @@
+"""Record which narration inputs an assembly consumed: adoption, snapshot, placement, output."""
+
+import json
+import math
+from pathlib import Path
+import shutil
+import subprocess
+
+from adoption.frozen_audio import probe_audio_packets
+from adoption.strict_inputs import (
+    read_json_bytes, require_fields, require_local_path, without_digests, write_json_atomic,
+)
+
+
+ARTIFACT = "narration_input_binding"
+FILENAME = "narration_input_binding.json"
+IDENTITY_STATUSES = frozenset({"UNADOPTED", "BOUND_TO_ADOPTION"})
+# The conservative default an adoption gets when it declares nothing stronger.
+TEMPO_POLICY = {
+    "global_atempo": 1.0,
+    "bounded_segment_fit": False,
+    "segment_tempo_max": 1.0,
+    "cumulative_tempo_max": 1.0,
+    "cumulative_tempo_hard_max": 1.0,
+}
+TEMPO_NUMBERS = ("global_atempo", "segment_tempo_max", "cumulative_tempo_max",
+                 "cumulative_tempo_hard_max")
+
+
+def validate_tempo_policy(value):
+    """Accept any adoption-declared tempo policy whose shape and bounds hold.
+
+    The adoption, not this module, decides how fast its own narration may be
+    played; the module only refuses policies that are malformed or that would
+    let a segment exceed the cumulative hard ceiling the policy itself declares.
+    """
+    require_fields(value, sorted(TEMPO_POLICY), "tempo_policy")
+    policy = {}
+    for key in TEMPO_NUMBERS:
+        number = value[key]
+        if type(number) not in (int, float) or not math.isfinite(number):
+            raise ValueError(f"tempo_policy {key} must be a finite number")
+        policy[key] = float(number)
+    if type(value["bounded_segment_fit"]) is not bool:
+        raise ValueError("tempo_policy bounded_segment_fit must be a boolean")
+    policy["bounded_segment_fit"] = value["bounded_segment_fit"]
+    if policy["cumulative_tempo_max"] < 1.0:
+        raise ValueError("tempo_policy cumulative_tempo_max must be at least 1.0")
+    if policy["cumulative_tempo_hard_max"] < policy["cumulative_tempo_max"]:
+        raise ValueError("tempo_policy cumulative_tempo_hard_max must not be below "
+                         "cumulative_tempo_max")
+    if policy["segment_tempo_max"] < 1.0:
+        raise ValueError("tempo_policy segment_tempo_max must be at least 1.0")
+    if not 0 < policy["global_atempo"] <= policy["cumulative_tempo_hard_max"]:
+        raise ValueError("tempo_policy global_atempo must be positive and within "
+                         "cumulative_tempo_hard_max")
+    return policy
+
+
+def load_adoption(path, *, tts_meta_path, tts_segments):
+    """Load a strict v1 adoption and check it against the current tts_meta segments."""
+    if tts_meta_path is None:
+        raise ValueError("narration adoption requires explicit tts_meta_path")
+    adoption_path, _, adoption = read_json_bytes(path, "narration adoption")
+    adoption = without_digests(adoption, "narration adoption")
+    require_fields(adoption, ["artifact", "schema_version", "segments", "tempo_policy"],
+                   "narration adoption")
+    if adoption["artifact"] != "narration_adoption" or type(adoption["schema_version"]) is not int \
+            or adoption["schema_version"] != 1:
+        raise ValueError("unsupported narration_adoption schema")
+    tts_meta_path, _, tts_meta = read_json_bytes(tts_meta_path, "tts_meta")
+    if not isinstance(tts_meta, dict) or not isinstance(tts_meta.get("segments"), list):
+        raise ValueError("tts_meta requires a segments list")
+    if tts_meta["segments"] != tts_segments:
+        raise ValueError("in-memory narration segments differ from bound tts_meta")
+    tempo_policy = validate_tempo_policy(adoption["tempo_policy"])
+    if not isinstance(adoption["segments"], list) or len(adoption["segments"]) != len(tts_segments):
+        raise ValueError("adoption segments must exactly cover tts_meta segments")
+    normalized_segments = []
+    for adopted, actual in zip(adoption["segments"], tts_segments):
+        adopted = without_digests(adopted, "adoption segment")
+        require_fields(adopted, ["index", "spoken_text", "requested_provider", "requested_voice"],
+                       "adoption segment")
+        if type(adopted["index"]) is not int or adopted["index"] != actual.get("index"):
+            raise ValueError("adoption segment index/order differs from tts_meta")
+        spoken = actual.get("spoken_text", actual.get("narration"))
+        if not isinstance(adopted["spoken_text"], str) or adopted["spoken_text"] != spoken:
+            raise ValueError("adoption spoken_text differs from tts_meta")
+        for key in ("requested_provider", "requested_voice"):
+            if not isinstance(adopted[key], str) or not adopted[key]:
+                raise ValueError(f"adoption {key} must be a non-empty string")
+        normalized_segments.append(dict(adopted))
+    return {
+        "path": str(adoption_path),
+        "tts_meta": {"path": str(tts_meta_path)},
+        "segments": normalized_segments, "tempo_policy": tempo_policy,
+    }
+
+
+def _copy_snapshot(source, destination):
+    """Copy seam kept small so tests can inject a post-preflight source mutation."""
+    shutil.copyfile(source, destination)
+
+
+def prepare_binding(tts_segments, work_dir, *, narration_adoption_path=None,
+                    tts_meta_path=None):
+    """Validate first, then snapshot the adopted narration inputs into work_dir."""
+    if not isinstance(tts_segments, list):
+        raise ValueError("tts_segments must be a list")
+    adoption = (
+        load_adoption(narration_adoption_path, tts_meta_path=tts_meta_path,
+                      tts_segments=tts_segments)
+        if narration_adoption_path is not None else None
+    )
+    if not adoption:
+        originals = [
+            {"index": segment["index"], "source": Path(segment["audio_path"]).resolve(),
+             "spoken_text": segment["spoken_text"]}
+            for segment in tts_segments
+        ]
+        return {
+            "identity_status": "UNADOPTED", "adoption": None, "tempo_policy": None,
+            "originals": originals, "active": False, "segments": [],
+        }
+    originals = []
+    seen_indices = set()
+    for position, segment in enumerate(tts_segments):
+        if not isinstance(segment, dict) or type(segment.get("index")) is not int:
+            raise ValueError("each narration segment requires an integer index")
+        if segment["index"] in seen_indices:
+            raise ValueError("narration segment indices must be unique")
+        seen_indices.add(segment["index"])
+        adopted = adoption["segments"][position]
+        source = require_local_path(segment["audio_path"], "narration audio")
+        originals.append({
+            "index": segment["index"], "source": source,
+            "spoken_text": segment["spoken_text"],
+            "requested_provider": adopted["requested_provider"],
+            "requested_voice": adopted["requested_voice"],
+        })
+    context = {
+        "identity_status": "BOUND_TO_ADOPTION", "adoption": adoption,
+        "tempo_policy": adoption["tempo_policy"],
+        "originals": originals, "active": True, "segments": [], "sealed": None,
+    }
+    snapshot_dir = Path(work_dir).resolve() / ".narration_input_snapshots"
+    snapshot_dir.mkdir(parents=True, exist_ok=False)
+    for position, (segment, original) in enumerate(zip(tts_segments, originals)):
+        suffix = original["source"].suffix or ".audio"
+        snapshot = snapshot_dir / f"segment_{position:04d}_{segment['index']}{suffix}"
+        _copy_snapshot(original["source"], snapshot)
+        segment["audio_path"] = str(snapshot)
+        segment["narration_input_original"] = {"path": str(original["source"])}
+        segment["narration_input_snapshot"] = {"path": str(snapshot)}
+        context["segments"].append({
+            "index": original["index"], "spoken_text": original["spoken_text"],
+            "requested_provider": original["requested_provider"],
+            "requested_voice": original["requested_voice"],
+            "original": dict(segment["narration_input_original"]),
+            "snapshot": dict(segment["narration_input_snapshot"]),
+        })
+    return context
+
+
+def _pcm(path):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_streams",
+         "-show_entries", "stream=codec_name,sample_fmt,sample_rate,channels,channel_layout",
+         "-of", "json", str(path)], capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode:
+        raise ValueError(f"audio probe failed: {result.stderr.strip()}")
+    streams = json.loads(result.stdout).get("streams", [])
+    if len(streams) != 1:
+        raise ValueError("expected exactly one audio stream")
+    stream = streams[0]
+    return {key: stream.get(key) for key in (
+        "codec_name", "sample_fmt", "sample_rate", "channels", "channel_layout"
+    )}
+
+
+def _asset(path, *, pcm=False):
+    path = require_local_path(path, "binding asset")
+    value = {"path": str(path)}
+    if pcm:
+        value["pcm"] = _pcm(path)
+    return value
+
+
+def seal_render_inputs(context, tts_segments, narration_wav):
+    """Record every derived audio file that the final FFmpeg command will consume."""
+    if not context.get("active"):
+        return None
+    by_index = {segment["index"]: segment for segment in tts_segments}
+    sealed_segments = []
+    for item in context["segments"]:
+        segment = by_index[item["index"]]
+        placed = segment.get("placed_audio_path")
+        if not placed:
+            raise RuntimeError("active narration binding has no complete placed audio")
+        conversion = segment.get("narration_conversion_path")
+        conversion_asset = (
+            {"applied": True, **_asset(conversion, pcm=True)}
+            if conversion else {"applied": False}
+        )
+        sealed_segments.append({
+            "index": item["index"],
+            "conversion": conversion_asset,
+            "placed": _asset(placed, pcm=True),
+        })
+    context["sealed"] = {
+        "segments": sealed_segments,
+        "narration_bus": _asset(narration_wav, pcm=True),
+    }
+    return context["sealed"]
+
+
+def _active_report(context, rendered_output, final_output):
+    if not context.get("sealed"):
+        raise RuntimeError("active narration inputs must be sealed before finalization")
+    sealed = {item["index"]: item for item in context["sealed"]["segments"]}
+    segments = []
+    for item in context["segments"]:
+        segments.append({
+            **item,
+            "original": _asset(item["original"]["path"], pcm=True),
+            "snapshot": _asset(item["snapshot"]["path"], pcm=True),
+            "conversion": sealed[item["index"]]["conversion"],
+            "placed": sealed[item["index"]]["placed"],
+        })
+    rendered_path = require_local_path(rendered_output, "rendered output")
+    final_audio = probe_audio_packets(rendered_path, 0)
+    return {
+        "artifact": ARTIFACT, "schema_version": 1, "status": "FINALIZED",
+        "identity_status": context["identity_status"], "adoption": context["adoption"],
+        "segments": segments, "narration_bus": context["sealed"]["narration_bus"],
+        "final_output": {
+            "path": str(Path(final_output).resolve()),
+            "audio_stream": {
+                "decoder": final_audio["decoder"], "packet_count": final_audio["packet_count"],
+                "payload_bytes": final_audio["payload_bytes"],
+                "start_time": final_audio["start_time"], "duration": final_audio["duration"],
+            },
+        },
+        "voice_authentication": "NOT_CHECKED", "direct_listening": "NOT_CHECKED",
+    }
+
+
+def finalize_binding(context, tts_segments, narration_wav, final_output, *, rendered_output=None):
+    """Write ``narration_input_binding.json`` beside ``narration_wav`` and return it.
+
+    ``rendered_output`` is the candidate file to probe when the published
+    ``final_output`` path does not exist yet; it defaults to ``final_output``.
+    """
+    del tts_segments  # already sealed; the record describes what was consumed
+    if not context.get("active"):
+        report = {
+            "artifact": ARTIFACT, "schema_version": 1, "status": "FINALIZED",
+            "identity_status": "UNADOPTED", "adoption": None,
+            "segments": [
+                {
+                    "index": original["index"], "spoken_text": original["spoken_text"],
+                    "requested_provider": None, "requested_voice": None,
+                    "original": {"path": str(original["source"])},
+                    "snapshot": None, "conversion": {"applied": False},
+                    "placed": None,
+                }
+                for original in context["originals"]
+            ],
+            "narration_bus": ({"path": str(Path(narration_wav).resolve())}
+                              if Path(narration_wav).is_file() else None),
+            "final_output": ({"path": str(Path(final_output).resolve())}
+                             if Path(final_output).is_file() else None),
+            "voice_authentication": "NOT_CHECKED", "direct_listening": "NOT_CHECKED",
+        }
+    else:
+        report = _active_report(
+            context, final_output if rendered_output is None else rendered_output, final_output
+        )
+    write_json_atomic(Path(narration_wav).resolve().parent / FILENAME, report)
+    return report
+
+
+def record_of(report, path):
+    """The manifest/QC summary of one finalized binding report stored at ``path``."""
+    return {"path": str(Path(path).resolve()),
+            "identity_status": report["identity_status"],
+            "tempo_policy": (
+                report["adoption"]["tempo_policy"]
+                if report["identity_status"] == "BOUND_TO_ADOPTION" else None
+            )}
+
+
+def binding_record(work_dir):
+    """The finalized binding's path, identity status and tempo policy; None when absent/invalid."""
+    path = Path(work_dir) / FILENAME
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if (
+        not isinstance(value, dict)
+        or value.get("artifact") != ARTIFACT
+        or type(value.get("schema_version")) is not int
+        or value.get("schema_version") != 1
+        or value.get("status") != "FINALIZED"
+        or value.get("identity_status") not in IDENTITY_STATUSES
+    ):
+        return None
+    if value["identity_status"] == "BOUND_TO_ADOPTION":
+        adoption = value.get("adoption")
+        if not isinstance(adoption, dict):
+            return None
+        try:
+            validate_tempo_policy(adoption.get("tempo_policy"))
+        except ValueError:
+            return None
+    final_output = value.get("final_output")
+    if not isinstance(final_output, dict) or not Path(str(final_output.get("path", ""))).is_file():
+        return None
+    return record_of(value, path)

package/lib/video-recap/skills/video-assemble/scripts/adoption/strict_inputs.py

@@ -0,0 +1,109 @@
+"""Shared strict-input helpers for the explicit-input assemble modules.
+
+Every helper here fails closed with ``ValueError`` on malformed input and never
+guesses: a path must be a local file, a JSON document must parse, a rational must
+be canonical ``N/D``. ``run_logged`` and ``probe_json`` wrap the external tools so
+each caller logs the same evidence.
+"""
+
+from fractions import Fraction
+import json
+import math
+from pathlib import Path
+import subprocess
+
+
+def require_fields(value, required, label):
+    if not isinstance(value, dict) or set(value) != set(required):
+        raise ValueError(f"{label} requires exactly fields {required}")
+
+
+def without_digests(value, label):
+    """Drop the ``sha256`` / ``*_sha256`` keys older caller JSON declared; they are ignored."""
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be an object")
+    return {key: item for key, item in value.items()
+            if key != "sha256" and not key.endswith("_sha256")}
+
+
+def require_integer(value, label, minimum=0):
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{label} must be an integer >= {minimum}")
+    return value
+
+
+def require_number(value, label, minimum, maximum):
+    if type(value) not in (int, float) or not math.isfinite(value) \
+            or not minimum <= value <= maximum:
+        raise ValueError(f"{label} must be finite in [{minimum},{maximum}]")
+    return float(value)
+
+
+def require_local_path(path, label):
+    if not isinstance(path, (str, Path)) or not str(path) or "://" in str(path):
+        raise ValueError(f"{label} requires a local path")
+    resolved = Path(path).resolve()
+    if not resolved.is_file():
+        raise ValueError(f"{label} is missing: {resolved}")
+    return resolved
+
+
+def require_declared_path(value, label):
+    """Resolve a caller ``{"path": ...}`` declaration to an existing local file."""
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be an object with a path")
+    return require_local_path(value.get("path"), label)
+
+
+def read_json_bytes(path, label):
+    """Return (resolved_path, raw_bytes, parsed) for one local JSON document."""
+    resolved = require_local_path(path, label)
+    raw = resolved.read_bytes()
+    try:
+        return resolved, raw, json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{label} is not valid JSON") from exc
+
+
+def write_json_atomic(path, value):
+    path = Path(path)
+    temporary = path.with_suffix(".writing.json")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def canonical_fraction(value, label):
+    if not isinstance(value, str):
+        raise ValueError(f"{label} must be a canonical rational string")
+    try:
+        result = Fraction(value)
+    except (ValueError, ZeroDivisionError) as exc:
+        raise ValueError(f"invalid {label}") from exc
+    if result <= 0 or value != f"{result.numerator}/{result.denominator}":
+        raise ValueError(f"{label} must be a positive canonical N/D rational")
+    return result
+
+
+def probe_json(path, *ffprobe_args):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", *ffprobe_args, "-of", "json", str(path)],
+        capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode or result.stderr.strip():
+        raise ValueError(f"media probe failed for {path}: {result.stderr.strip()}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid media probe JSON for {path}") from exc
+
+
+def run_logged(command, directory, label, *, prefix="", timeout=3600):
+    """Run one FFmpeg command, keeping ``<prefix><label>.command.json`` and ``.log``."""
+    directory = Path(directory)
+    name = f"{prefix}{label}"
+    write_json_atomic(directory / f"{name}.command.json", command)
+    result = subprocess.run(command, capture_output=True, text=True, timeout=timeout)
+    (directory / f"{name}.log").write_text(result.stderr, encoding="utf-8")
+    if result.returncode:
+        raise RuntimeError(f"{name} FFmpeg failed; see {name}.log")
+    return result