@lemoncat7/dsh-partner 2.8.0 → 2.8.2

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/assembly_contract.py

@@ -0,0 +1,318 @@
+"""Assembly manifest/QC persistence and delivery contract helpers."""
+
+import json
+from fractions import Fraction
+import math
+import subprocess
+import wave
+from pathlib import Path
+
+from lib import CONFIG
+from assemble_constants import (
+    ASSEMBLY_MANIFEST,
+    ASSEMBLY_QC,
+    SEGMENT_AUDIO_SCHEMA_VERSION,
+)
+from audio_mix import _loudness_mode
+from subtitles.track_binding import manifest_subtitle_evidence
+from artifacts import (
+    _load_work_json,
+    _source_video_identity,
+    _timeline_provenance_status,
+)
+
+_AUDIO_QC_CODES = frozenset({
+    "missing_narration", "skipped_segments", "no_safe_fit", "effective_tempo_exceeded",
+    "empty_narration", "truncated_speech", "unsafe_source_handoff", "timeline_audio_mismatch",
+})
+
+
+def _assembly_manifest_payload(input_video, tts_segments, work_dir, output_path,
+                               tts_meta_path=None, final_output=None, *, settings_payload,
+                               audio_mode="narration", audio_stream_index=0,
+                               narration_input_binding=None, audio_mix_binding=None):
+    """Slim render record. The orchestrator reads `final_output` to report the result;
+    `source_video` stays None unless cut mode explicitly passed --source-video, proving a
+    stale ambient SOURCE_VIDEO never leaked into a full-mode timeline / 剪映 export."""
+    input_video = Path(input_video)
+    output_path = Path(output_path)
+    source_video_identity = _source_video_identity()
+    qc_path = Path(work_dir) / ASSEMBLY_QC
+    qc = _load_work_json(work_dir, ASSEMBLY_QC)  # always written by publish_render first
+    settings = settings_payload(
+        work_dir, audio_mode=audio_mode, audio_stream_index=audio_stream_index
+    )
+    payload = {
+        "schema_version": 2,
+        "input_video": str(input_video.resolve()),
+        "source_video": source_video_identity["path"] if source_video_identity else None,
+        "source_video_identity": source_video_identity,
+        "tts_meta": str(Path(tts_meta_path).resolve()) if tts_meta_path else None,
+        "tts_segments": len(tts_segments),
+        "audio_mode": audio_mode,
+        "selected_audio_stream_index": audio_stream_index,
+        "assembly_settings": settings,
+        "output_path": str(output_path.resolve()),
+        "segment_audio_schema_version": SEGMENT_AUDIO_SCHEMA_VERSION,
+        "qc_path": str(qc_path.resolve()),
+        "qc_verdict": qc["verdict"],
+        "qc_blocking_codes": qc["blocking_codes"],
+        # The settings payload records the configured/fallback loudness policy; these QC
+        # fields record what the just-finished render actually used after the loudnorm probe.
+        "qc_loudness_mode": qc["loudness_mode"],
+        "qc_loudnorm_measurement": qc["loudnorm_measurement"],
+        "audio_operations": qc["audio_operations"],
+        "adopted_audio": qc["adopted_audio"],
+        "narration_input_binding": narration_input_binding,
+        "audio_mix_binding": audio_mix_binding,
+        "audio_segments": [
+            {
+                "index": seg["index"],
+                # Informational manifest fields: a tts_meta without the schema marker is v1,
+                # and the loudness measurements are None whenever voiceover skipped
+                # normalization (strict adoption fixtures in tests/orchestrator omit both).
+                "segment_audio_schema_version": seg.get(
+                    "segment_audio_schema_version", SEGMENT_AUDIO_SCHEMA_VERSION
+                ),
+                "narration": seg["narration"],
+                "spoken_text": seg["spoken_text"],
+                "truncated": seg["truncated"],
+                "truncate_reason": seg["truncate_reason"],
+                "fit_status": seg["fit_status"],
+                "blocking": seg["blocking"],
+                "audio_duration": seg["audio_duration"],
+                "placed_audio_duration": seg["placed_audio_duration"],
+                "placed_audio_path": seg.get("placed_audio_path"),
+                "actual_place_start": seg.get("actual_place_start"),
+                "actual_place_end": seg.get("actual_place_end"),
+                "source_duck_end": seg.get("source_duck_end"),
+                "source_restore_at": seg.get("source_restore_at"),
+                "source_handoff_status": seg.get("source_handoff_status"),
+                "source_entry_status": seg.get("source_entry_status"),
+                "global_narration_speed": seg["global_narration_speed"],
+                "segment_tempo_factor": seg["segment_tempo_factor"],
+                "effective_tempo": seg["effective_tempo"],
+                "rms_dbfs_before": seg.get("rms_dbfs_before"),
+                "rms_dbfs_after": seg.get("rms_dbfs_after"),
+                "peak_after": seg.get("peak_after"),
+                "output_start_sample": seg.get("output_start_sample"),
+                "output_end_sample": seg.get("output_end_sample"),
+                "adopted_gain": seg.get("adopted_gain"),
+            }
+            for seg in tts_segments
+        ],
+    }
+    if final_output is not None:
+        payload["final_output"] = str(Path(final_output).resolve())
+    provenance = _timeline_provenance_status(work_dir)
+    if provenance:
+        payload["timeline_provenance"] = provenance
+    subtitle_evidence = manifest_subtitle_evidence(work_dir, input_video, output_path)
+    if subtitle_evidence is not None:
+        payload["subtitle_track"] = subtitle_evidence
+    return payload
+
+
+def _write_assembly_manifest(work_dir, manifest):
+    path = Path(work_dir) / ASSEMBLY_MANIFEST
+    path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def _visual_qc_rollup(visual_qc):
+    subtitles = visual_qc["subtitles"]
+    overlays = visual_qc["overlays"]
+    return {
+        "present": True,
+        "artifact": visual_qc["artifact"],
+        "verdict": visual_qc["verdict"],
+        "blocking": visual_qc["blocking"],
+        "blocking_codes": list(visual_qc["blocking_codes"]),
+        "summary": visual_qc["summary"],
+        "geometry": visual_qc["geometry"],
+        "subtitles": {
+            "entries": subtitles["entries"],
+            "multi_line": subtitles["multi_line"],
+            "overflow": subtitles["overflow"],
+            "safe_area": subtitles["safe_area"],
+        },
+        "mask": visual_qc["mask"],
+        "overlays": {
+            "present": overlays["present"],
+            "rendered": overlays["rendered"],
+            "unsupported": overlays["unsupported"],
+            "overflow": overlays["overflow"],
+        },
+    }
+
+
+def _placed_audio_matches_timeline(seg):
+    """True when the persisted per-beat WAV is exactly what the serialized timeline window plays."""
+    placed_path = Path(seg["placed_audio_path"])
+    if not placed_path.exists():
+        return False
+    try:
+        with wave.open(str(placed_path), "rb") as placed_wav:
+            placed_duration = placed_wav.getnframes() / placed_wav.getframerate()
+            tolerance = 1.0 / placed_wav.getframerate()
+    except wave.Error:
+        result = subprocess.run(
+            ["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+             "stream=sample_rate,time_base,duration_ts", "-of", "json", str(placed_path)],
+            capture_output=True, text=True, timeout=600,
+        )
+        streams = json.loads(result.stdout).get("streams", []) if not result.returncode else []
+        if len(streams) != 1:
+            return False
+        stream = streams[0]
+        try:
+            rate = int(stream["sample_rate"])
+            placed_duration = float(Fraction(stream["duration_ts"]) * Fraction(stream["time_base"]))
+            tolerance = 1.0 / rate
+        except (KeyError, TypeError, ValueError, ZeroDivisionError):
+            return False
+    timeline_start = math.floor(float(seg["actual_place_start"]) * 10_000 + 1e-9) / 10_000
+    timeline_end = math.ceil(float(seg["actual_place_end"]) * 10_000 - 1e-9) / 10_000
+    serialized_span = timeline_end - timeline_start
+    return (
+        abs(placed_duration - seg["placed_audio_duration"]) <= tolerance + 1e-9
+        and serialized_span + 1e-9 >= placed_duration
+    )
+
+
+def _build_assembly_qc(tts_segments, video_duration, *, audio_operations, render_delivery,
+                       output_path=None, source_has_audio=None, loudness_mode=None,
+                       loudnorm_measurement=None, visual_qc=None, audio_mode="narration",
+                       adopted_audio=None,
+                       narration_input_binding=None, audio_mix_binding=None,
+                       source_audio_status=None):
+    """Machine-readable assembly release gate.
+
+    Visual facts are rolled up from visual_qc.json. Delivery/render facts live here
+    (or render/delivery QC in future), never in visual_qc.json.
+    """
+    hard_max = CONFIG["narration_cumulative_tempo_hard_max"]
+    segments = tts_segments
+    no_safe = [
+        s["index"] for s in segments
+        if s["fit_status"] == "no_safe_fit"
+        or s["truncate_reason"] in {"no_safe_boundary", "no_room"}
+        or s["blocking"]
+    ]
+    skipped = [s["index"] for s in segments if s["fit_status"] == "skipped"]
+    tempo_exceeded = []
+    truncated = []
+    handoff_failed = []
+    timeline_audio_failed = []
+    max_effective = 0.0
+    for s in segments:
+        eff = float(s["effective_tempo"])
+        max_effective = max(max_effective, eff)
+        if eff > hard_max + 1e-6:
+            tempo_exceeded.append(s["index"])
+        if s["truncated"] or s["truncate_reason"] == "tail_trim_tolerance":
+            truncated.append(s["index"])
+        if s.get("source_handoff_blocking", False):
+            handoff_failed.append(s["index"])
+        if s["placed_audio_duration"] > 0 and not _placed_audio_matches_timeline(s):
+            timeline_audio_failed.append(s["index"])
+
+    placed = [s["placed_audio_duration"] for s in segments]
+    blocking_codes = []
+    if audio_mode == "narration" and not segments:
+        blocking_codes.append("missing_narration")
+    if skipped:
+        blocking_codes.append("skipped_segments")
+    if no_safe:
+        blocking_codes.append("no_safe_fit")
+    if tempo_exceeded:
+        blocking_codes.append("effective_tempo_exceeded")
+    if truncated:
+        blocking_codes.append("truncated_speech")
+    if handoff_failed:
+        blocking_codes.append("unsafe_source_handoff")
+    if timeline_audio_failed:
+        blocking_codes.append("timeline_audio_mismatch")
+    if placed and max(placed) <= 0.0 and not no_safe:
+        blocking_codes.append("empty_narration")
+    visual_rollup = (
+        _visual_qc_rollup(visual_qc)
+        if visual_qc is not None
+        else {"present": False, "verdict": "NOT_RUN", "blocking": False, "blocking_codes": [], "summary": {}}
+    )
+    if visual_rollup["blocking"]:
+        blocking_codes.append("visual_qc_failed")
+    if source_audio_status is not None:
+        source_audio = source_audio_status
+    elif source_has_audio is False:
+        # Not blocking: assemble can synthesize a silent original track.
+        source_audio = "synthetic_silence"
+    elif source_has_audio is True:
+        source_audio = "present"
+    else:
+        source_audio = "unknown"
+
+    output = {}
+    if output_path is not None:
+        output_path = Path(output_path)
+        output = {
+            "path": str(output_path),
+            "exists": output_path.exists(),
+            "bytes": output_path.stat().st_size if output_path.exists() else 0,
+        }
+        if output_path.exists() and output["bytes"] <= 0:
+            blocking_codes.append("empty_output")
+
+    return {
+        "schema_version": 1,
+        "artifact": ASSEMBLY_QC,
+        "verdict": "FAIL" if blocking_codes else "PASS",
+        "blocking": bool(blocking_codes),
+        "blocking_codes": blocking_codes,
+        "duration": round(float(video_duration), 4),
+        "audio_mode": audio_mode,
+        "audio_operations": audio_operations,
+        "adopted_audio": adopted_audio,
+        "narration_input_binding": narration_input_binding,
+        "audio_mix_binding": audio_mix_binding,
+        "source_audio": source_audio,
+        "loudness_mode": loudness_mode or _loudness_mode(loudnorm_measurement),
+        "loudnorm_measurement": loudnorm_measurement,
+        "release_gate": {
+            "verdict": "FAIL" if blocking_codes else "PASS",
+            "visual_qc": visual_rollup["verdict"],
+            "delivery_qc": "PASS",
+            "audio_qc": "FAIL" if _AUDIO_QC_CODES.intersection(blocking_codes) else "PASS",
+        },
+        "visual_qc": visual_rollup,
+        "delivery_qc": {
+            "video_encode_passes": render_delivery["video_encode_passes"],
+            "reencode_reason": render_delivery["reencode_reason"],
+            "audio_sample_rate": render_delivery["audio_sample_rate"],
+            "final_compat_notes": render_delivery["final_compat_notes"],
+        },
+        "summary": {
+            "segments": len(segments),
+            "placed_segments": sum(1 for x in placed if x > 0.0),
+            "skipped_segments": skipped,
+            "no_safe_fit_segments": no_safe,
+            "tempo_exceeded_segments": tempo_exceeded,
+            "max_effective_tempo": round(max_effective, 4),
+            "truncated_segments": truncated,
+            "unsafe_source_handoff_segments": handoff_failed,
+            "timeline_audio_mismatch_segments": timeline_audio_failed,
+        },
+        "output": output,
+    }
+
+
+def _write_assembly_qc(work_dir, qc):
+    path = Path(work_dir) / ASSEMBLY_QC
+    path.write_text(json.dumps(qc, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def _resolve_final_output(base, stem):
+    """The recap output is the stable human alias recap_<stem>.mp4, overwritten in place
+    on every run so the iterate-on-narration loop always refreshes the same file."""
+    return Path(base) / f"recap_{stem}.mp4"

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/assembly_settings.py

@@ -0,0 +1,138 @@
+"""Render-affecting settings payload recorded in the manifest and compared by resume logic."""
+
+from pathlib import Path
+
+from artifacts import _artifact_identity
+from assemble_constants import VISUAL_OVERLAYS
+from audio_mix import _loudness_mode, final_loudnorm_filter
+from lib import CONFIG
+from source_subtitles import _has_user_subtitles, _source_subtitle_mask_policy
+from subtitles.core import _subtitle_style_config
+from adoption.narration_binding import binding_record
+from adoption.audio_mix_binding import binding_record as audio_mix_binding_record
+from packaging import packaging_settings
+
+
+def assembly_settings_payload(work_dir=None, *, audio_mode="narration", audio_stream_index=0):
+    """Settings that affect the rendered video, as a plain nested dict compared with ``==`` by
+    pipeline resume logic. When work_dir is given, a user_subtitles presence flag and the
+    ``{size, mtime_ns}`` identity of the overlay/subtitle-track inputs are included so dropping
+    in or rewriting one of those files rebuilds the cached subtitles."""
+    burn_subtitles = CONFIG["burn_subtitles"]
+    mask_policy = _source_subtitle_mask_policy(work_dir)
+    mask_source_subtitles = mask_policy["active"]
+    overlay_identity = (
+        _artifact_identity(Path(work_dir) / VISUAL_OVERLAYS) if work_dir is not None else None
+    )
+    subtitle_track_identity = (
+        _artifact_identity(Path(work_dir) / "subtitle_track.json")
+        if work_dir is not None else None
+    )
+    settings = {
+        "user_subtitles": _has_user_subtitles(work_dir),
+        "burn_subtitles": burn_subtitles,
+        "force_video_reencode": CONFIG["force_video_reencode"],
+        "encode": {
+            "output_crf": CONFIG["output_crf"],
+            "output_preset": CONFIG["output_preset"],
+            "output_max_height": CONFIG["output_max_height"],
+        },
+        "video_filters": {
+            "mask_source_subtitles": mask_source_subtitles,
+            "source_subtitle_mask_policy": mask_policy["policy"],
+            "source_subtitle_mask_policy_declared": mask_policy["declared"],
+            "source_subtitle_mask_policy_trigger": mask_policy["trigger"],
+            "source_subtitle_mask_ratio": (
+                CONFIG["source_subtitle_mask_ratio"] if mask_source_subtitles else None
+            ),
+            "source_subtitle_mask_timing": (
+                CONFIG["source_subtitle_mask_timing"] if mask_source_subtitles else None
+            ),
+            "subtitle_mask_opacity": (
+                CONFIG["subtitle_mask_opacity"] if mask_source_subtitles else None
+            ),
+            "subtitle_mask_padding": (
+                CONFIG["subtitle_mask_padding"] if mask_source_subtitles else None
+            ),
+            "subtitle_y_top": CONFIG["subtitle_y_top"],
+            "subtitle_y_bot": CONFIG["subtitle_y_bot"],
+            "visual_overlays": {
+                "artifact": VISUAL_OVERLAYS,
+                "present": overlay_identity is not None,
+                "identity": overlay_identity,
+            },
+            "packaging_layers": packaging_settings(work_dir),
+        },
+        "audio": {
+            "mode": audio_mode,
+            "selected_stream_index": audio_stream_index,
+        },
+    }
+    explicit_mix = (
+        audio_mix_binding_record(work_dir)
+        if work_dir is not None and audio_mode == "narration" else None
+    )
+    if explicit_mix:
+        settings["audio"]["path"] = "explicit_adopted_full_sound"
+        settings["audio_mix_binding"] = explicit_mix
+    if audio_mode == "narration":
+        narration_binding = binding_record(work_dir) if work_dir else None
+        settings["narration_input_binding"] = narration_binding
+        adopted_tempo = (
+            narration_binding.get("tempo_policy") if narration_binding else None
+        )
+        settings["narration_timing"] = {
+            "delay_seconds": 0.0 if explicit_mix else CONFIG["narration_delay_seconds"],
+            "tail_pad_seconds": 0.0 if explicit_mix else CONFIG["narration_tail_pad_seconds"],
+            "fade_ms": 0 if explicit_mix else CONFIG["fade_ms"],
+            "narration_speed": (
+                1.0 if explicit_mix else
+                adopted_tempo["global_atempo"] if adopted_tempo else CONFIG["narration_speed"]
+            ),
+            "tempo_source": (
+                "explicit_audio_mix" if explicit_mix else
+                "adoption" if adopted_tempo else "configuration"
+            ),
+            "narration_cumulative_tempo_max": CONFIG["narration_cumulative_tempo_max"],
+            "tts_segment_tempo_max": (
+                adopted_tempo["segment_tempo_max"]
+                if explicit_mix and adopted_tempo else CONFIG["tts_segment_tempo_max"]
+            ),
+        }
+        if explicit_mix and adopted_tempo:
+            settings["narration_timing"]["narration_cumulative_tempo_max"] = \
+                adopted_tempo["cumulative_tempo_max"]
+            settings["narration_timing"]["narration_cumulative_tempo_hard_max"] = \
+                adopted_tempo["cumulative_tempo_hard_max"]
+    if audio_mode in {"narration", "source-mix"} and not explicit_mix:
+        # adopted-packet-copy never decodes or mixes, so mix settings cannot change it.
+        settings["audio_mix"] = {
+            "ducking_mode": CONFIG["ducking_mode"],
+            "duck_fade_seconds": CONFIG["duck_fade_seconds"],
+            "duck_bridge_seconds": CONFIG["duck_bridge_seconds"],
+            "ducking_narr_weight": CONFIG["ducking_narr_weight"],
+            "ducking_orig_volume": CONFIG["ducking_orig_volume"],
+            "idle_orig_volume": CONFIG["idle_orig_volume"],
+            "speech_ducking_volume": CONFIG["speech_ducking_volume"],
+            "zone_ducking_volume": CONFIG["zone_ducking_volume"],
+            "ducking_threshold": CONFIG["ducking_threshold"],
+            "ducking_ratio": CONFIG["ducking_ratio"],
+            "ducking_attack": CONFIG["ducking_attack"],
+            "ducking_release": CONFIG["ducking_release"],
+            "ducking_level_sc": CONFIG["ducking_level_sc"],
+            "ducking_makeup": CONFIG["ducking_makeup"],
+            "final_loudnorm": final_loudnorm_filter(),
+            "loudness_mode": _loudness_mode(),
+            "bgm_path": CONFIG["bgm_path"],
+            "bgm_volume": CONFIG["bgm_volume"],
+            "bgm_ducking_volume": CONFIG["bgm_ducking_volume"],
+        }
+    if burn_subtitles:
+        settings["subtitle_renderer"] = "ass"
+        settings["subtitle_style"] = _subtitle_style_config()
+    if subtitle_track_identity is not None:
+        settings["subtitle_track"] = {
+            "artifact": "subtitle_track.json",
+            "identity": subtitle_track_identity,
+        }
+    return settings

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/audio_automation.py

@@ -0,0 +1,195 @@
+"""Shared audio automation semantics for ffmpeg render and editable timelines.
+
+This module is stdlib-only and is the single source for ducking window coalescing,
+pre-roll/hold/post-roll gain shape, timeline keyframes, and ffmpeg volume terms.
+"""
+
+
+def _round_keyframe(t_s, gain):
+    return {"t": round(float(t_s), 4), "gain": round(float(gain), 4)}
+
+
+def default_bridge(fade):
+    return 2 * float(fade)
+
+
+def coalesce_duck_windows(windows, bridge):
+    """Merge [(start, end, gain)] windows separated by gaps below `bridge`.
+
+    A bridged mixed-level span uses the lowest gain across all members so neither
+    ffmpeg nor timeline export swells louder in the bridged gap.
+    """
+    rel = sorted(
+        ([float(s), float(e), float(g)] for s, e, g in windows if float(e) > float(s)),
+        key=lambda w: w[0],
+    )
+    if not rel:
+        return []
+    bridge = float(bridge)
+    merged = [rel[0][:]]
+    for s, e, gain in rel[1:]:
+        if s - merged[-1][1] < bridge:
+            merged[-1][1] = max(merged[-1][1], e)
+            merged[-1][2] = min(merged[-1][2], gain)
+        else:
+            merged.append([s, e, gain])
+    return merged
+
+
+def _t_minus(value):
+    value = float(value)
+    if value < 0:
+        return f"t+{abs(value):.2f}"
+    return f"t-{value:.2f}"
+
+
+def duck_ramp_expression(start, end, fade):
+    """Return ffmpeg expression for the canonical duck shape.
+
+    Semantics: ramp down during [start-fade, start], hold fully ducked on
+    [start, end], and release during [end, end+fade].
+    """
+    start = float(start)
+    end = float(end)
+    fade = float(fade)
+    if fade <= 0:
+        return f"between(t,{start:.2f},{end:.2f})"
+    ramp_start = start - fade
+    ramp_end = end + fade
+    return f"min(1,max(0,min({_t_minus(ramp_start)},{ramp_end:.2f}-t)/{fade:.2f}))"
+
+
+def ducking_expression(windows, idle, fade):
+    """Build the ffmpeg volume expression for coalesced duck windows."""
+    if not windows:
+        return None
+    idle = float(idle)
+    terms = [
+        f"+({float(level) - idle:.3f})*{duck_ramp_expression(s, e, fade)}"
+        for s, e, level in windows
+    ]
+    return f"max(0,min(1,{idle}{''.join(terms)}))"
+
+
+def coalesce_release_duck_windows(windows, bridge):
+    """Merge [(start, hold_end, gain, restore_at)] while preserving safe releases."""
+    rel = sorted(
+        ([float(s), float(e), float(g), max(float(e), float(r))] for s, e, g, r in windows if float(e) > float(s)),
+        key=lambda row: row[0],
+    )
+    if not rel:
+        return []
+    bridge = float(bridge)
+    merged = [rel[0][:]]
+    for start, end, gain, restore in rel[1:]:
+        if start - merged[-1][1] < bridge:
+            merged[-1][1] = max(merged[-1][1], end)
+            merged[-1][2] = min(merged[-1][2], gain)
+            merged[-1][3] = max(merged[-1][1], merged[-1][3], restore)
+        else:
+            merged.append([start, end, gain, restore])
+    return merged
+
+
+def release_ducking_expression(windows, idle, attack_fade, bridge=None):
+    """FFmpeg gain expression with a fixed attack and a per-window safe release end."""
+    attack = float(attack_fade)
+    if bridge is None:
+        bridge = default_bridge(attack)
+    merged = coalesce_release_duck_windows(windows, bridge)
+    if not merged:
+        return None
+    idle = float(idle)
+    terms = []
+    for start, hold_end, level, restore_at in merged:
+        if attack > 0:
+            attack_term = f"({_t_minus(start - attack)})/{attack:.4f}"
+        else:
+            attack_term = f"between(t,{start:.4f},{restore_at:.4f})"
+        release = restore_at - hold_end
+        if release > 1e-6:
+            release_term = f"({restore_at:.4f}-t)/{release:.4f}"
+            mask = f"min(1,max(0,min({attack_term},{release_term})))"
+        else:
+            mask = f"between(t,{start:.4f},{hold_end:.4f})"
+        terms.append(f"+({float(level) - idle:.3f})*{mask}")
+    return f"max(0,min(1,{idle}{''.join(terms)}))"
+
+
+def release_ducking_keyframes(windows, idle, attack_fade, span_start, span_end, bridge=None):
+    """Timeline keyframes matching `release_ducking_expression` exactly."""
+    attack = float(attack_fade)
+    if bridge is None:
+        bridge = default_bridge(attack)
+    span_start, span_end = float(span_start), float(span_end)
+    normalized = [
+        (max(span_start, start), min(span_end, end), gain, min(span_end, max(end, restore)))
+        for start, end, gain, restore in ((float(s), float(e), float(g), float(r)) for s, e, g, r in windows)
+        if end > span_start and start < span_end and end > start
+    ]
+    merged = coalesce_release_duck_windows(normalized, bridge)
+    if not merged:
+        return []
+    points = [(span_start, float(idle))]
+    for start, hold_end, level, restore_at in merged:
+        points.extend([
+            (max(span_start, start - attack), float(idle)),
+            (start, level),
+            (hold_end, level),
+            (restore_at, float(idle)),
+        ])
+    points.append((span_end, float(idle)))
+    points.sort(key=lambda point: point[0])
+    out = []
+    for when, gain in points:
+        if out and abs(out[-1][0] - when) < 1e-4:
+            out[-1] = (when, min(out[-1][1], gain))
+        else:
+            out.append((when, gain))
+    return [_round_keyframe(when, gain) for when, gain in out]
+
+
+def variable_ducking_keyframes(windows, idle, fade, span_start, span_end, bridge=None):
+    """Volume keyframes for per-window duck gains using canonical semantics."""
+    fade = float(fade)
+    if bridge is None:
+        bridge = default_bridge(fade)
+    span_start = float(span_start)
+    span_end = float(span_end)
+    rel = sorted(
+        (max(span_start, float(w[0])), min(span_end, float(w[1])), float(w[2]))
+        for w in windows
+        if float(w[1]) > span_start and float(w[0]) < span_end and float(w[1]) > float(w[0])
+    )
+    merged = coalesce_duck_windows(rel, bridge)
+    if not merged:
+        return []
+
+    pts = [(span_start, float(idle))]
+    for s, e, level in merged:
+        pts.append((max(span_start, s - fade), float(idle)))
+        pts.append((s, level))
+        pts.append((e, level))
+        pts.append((min(span_end, e + fade), float(idle)))
+    pts.append((span_end, float(idle)))
+
+    pts.sort(key=lambda p: p[0])
+    out = []
+    for t, gain in pts:
+        if out and abs(out[-1][0] - t) < 1e-4:
+            out[-1] = (t, min(out[-1][1], gain))
+        else:
+            out.append((t, gain))
+    return [_round_keyframe(t, gain) for t, gain in out]
+
+
+def fixed_ducking_keyframes(windows, idle, duck, fade, span_start, span_end, bridge=None):
+    """Volume keyframes for fixed-gain duck windows using canonical semantics."""
+    return variable_ducking_keyframes(
+        [(float(s), float(e), float(duck)) for s, e in windows],
+        idle,
+        fade,
+        span_start,
+        span_end,
+        bridge=bridge,
+    )