@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-assemble/references/source-score.md

@@ -0,0 +1,147 @@
+# Source and score bed producer
+
+`source_score.py` is a standalone producer for explicitly authored source-audio
+intervals and one continuous score playhead. It does not mix narration, inspect old
+masters, infer dialogue, choose music, retime sound, normalize loudness, limit peaks,
+or publish a final video.
+
+```bash
+python3 scripts/source_score.py source_score_plan.json --output-dir a-new-directory
+```
+
+The output directory must not exist. Success creates:
+
+- `source_bed.wav` — reordered/pre-gained source intervals plus explicit silence;
+- `score_bed.wav` — one continuous raw-score window or an adopted frozen stem;
+- `prepared_bed.wav` — source plus score, without master gain/limiting;
+- `prepared_bed_receipt.json` — input paths, clocks, sample ranges, PCM facts and QC facts.
+
+All three beds are `pcm_f32le`, 48 kHz, stereo. Float output avoids repeated integer
+quantization and preserves values outside `[-1,1]`; the receipt records actual peak,
+finite-sample status, and `FLOAT_PRESERVED_NO_MASTER`. A later explicitly adopted
+consumer owns final master gain and delivery encoding.
+
+## Strict plan schema v1
+
+```json
+{
+  "artifact": "source_score_plan",
+  "schema_version": 1,
+  "output": {"sample_rate": 48000, "channels": 2, "total_samples": 1920000},
+  "source_segments": [
+    {
+      "id": "protected-dialogue-1",
+      "path": "/local/source.mov",
+      "audio_stream": 0,
+      "source_fps": "24/1",
+      "source_start_frame": 120,
+      "source_end_frame": 180,
+      "output_start_sample": 240000,
+      "gain": 1.0,
+      "fade_in_samples": 0,
+      "fade_out_samples": 96,
+      "fade_shape": "linear",
+      "role": "protected_original"
+    }
+  ],
+  "source_silence": [
+    {"output_start_sample": 0, "output_end_sample": 240000, "role": "silence"},
+    {"output_start_sample": 360000, "output_end_sample": 1920000, "role": "silence"}
+  ],
+  "score": {
+    "kind": "raw",
+    "path": "/local/score.wav",
+    "audio_stream": 0,
+    "source_offset_sample": 384000,
+    "gain": 0.18,
+    "fade_in_samples": 33600,
+    "fade_out_samples": 120000,
+    "fade_shape": "half_cosine"
+  }
+}
+```
+
+Every source range is half-open in CFR picture frames. Version 1 accepts H.264 and
+HEVC picture sources whose complete packet PTS/duration grid proves one zero-origin
+packet per same-speed frame. Frame boundaries are projected onto the 48 kHz clock by
+rounding the exact position half-up once, so `48000/fps` need not be an integer and a
+broadcast rate such as 30000/1001 is accepted; every derived bound comes from those
+rounded positions. Other codecs, incomplete packet timing, VFR, retime fields,
+nominal time seeks, and unknown fields are rejected rather than called verified
+(legacy `sha256` keys are ignored).
+Each unique selected source stream is decoded from its actual PTS clock to canonical
+48 kHz stereo exactly once. All authored intervals are then cut from that canonical
+sample array—never independently decoded or `-ss`-seeked per edit.
+
+The source segment duration is `(source_end_frame-source_start_frame)*48000/fps`.
+Its output end is derived, not declared. Source segments and explicit silence ranges
+must form an exact, nonoverlapping partition of `[0,total_samples)`. There are no
+implicit gaps. Supported roles are `protected_original` and
+`mixed_original_under_narration`; their gains and labels are retained unchanged.
+
+Source fades are explicitly `linear`. A fade of `N>=2` samples uses inclusive
+endpoints: fade-in gain is `i/(N-1)`, and fade-out gain is `(N-1-i)/(N-1)`. Thus the
+first/last samples are exactly zero and the opposite endpoints exactly one. Zero
+means no fade; a one-sample fade is rejected as ambiguous. Fade windows may not
+overlap within a segment.
+
+## Score modes
+
+`raw` decodes the selected score stream once, advances one playhead from
+`source_offset_sample`, and takes exactly `total_samples`. The input must be long
+enough; there is no implicit loop. Gain and one pair of whole-score fades are applied
+once, so score playback never resets at picture/source cuts. `linear` and
+`half_cosine` fades use inclusive endpoints.
+
+When the adopted source bed is already the complete soundtrack and no additional
+music is selected, use the exact no-score form:
+
+```json
+{"kind":"none"}
+```
+
+It accepts no other fields. `score_bed.wav` is real all-zero float PCM at the exact
+output length, while `prepared_bed.wav` is an exact canonical PCM copy of
+`source_bed.wav`; the receipt records `kind:none` rather than inventing a music asset.
+
+An adopted score that already contains its chosen offset/gain/fades uses the exact
+alternative schema:
+
+```json
+{"kind":"frozen","path":"/local/frozen.wav","audio_stream":0}
+```
+
+Frozen input must be PCM16, PCM24, or PCM float, 48 kHz stereo, and exactly
+`total_samples`. PCM16/24 values convert exactly to float canonical representation.
+No offset, gain, fade, loop, normalization or other processing fields are accepted.
+The receipt records the frozen file path and its probed PCM facts.
+
+## Receipt and failure boundary
+
+`prepared_bed_receipt` schema version 1 records the plan path, each input path,
+selected stream, actual CFR/audio clocks, canonical decoded PCM facts, resolved
+input/output sample ranges, gains, fades, roles, and each output's path, byte size,
+format, sample count, finite status and peak.
+
+Every declared input must exist and probe as declared before work starts. A selected
+source range must fit the actual canonical decoded samples; silence padding can never
+conceal a short source. WAVs remain hidden staging artifacts until every output
+validates. FFmpeg failure, invalid ranges, non-finite PCM, or an existing target
+directory cannot publish final-named beds or a receipt.
+Diagnostic command/log/intermediate files may remain in the unique failed directory.
+
+To consume a completed receipt with explicitly adopted narration, use the strict
+`--audio-mix-adoption` path in `explicit-audio-mix.md`. To deliver an already complete
+prepared bed without narration, a dedicated prepared-audio renderer will follow in a
+later release. Do not feed `prepared_bed.wav` through legacy source ducking or
+ambient BGM/loudness settings.
+
+## 与旧入口的关系（中文摘要）
+
+原片完整解码一次再切样本，分别执行保留对白、低位原声和明确静音；渐变必须显式给定。
+已处理的音乐轨走 `frozen`，不能再次偏移、调增益或加渐变。若采用的原声底轨本身已包含
+完整音乐决定且不再叠加配乐，使用严格的 `score:{"kind":"none"}`；它生成真实全零 score，
+并保持 prepared 与 source 逐字节相同，不伪造静音音乐资产。
+
+这一步仅输出声音底轨和来源回执，不是最终视频。旧入口保留兼容行为；调用方须区分
+“底轨已验证”“配音已验证”和“完整混音已验证”三种状态，不能相互冒充。

package/lib/video-recap/skills/video-assemble/references/subtitle-track.md

@@ -0,0 +1,202 @@
+# Independent subtitle track contract (schema v1)
+
+`scripts/subtitles/track.py` loads a subtitle track whose cue times already use
+the final **output clock**. It validates the track against picture, edit, audio,
+and duration facts independently supplied by the caller. It does not align
+speech, remap source time, split text, repair cue boundaries, or prove that a
+subtitle is perceptually synchronized.
+
+## Loader API
+
+```python
+from fractions import Fraction
+from subtitles.track import load_subtitle_track
+
+loaded = load_subtitle_track(
+    "subtitle_track.json",
+    expected_picture_identity={
+        "path": "/project/paired.mp4",
+        "edit_plan": "/project/edit_plan.json",
+    },
+    expected_audio_identity={
+        "selected_stream": 1,
+        "sample_rate": 48000,
+        "packet_count": 4700,
+    },
+    expected_duration_seconds=Fraction(duration_ts) * stream_time_base,
+    reject_legacy_estimate=True,
+)
+metadata = loaded["metadata"]
+entries = loaded["entries"]
+```
+
+The input may also be an in-memory mapping. `entries` is a list of dictionaries
+ready for the existing seconds-based subtitle renderer:
+
+```json
+{
+  "start": 1.0,
+  "end": 3.0,
+  "text": "example",
+  "source": "narration",
+  "source_ref": "narration:7",
+  "timing_evidence": {
+    "kind": "asr_boundary_calibrated",
+    "evidence_refs": ["alignment-run:example"],
+    "calibration": "asr_energy",
+    "word_alignment": "none"
+  }
+}
+```
+
+The loader preserves cue text and boundaries. The only conversion is exact
+integer ticks to renderer-facing seconds. `metadata.timing_evidence_kinds`
+reports the labels present; it is not an aggregate precision verdict.
+
+## Schema v1
+
+```json
+{
+  "schema_version": 1,
+  "clock": {
+    "kind": "output",
+    "timebase": {"numerator": 1, "denominator": 30},
+    "duration_ticks": 300
+  },
+  "overlap_policy": "forbid",
+  "bindings": {
+    "picture": {
+      "path": "/project/paired.mp4",
+      "edit_plan": "/project/edit_plan.json"
+    },
+    "audio": {
+      "selected_stream": 1,
+      "sample_rate": 48000,
+      "packet_count": 4700
+    }
+  },
+  "cues": [
+    {
+      "start_tick": 30,
+      "end_tick": 90,
+      "text": "example",
+      "attribution": {"kind": "narration", "ref": "narration:7"},
+      "timing_evidence": {
+        "kind": "asr_boundary_calibrated",
+        "evidence_refs": ["alignment-run:example"],
+        "calibration": "asr_energy",
+        "word_alignment": "none"
+      }
+    }
+  ]
+}
+```
+
+- `timebase` is rational seconds per tick. Cue intervals are half-open
+  `[start_tick, end_tick)`.
+- `duration_ticks`, cue bounds, and stream indexes are nonnegative integers
+  (booleans are not integers for this contract).
+- Cues must be ordered, non-overlapping, nonempty, and contained by the output
+  duration. Adjacent half-open cues may touch.
+- Distinct tick bounds must remain a positive, finite interval after conversion
+  to the renderer's float seconds. Tracks beyond that projection precision fail
+  closed rather than becoming a zero-length rendered cue.
+- `overlap_policy` must be `forbid`. Schema v1 has no permissive overlap mode.
+- `attribution.kind` is `source` or `narration`; `ref` identifies the source
+  utterance or narration item without changing its text.
+- Unknown fields and schema versions other than integer `1` are rejected, so a
+  newer producer cannot be silently interpreted as v1. Legacy `sha256` /
+  `edit_sha256` binding keys are the one exception: they are ignored.
+
+## Independent binding checks
+
+The loader compares track declarations with the caller's current facts; it never
+treats a track's own binding as evidence that the track is fresh.
+
+- `picture.path` is mandatory and must resolve to the caller's current picture
+  path. `edit_plan` is optional for inputs without a separately materialized
+  edit plan; if the track contains it, the caller must supply the same path.
+- `audio.selected_stream`, `sample_rate` and `packet_count` describe the
+  **actually adopted** audio stream, not merely a source filename or an intended
+  mix manifest. Pass the facts probed from the current media; this module
+  deliberately does not run ffprobe itself.
+- `expected_duration_seconds` is mandatory and checked against
+  `duration_ticks * timebase`. Prefer `Fraction(duration_ts) * time_base` from
+  the actual output stream to avoid decimal/container rounding. `int`, finite
+  `float`, and finite `Decimal` are also accepted.
+
+## Timing evidence labels
+
+Evidence labels describe how a cue boundary was obtained. They do not change
+the exact burn time represented by its ticks.
+
+| `kind` | Required calibration | Required word alignment | Evidence refs |
+|---|---|---|---|
+| `legacy_estimate` | `none` | `none` | optional |
+| `asr_boundary_calibrated` | `asr_energy` | `none` | required |
+| `word_timestamps` | `none` or `asr_energy` | `asr_words` | required |
+| `human_verified` | `human_boundary` | `none` or `human_words` | required |
+
+`asr_boundary_calibrated` is the label for a coarse-ASR boundary adjusted with
+ASR context and/or energy evidence. Energy onset is not proof of a phoneme, so
+this label cannot claim word alignment or human verification. Missing evidence
+references cannot claim any non-legacy kind. A strict caller may reject
+`legacy_estimate`; accepting another label still does not automatically call it
+strong alignment.
+
+Because cue intervals are half-open, a cue is not visible at any tick before its
+`start_tick`; the tick immediately preceding it belongs to whatever came before.
+
+## Deliberate limits
+
+- Schema v1 has no source-to-cut/edit map and cannot map source-clock cues.
+- The module does not inspect media, select audio streams, or tolerate a
+  self-declared binding without current caller facts.
+- Validation proves schema consistency and the requested bindings only. Actual
+  rendered first/last subtitle frames and perceptual speech alignment require
+  separate render/media review.
+
+## Current assembly integration (bounded, not automatic alignment)
+
+Place `subtitle_track.json` in `work_dir` and select
+`assemble.py --audio-mode adopted-packet-copy`. A present track is a **complete
+replacement** of all generated narration/original-dialogue subtitles, not a
+partial patch and not merged with legacy subtitles. Carry every cue that should
+remain; an empty `cues` array intentionally removes all generated subtitles.
+Unknown patch/merge modes are rejected by schema v1. This does not detect words
+missing from the authored full track: acoustic/coverage review remains required.
+
+The assembly integration independently probes the chosen input stream for its
+sample rate and packet count, resolves the input path for the picture binding,
+and records the `{size, mtime_ns}` of the track, video and optional edit plan in
+`subtitle_track_validation.json`. It does not use the track's own declarations
+as current facts.
+
+Actual decoded frame PTS are read before projection. Integer cue ticks and the
+rational timebase are retained until each boundary is resolved to the first
+frame at or after it. `subtitle_track_validation.json` records original ticks,
+resolved frame indexes/PTS, quantization deltas, ASS thresholds, validation
+schema and projector version. SRT and timeline consume resolved frame seconds;
+ASS thresholds are chosen to switch on those same frames despite ASS's 10ms
+clock. A cue with no visible frame, or a boundary that ASS cannot distinguish,
+is rejected rather than silently dropped. The original author file is not
+rewritten. Legacy subtitles keep their previous rendering behavior.
+
+Each consumption re-checks the track/media/optional edit plan `{size, mtime_ns}`
+and the consumer duration; a rewritten input is stale and must be prepared
+again. Deleting the explicit track clears its previous validation record.
+An invalid/stale track never falls back to character-proportional timing.
+
+Current limits:
+- Integration is for output media starting at zero with an adopted AAC track,
+  not raw-source-to-edited-output mapping or a newly mixed narration track.
+- The low-level preparation API accepts `edit_plan_path`, but the assembly CLI
+  does not yet expose it. CLI tracks must omit `edit_plan`; that path binds the
+  input media, not edit-plan ancestry.
+- The low-level policy `reject_legacy_estimate=True` is available. There is not
+  yet a wired commercial-profile CLI gate. The current CLI preserves timing
+  evidence labels and does not call every accepted cue precisely aligned.
+- The actual FFmpeg regression demonstrates frame timing with a synthetic cue,
+  not phoneme alignment. `direct_listening` and `acoustic_alignment` remain
+  `NOT_CHECKED`; evidence labels are declarations, not automatically verified
+  human approval or proof that an external evidence reference is true.

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

@@ -0,0 +1 @@
+"""Adoption family: narration/audio-mix binding + strict publish for adopted-source audio."""

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

@@ -0,0 +1,279 @@
+"""Validate, render, and record an explicitly adopted prepared-bed plus narration mix."""
+
+import json
+from pathlib import Path
+import subprocess
+
+from assemble_constants import frame_clock_samples
+from adoption.frozen_audio import probe_audio_packets
+import adoption.narration_binding as narration_binding
+from pair_media import probe_picture, validate_pair_timing
+import source_score
+from adoption.strict_inputs import (
+    read_json_bytes, require_fields, require_integer, require_local_path, require_number,
+    run_logged, without_digests, write_json_atomic,
+)
+
+
+ARTIFACT = "audio_mix_binding"
+FILENAME = "audio_mix_binding.json"
+RATE = 48_000
+CHANNELS = 2
+CODEC = "pcm_f32le"
+
+
+def _picture_format(picture):
+    samples = frame_clock_samples(picture["frame_count"], picture["fps"], RATE)
+    return samples, {
+        "fps": picture["fps"], "frame_count": picture["frame_count"],
+        "duration": picture["duration"], "start": picture["start"],
+        "decoder": picture["decoder"],
+    }
+
+
+def load_adoption(path, *, input_video, narration_adoption_path, tts_segments):
+    """Strict read-only preflight; no work artifacts are created here."""
+    adoption_path, _, value = read_json_bytes(path, "audio mix adoption")
+    value = without_digests(value, "audio mix adoption")
+    require_fields(value, ["artifact", "schema_version", "prepared_receipt", "format", "segments",
+                           "master_gain_db"], "audio mix adoption")
+    if value["artifact"] != "audio_mix_adoption" or type(value["schema_version"]) is not int \
+            or value["schema_version"] != 1:
+        raise ValueError("unsupported audio_mix_adoption schema")
+    input_video = require_local_path(input_video, "picture")
+    picture = probe_picture(input_video)
+    picture_samples, picture_summary = _picture_format(picture)
+
+    narration_path = require_local_path(narration_adoption_path, "narration adoption")
+    require_fields(value["format"], ["sample_rate", "channels", "total_samples"], "mix format")
+    mix_format = value["format"]
+    if mix_format != {"sample_rate": RATE, "channels": CHANNELS,
+                      "total_samples": picture_samples}:
+        raise ValueError("mix format differs from the actual picture sample clock")
+    prepared_receipt = source_score.validate_prepared_receipt(
+        value["prepared_receipt"], mix_format
+    )
+
+    if not isinstance(value["segments"], list) or len(value["segments"]) != len(tts_segments):
+        raise ValueError("audio mix segments must exactly cover narration segments")
+    normalized = []
+    seen = set()
+    for adopted, segment in zip(value["segments"], tts_segments):
+        adopted = without_digests(adopted, "audio mix segment")
+        require_fields(adopted, ["index", "output_start_sample", "gain"], "audio mix segment")
+        index = require_integer(adopted["index"], "audio mix segment index")
+        if index in seen or index != segment["index"]:
+            raise ValueError("audio mix segment index/order differs from narration")
+        seen.add(index)
+        normalized.append({
+            "index": index,
+            "output_start_sample": require_integer(
+                adopted["output_start_sample"], "output_start_sample"),
+            "gain": require_number(adopted["gain"], "narration gain", 0, 16),
+        })
+    return {
+        "path": str(adoption_path),
+        "picture": {"path": str(input_video), "clock": picture_summary},
+        "picture_identity": picture,
+        "prepared_receipt": prepared_receipt["reference"],
+        "prepared": prepared_receipt["outputs"],
+        "narration_adoption": {"path": str(narration_path)},
+        "format": dict(mix_format), "segments": normalized,
+        "master_gain_db": require_number(value["master_gain_db"], "master_gain_db", -24, 24),
+        "runtime": None,
+    }
+
+
+def _run(command, work_dir, label):
+    run_logged(command, work_dir, label, prefix="explicit_")
+
+
+def _channels(path):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+         "stream=channels", "-of", "default=nw=1:nk=1", str(path)],
+        capture_output=True, text=True, timeout=600,
+    )
+    try:
+        channels = int(result.stdout.strip())
+    except ValueError as exc:
+        raise ValueError("narration channel probe failed") from exc
+    if result.returncode or channels not in {1, 2}:
+        raise ValueError("explicit narration supports only mono or stereo input")
+    return channels
+
+
+def render_explicit_mix(context, narration_context, tts_segments, work_dir):
+    """Render complete direct 48 kHz placements, voice bus, premaster, and fixed master."""
+    directory = Path(work_dir).resolve() / ".explicit_audio_mix"
+    directory.mkdir(parents=True, exist_ok=False)
+    by_index = {item["index"]: item for item in narration_context["segments"]}
+    segment_memory = {item["index"]: item for item in tts_segments}
+    rendered = []
+    for position, adopted in enumerate(context["segments"]):
+        source = by_index[adopted["index"]]["snapshot"]["path"]
+        channels = _channels(source)
+        placed = directory / f"placed_{position:04d}_{adopted['index']}.wav"
+        if channels == 1:
+            channel_filter = (
+                "aformat=sample_fmts=flt,"
+                "pan=stereo|c0=0.7071067811865476*c0|c1=0.7071067811865476*c0,"
+                "aresample=48000:async=0:first_pts=0,aformat=sample_fmts=flt:"
+                "sample_rates=48000:channel_layouts=stereo"
+            )
+            matrix = "mono_equal_power"
+        else:
+            channel_filter = (
+                "aresample=48000:async=0:first_pts=0,aformat=sample_fmts=flt:"
+                "sample_rates=48000:channel_layouts=stereo"
+            )
+            matrix = "stereo_identity"
+        _run(["ffmpeg", "-nostdin", "-v", "error", "-n", "-i", str(source),
+              "-map", "0:a:0", "-af", channel_filter, "-c:a", CODEC, str(placed)],
+             directory, f"place_{position:04d}")
+        facts = source_score._output_facts(placed)
+        start = adopted["output_start_sample"]
+        end = start + facts["pcm"]["samples"]
+        if end > context["format"]["total_samples"]:
+            raise ValueError("complete narration segment does not fit the adopted mix clock")
+        rendered.append({**adopted, "output_end_sample": end, "input_channels": channels,
+                         "channel_matrix": matrix, "placed": facts})
+        memory = segment_memory[adopted["index"]]
+        memory.update({
+            "placed_audio_path": str(placed),
+            "narration_conversion_path": str(placed),
+            "audio_duration": facts["pcm"]["samples"] / RATE,
+            "placed_audio_duration": facts["pcm"]["samples"] / RATE,
+            "actual_place_start": start / RATE, "actual_place_end": end / RATE,
+            "output_start_sample": start, "output_end_sample": end,
+            "adopted_gain": adopted["gain"],
+            "global_narration_speed": 1.0, "segment_tempo_factor": 1.0,
+            "effective_tempo": 1.0, "fit_status": "placed", "blocking": False,
+            "truncated": False, "truncate_reason": "none",
+        })
+    ordered = sorted(rendered, key=lambda item: item["output_start_sample"])
+    if any(current["output_start_sample"] < previous["output_end_sample"]
+           for previous, current in zip(ordered, ordered[1:])):
+        raise ValueError("explicit narration placements overlap")
+
+    total = context["format"]["total_samples"]
+    voice_bus = directory / "voice_bus.wav"
+    command = ["ffmpeg", "-nostdin", "-v", "error", "-n"]
+    for item in rendered:
+        command += ["-i", item["placed"]["path"]]
+    filters = [f"anullsrc=r={RATE}:cl=stereo,atrim=end_sample={total}[base]"]
+    labels = ["[base]"]
+    for position, item in enumerate(rendered):
+        filters.append(
+            f"[{position}:a]volume={item['gain']:.17g},"
+            f"adelay={item['output_start_sample']}S:all=1[v{position}]"
+        )
+        labels.append(f"[v{position}]")
+    filters.append("".join(labels) + f"amix=inputs={len(labels)}:duration=first:normalize=0,"
+                   f"atrim=end_sample={total},aformat=sample_fmts=flt:sample_rates={RATE}:"
+                   "channel_layouts=stereo[out]")
+    command += ["-filter_complex", ";".join(filters), "-map", "[out]", "-c:a", CODEC,
+                str(voice_bus)]
+    _run(command, directory, "voice_bus")
+    voice_facts = source_score._output_facts(voice_bus)
+    narration_binding.seal_render_inputs(narration_context, tts_segments, voice_bus)
+    narration_context["sealed"]["narration_bus"]["consumption_status"] = \
+        "CONSUMED_BY_EXPLICIT_MIX"
+
+    prepared = context["prepared"]["prepared_bed.wav"]["path"]
+    premaster = directory / "premaster.wav"
+    _run(["ffmpeg", "-nostdin", "-v", "error", "-n", "-i", prepared, "-i", str(voice_bus),
+          "-filter_complex", f"[0:a][1:a]amix=inputs=2:duration=first:normalize=0,"
+          f"atrim=end_sample={total},aformat=sample_fmts=flt:sample_rates={RATE}:"
+          "channel_layouts=stereo[out]", "-map", "[out]", "-c:a", CODEC, str(premaster)],
+         directory, "premaster")
+    master = directory / "master.wav"
+    gain = 10 ** (context["master_gain_db"] / 20)
+    _run(["ffmpeg", "-nostdin", "-v", "error", "-n", "-i", str(premaster),
+          "-af", f"volume={gain:.17g},aformat=sample_fmts=flt:sample_rates={RATE}:"
+          "channel_layouts=stereo", "-c:a", CODEC, str(master)], directory, "master")
+    runtime = {
+        "segments": rendered, "voice_bus": voice_facts,
+        "premaster": source_score._output_facts(premaster),
+        "master": source_score._output_facts(master), "master_gain_linear": gain,
+    }
+    if any(runtime[key]["pcm"]["samples"] != total
+           for key in ("voice_bus", "premaster", "master")):
+        raise ValueError("explicit mix derivative sample count differs from picture clock")
+    context["runtime"] = runtime
+    return runtime
+
+
+def finalize_binding(context, narration_record, rendered_output, final_output, work_dir):
+    """Probe the rendered candidate and write ``audio_mix_binding.json`` into work_dir."""
+    if not context.get("runtime"):
+        raise RuntimeError("explicit audio mix must be rendered before finalization")
+    rendered = require_local_path(rendered_output, "rendered output")
+    output_picture = probe_picture(rendered)
+    input_clock = _picture_format(context["picture_identity"])[1]
+    output_clock = _picture_format(output_picture)[1]
+    for key in ("fps", "frame_count", "duration", "start"):
+        if output_clock[key] != input_clock[key]:
+            raise ValueError("rendered output picture frame clock changed")
+    packet_identity = (
+        "EXACT" if output_picture == context["picture_identity"]
+        else "REENCODED_CLOCK_MATCH"
+    )
+    audio = probe_audio_packets(rendered, 0)
+    validate_pair_timing(output_picture, audio)
+    decoded = Path(context["runtime"]["master"]["path"]).parent / "final_aac_decoded.wav"
+    _run(["ffmpeg", "-nostdin", "-v", "error", "-n", "-i", str(rendered),
+          "-map", "0:a:0", "-af", "aformat=sample_fmts=flt:sample_rates=48000:"
+          "channel_layouts=stereo", "-c:a", CODEC, str(decoded)], decoded.parent,
+         "final_decode")
+    context["runtime"]["final_decoded_pcm"] = source_score._output_facts(decoded)
+    report = {
+        "artifact": ARTIFACT, "schema_version": 1, "status": "FINALIZED",
+        "adoption": {"path": context["path"]},
+        "picture": context["picture"],
+        "output_picture": {
+            **output_clock, "packet_identity": packet_identity,
+        },
+        "prepared_receipt": context["prepared_receipt"],
+        "prepared": context["prepared"], "format": context["format"],
+        "segments": context["runtime"]["segments"],
+        "voice_bus": context["runtime"]["voice_bus"],
+        "premaster": context["runtime"]["premaster"],
+        "master": {**context["runtime"]["master"], "gain_db": context["master_gain_db"],
+                   "gain_linear": context["runtime"]["master_gain_linear"]},
+        "narration_input_binding": {"path": narration_record["path"], "status": "FINALIZED"},
+        "final_output": {
+            "path": str(Path(final_output).resolve()),
+            "decoded_pcm": context["runtime"]["final_decoded_pcm"],
+            "audio_stream": {
+                "decoder": audio["decoder"], "packet_count": audio["packet_count"],
+                "payload_bytes": audio["payload_bytes"],
+                "start_time": audio["start_time"], "duration": audio["duration"],
+            },
+        },
+        "direct_listening": "NOT_CHECKED", "normal_speed_review": "NOT_CHECKED",
+        "release_approved": False,
+    }
+    write_json_atomic(Path(work_dir).resolve() / FILENAME, report)
+    return report
+
+
+def binding_record(work_dir):
+    """The finalized mix binding's path and status; None when absent or malformed."""
+    path = Path(work_dir) / FILENAME
+    if not path.is_file():
+        return None
+    try:
+        report = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(report, dict) or report.get("artifact") != ARTIFACT \
+            or report.get("schema_version") != 1 or report.get("status") != "FINALIZED":
+        return None
+    final = report.get("final_output")
+    if not isinstance(final, dict) or not Path(str(final.get("path", ""))).is_file():
+        return None
+    narration = report.get("narration_input_binding")
+    if not isinstance(narration, dict) or not Path(str(narration.get("path", ""))).is_file():
+        return None
+    return {"path": str(path.resolve()), "status": "FINALIZED"}