@oh-story/dsh 0.1.3 → 0.1.5

package/lib/video-recap/skills/video-assemble/scripts/assembly_contract.py

@@ -0,0 +1,305 @@
+"""Assembly manifest/QC persistence and delivery contract helpers."""
+
+import json
+import math
+import wave
+from pathlib import Path
+
+from lib import CONFIG
+from assemble_constants import (
+    ASSEMBLY_MANIFEST,
+    ASSEMBLY_QC,
+    SEGMENT_AUDIO_SCHEMA_VERSION,
+    VISUAL_QC,
+)
+from audio_mix import _loudness_mode
+from artifacts import (
+    _load_work_json,
+    _source_video_identity,
+    _timeline_provenance_status,
+)
+
+def _assembly_manifest_payload(input_video, tts_segments, work_dir, output_path,
+                               tts_meta_path=None, final_output=None, *, settings_fingerprint):
+    """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, source_video_fingerprint = _source_video_identity()
+    qc_path = Path(work_dir) / ASSEMBLY_QC
+    qc = _load_work_json(work_dir, ASSEMBLY_QC) if qc_path.exists() else None
+    payload = {
+        "schema_version": 2,
+        "input_video": str(input_video.resolve()),
+        "source_video": source_video,
+        "source_video_fingerprint": source_video_fingerprint,
+        "tts_meta": str(Path(tts_meta_path).resolve()) if tts_meta_path else None,
+        "tts_segments": len(tts_segments or []),
+        "assembly_settings": settings_fingerprint(work_dir),
+        "output_path": str(output_path.resolve()),
+        "segment_audio_schema_version": SEGMENT_AUDIO_SCHEMA_VERSION,
+        "qc_path": str(qc_path.resolve()) if qc_path.exists() else None,
+        "qc_verdict": qc.get("verdict") if isinstance(qc, dict) else None,
+        "qc_blocking_codes": qc.get("blocking_codes", []) if isinstance(qc, dict) else [],
+        # The settings fingerprint 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.get("loudness_mode") if isinstance(qc, dict) else None,
+        "qc_loudnorm_measurement": qc.get("loudnorm_measurement") if isinstance(qc, dict) else None,
+        "audio_segments": [
+            {
+                "index": seg.get("index"),
+                "segment_audio_schema_version": seg.get("segment_audio_schema_version", SEGMENT_AUDIO_SCHEMA_VERSION),
+                "narration": seg.get("narration", ""),
+                "spoken_text": seg.get("spoken_text") or seg.get("narration", ""),
+                "truncated": bool(seg.get("truncated", False)),
+                "truncate_reason": seg.get("truncate_reason", "none"),
+                "fit_status": seg.get("fit_status"),
+                "blocking": bool(seg.get("blocking", False)),
+                "audio_duration": seg.get("audio_duration"),
+                "placed_audio_duration": seg.get("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.get("global_narration_speed"),
+                "segment_tempo_factor": seg.get("segment_tempo_factor"),
+                "effective_tempo": seg.get("effective_tempo"),
+                "rms_dbfs_before": seg.get("rms_dbfs_before"),
+                "rms_dbfs_after": seg.get("rms_dbfs_after"),
+                "peak_after": seg.get("peak_after"),
+            }
+            for seg in (tts_segments or [])
+            if isinstance(seg, dict)
+        ],
+    }
+    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
+    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):
+    if not isinstance(visual_qc, dict):
+        return {
+            "present": False,
+            "verdict": "MISSING",
+            "blocking": True,
+            "blocking_codes": ["missing_visual_qc"],
+            "summary": {},
+        }
+    subtitles = visual_qc.get("subtitles") or visual_qc.get("subtitle") or {}
+    overlays = visual_qc.get("overlays") or visual_qc.get("overlay") or {}
+    return {
+        "present": True,
+        "artifact": visual_qc.get("artifact", VISUAL_QC),
+        "verdict": visual_qc.get("verdict"),
+        "blocking": bool(visual_qc.get("blocking", False)),
+        "blocking_codes": list(visual_qc.get("blocking_codes") or []),
+        "summary": visual_qc.get("summary", {}),
+        "geometry": visual_qc.get("geometry", {}),
+        "subtitles": {
+            "entries": subtitles.get("entries", 0),
+            "multi_line": subtitles.get("multi_line", False),
+            "overflow": subtitles.get("overflow", False),
+            "safe_area": subtitles.get("safe_area", {}),
+        },
+        "subtitle": subtitles,
+        "mask": visual_qc.get("mask", {}),
+        "overlays": {
+            "present": overlays.get("present", bool(overlays.get("items"))),
+            "rendered": overlays.get("rendered", len(overlays.get("items", [])) if isinstance(overlays.get("items"), list) else 0),
+            "unsupported": overlays.get("unsupported", []),
+            "overflow": overlays.get("overflow", []),
+        },
+        "overlay": overlays,
+    }
+
+
+def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
+                       source_has_audio=None, loudness_mode=None, loudnorm_measurement=None,
+                       visual_qc=None, render_delivery=None, delivery_qc=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 = float(CONFIG.get("narration_cumulative_tempo_hard_max", 1.40) or 1.40)
+    segments = [s for s in (tts_segments or []) if isinstance(s, dict)]
+    no_safe = [
+        int(s.get("index", i))
+        for i, s in enumerate(segments)
+        if s.get("fit_status") == "no_safe_fit"
+        or s.get("truncate_reason") in {"no_safe_boundary", "no_room"}
+        or bool(s.get("blocking", False))
+    ]
+    skipped = [
+        int(s.get("index", i))
+        for i, s in enumerate(segments)
+        if s.get("fit_status") == "skipped"
+    ]
+    fit_failed = [
+        int(s.get("index", i))
+        for i, s in enumerate(segments)
+        if s.get("fit_status") == "speed_adjust_failed"
+    ]
+    tempo_exceeded = []
+    truncated = []
+    handoff_failed = []
+    timeline_audio_failed = []
+    max_effective = 0.0
+    for i, s in enumerate(segments):
+        try:
+            eff = float(s.get("effective_tempo", 0.0) or 0.0)
+        except (TypeError, ValueError):
+            eff = 0.0
+        max_effective = max(max_effective, eff)
+        if eff > hard_max + 1e-6:
+            tempo_exceeded.append(int(s.get("index", i)))
+        if bool(s.get("truncated", False)) or s.get("truncate_reason") == "tail_trim_tolerance":
+            truncated.append(int(s.get("index", i)))
+        if bool(s.get("source_handoff_blocking", False)):
+            handoff_failed.append(int(s.get("index", i)))
+        if s.get("actual_place_start") is not None and float(s.get("placed_audio_duration", 0.0) or 0.0) > 0:
+            placed_path = s.get("placed_audio_path")
+            valid_placed_file = False
+            if placed_path and Path(placed_path).exists():
+                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()
+                    timeline_start = round(float(s.get("actual_place_start")), 4)
+                    timeline_end = math.ceil(
+                        float(s.get("actual_place_end")) * 10_000 - 1e-9
+                    ) / 10_000
+                    serialized_span = timeline_end - timeline_start
+                    valid_placed_file = abs(
+                        placed_duration - float(s.get("placed_audio_duration") or 0.0)
+                    ) <= tolerance + 1e-9 and serialized_span + 1e-9 >= placed_duration
+                except (OSError, wave.Error, ZeroDivisionError, TypeError, ValueError):
+                    valid_placed_file = False
+            if not valid_placed_file:
+                timeline_audio_failed.append(int(s.get("index", i)))
+
+    placed = [
+        float(s.get("placed_audio_duration", 0.0) or 0.0)
+        for s in segments
+        if s.get("placed_audio_duration") is not None
+    ]
+    blocking_codes = []
+    if not segments:
+        blocking_codes.append("missing_narration")
+    if skipped:
+        blocking_codes.append("skipped_segments")
+    if fit_failed:
+        blocking_codes.append("fit_failed")
+    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.get("blocking"):
+        blocking_codes.append("visual_qc_failed")
+    if 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")
+
+    render_delivery = render_delivery or delivery_qc or {}
+    qc_payload = {
+        "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 or 0.0), 4),
+        "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.get("verdict"),
+            "delivery_qc": "PASS",
+            "audio_qc": "FAIL" if any(
+                c in blocking_codes
+                for c in (
+                    "missing_narration", "skipped_segments", "fit_failed", "no_safe_fit",
+                    "effective_tempo_exceeded", "empty_narration", "truncated_speech",
+                    "unsafe_source_handoff",
+                    "timeline_audio_mismatch",
+                )
+            ) else "PASS",
+        },
+        "visual_qc": visual_rollup,
+        "delivery_qc": {
+            "video_encode_passes": render_delivery.get("video_encode_passes"),
+            "reencode_reason": render_delivery.get("reencode_reason"),
+            "audio_sample_rate": render_delivery.get("audio_sample_rate"),
+            "final_compat_notes": render_delivery.get("final_compat_notes", []),
+        },
+        "summary": {
+            "segments": len(segments),
+            "placed_segments": sum(1 for x in placed if x > 0.0),
+            "skipped_segments": skipped,
+            "fit_failed_segments": fit_failed,
+            "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,
+    }
+    qc_payload["visual_rollup"] = visual_rollup
+    qc_payload["delivery_rollup"] = qc_payload["delivery_qc"]
+    return qc_payload
+
+
+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/lib/video-recap/skills/video-assemble/scripts/assembly_settings.py

@@ -0,0 +1,94 @@
+"""Render-affecting settings fingerprint for cache/resume decisions."""
+
+from pathlib import Path
+
+from artifacts import _artifact_fingerprint
+from assemble_constants import (
+    SUBTITLE_RENDER_VERSION,
+    SUBTITLE_TEXT_NORMALIZE_VERSION,
+    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 subtitle_core import _subtitle_style_config
+
+def assembly_settings_fingerprint(work_dir=None):
+    """Settings that affect the rendered video, used by pipeline resume cache. When work_dir is
+    given, a user_subtitles presence flag is included so dropping in a user-subtitle file rebuilds
+    the cached subtitles."""
+    burn_subtitles = bool(CONFIG.get("burn_subtitles", False))
+    mask_policy = _source_subtitle_mask_policy(work_dir)
+    mask_source_subtitles = bool(mask_policy["active"])
+    user_subtitles = _has_user_subtitles(work_dir)
+    overlay_path = Path(work_dir) / VISUAL_OVERLAYS if work_dir is not None else None
+    fingerprint = {
+        "version": SUBTITLE_RENDER_VERSION,
+        "subtitle_text_normalize": SUBTITLE_TEXT_NORMALIZE_VERSION,
+        "user_subtitles": user_subtitles,
+        "burn_subtitles": burn_subtitles,
+        "force_video_reencode": bool(CONFIG.get("force_video_reencode", False)),
+        "encode": {
+            "output_crf": CONFIG.get("output_crf", 18),
+            "output_preset": CONFIG.get("output_preset", "veryfast"),
+            "output_max_height": CONFIG.get("output_max_height", 0),
+        },
+        "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.get("source_subtitle_mask_ratio", 0.14) if mask_source_subtitles else None
+            ),
+            "source_subtitle_mask_timing": (
+                CONFIG.get("source_subtitle_mask_timing", "narration") if mask_source_subtitles else None
+            ),
+            "subtitle_mask_opacity": (
+                CONFIG.get("subtitle_mask_opacity", 0.6) if mask_source_subtitles else None
+            ),
+            "subtitle_mask_padding": (
+                CONFIG.get("subtitle_mask_padding", 4) if mask_source_subtitles else None
+            ),
+            "subtitle_y_top": CONFIG.get("subtitle_y_top", -1),
+            "subtitle_y_bot": CONFIG.get("subtitle_y_bot", -1),
+            "visual_overlays": {
+                "artifact": VISUAL_OVERLAYS,
+                "present": bool(overlay_path and overlay_path.exists()),
+                "fingerprint": _artifact_fingerprint(overlay_path) if overlay_path and overlay_path.exists() else None,
+            },
+        },
+        "narration_timing": {
+            "delay_seconds": CONFIG.get("narration_delay_seconds", 0.0),
+            "tail_pad_seconds": CONFIG.get("narration_tail_pad_seconds", 0.1),
+            "fade_ms": CONFIG.get("fade_ms", 120),
+            "narration_speed": CONFIG.get("narration_speed", 1.0),
+            "narration_cumulative_tempo_max": CONFIG.get("narration_cumulative_tempo_max", 1.35),
+            "tts_segment_tempo_max": CONFIG.get("tts_segment_tempo_max", 1.20),
+        },
+        "audio_mix": {
+            "ducking_mode": CONFIG.get("ducking_mode", "fixed"),
+            "duck_fade_seconds": CONFIG.get("duck_fade_seconds", 0.3),
+            "duck_bridge_seconds": CONFIG.get("duck_bridge_seconds", 1.5),
+            "ducking_narr_weight": CONFIG.get("ducking_narr_weight", 1.5),
+            "ducking_orig_volume": CONFIG.get("ducking_orig_volume", 0.3),
+            "idle_orig_volume": CONFIG.get("idle_orig_volume", 1.0),
+            "speech_ducking_volume": CONFIG.get("speech_ducking_volume", 0.2),
+            "zone_ducking_volume": CONFIG.get("zone_ducking_volume", 0.12),
+            "ducking_threshold": CONFIG.get("ducking_threshold", 0.15),
+            "ducking_ratio": CONFIG.get("ducking_ratio", 3),
+            "ducking_attack": CONFIG.get("ducking_attack", 10),
+            "ducking_release": CONFIG.get("ducking_release", 300),
+            "ducking_level_sc": CONFIG.get("ducking_level_sc", 2.0),
+            "ducking_makeup": CONFIG.get("ducking_makeup", 1.2),
+            "final_loudnorm": final_loudnorm_filter(),
+            "loudness_mode": _loudness_mode(),
+            "bgm_path": CONFIG.get("bgm_path", ""),
+            "bgm_volume": CONFIG.get("bgm_volume", 0.18),
+            "bgm_ducking_volume": CONFIG.get("bgm_ducking_volume", 0.10),
+        },
+    }
+    if burn_subtitles:
+        fingerprint["subtitle_renderer"] = "ass"
+        fingerprint["subtitle_style"] = _subtitle_style_config()
+    return fingerprint

package/lib/video-recap/skills/video-assemble/scripts/audio_automation.py

@@ -0,0 +1,205 @@
+"""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 or 0)
+
+
+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 or 0)
+    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 or 0)
+    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."""
+    merged = list(windows or [])
+    if not merged:
+        return None
+    idle = float(idle)
+    terms = [
+        f"+({float(level) - idle:.3f})*{duck_ramp_expression(s, e, fade)}"
+        for s, e, level in merged
+    ]
+    return f"max(0,min(1,{idle}{''.join(terms)}))"
+
+
+def coalesce_release_duck_windows(windows, bridge, default_release_fade=0.0):
+    """Merge [(start, hold_end, gain, restore_at?)] while preserving safe releases."""
+    fade = max(0.0, float(default_release_fade or 0.0))
+    rel = []
+    for row in windows or []:
+        if len(row) < 3:
+            continue
+        start, end, gain = map(float, row[:3])
+        restore = float(row[3]) if len(row) > 3 and row[3] is not None else end + fade
+        if end > start:
+            rel.append([start, end, gain, max(end, restore)])
+    rel.sort(key=lambda row: row[0])
+    if not rel:
+        return []
+    bridge = max(0.0, float(bridge or 0.0))
+    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 = max(0.0, float(attack_fade or 0.0))
+    if bridge is None:
+        bridge = default_bridge(attack)
+    merged = coalesce_release_duck_windows(windows, bridge, attack)
+    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 = max(0.0, float(attack_fade or 0.0))
+    if bridge is None:
+        bridge = default_bridge(attack)
+    span_start, span_end = float(span_start), float(span_end)
+    normalized = []
+    for row in windows or []:
+        if len(row) < 3:
+            continue
+        start, end, gain = map(float, row[:3])
+        restore = float(row[3]) if len(row) > 3 and row[3] is not None else end + attack
+        if end > span_start and start < span_end and end > start:
+            normalized.append((max(span_start, start), min(span_end, end), gain, min(span_end, max(end, restore))))
+    merged = coalesce_release_duck_windows(normalized, bridge, attack)
+    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 or 0)
+    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,
+    )