ffmpeg-skill 0.4.0 → 0.5.0

package/scripts/loudness.py

@@ -18,11 +18,13 @@ import os
 import re
 import sys
 
-from _common import add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
 
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
+    if STATE["dry_run"]:
+        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0"}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
     proc = run(cmd, check=False)

package/scripts/multicam.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import List, Tuple
 
-from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, x264_args
 from sync import measure_offset
 
 
@@ -154,7 +154,8 @@ def main() -> int:
         w, h = h, w
     fps = args.fps or v0.get("fps") or 30.0
     fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
-    geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps={fps:g},format=yuv420p"
+    pixfmt = "yuv420p10le" if v0.get("hdr") else "yuv420p"
+    geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps={fps:g},format={pixfmt}"
 
     cmd = ffmpeg_base()
     for p in args.inputs:
@@ -184,7 +185,7 @@ def main() -> int:
 
     output = args.output or default_output(args.inputs[0], "multicam", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += x264_args(args.crf, args.preset) + aac_args() + ["-shortest", output]
+    cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + ["-shortest", output]
     run(cmd)
     r = probe(output)
     info(f"wrote {output} ({r['duration']:.3f}s, {len(filled)} cuts, audio from input {a})")

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -140,7 +140,7 @@ def main() -> int:
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
         fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
-        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a?", "-shortest"]
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a:0?", "-shortest"]
     else:
         x, y = position_exprs(args.position, args.margin, text_mode=True)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
@@ -159,7 +159,7 @@ def main() -> int:
             opts.append(f"enable='{enable}'")
         cmd += ["-vf", "drawtext=" + ":".join(opts)]
 
-    cmd += x264_args(args.crf, args.preset) + cfr_args(meta)
+    cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
     cmd.append(output)
     run(cmd)

package/scripts/render.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Declarative edits: describe the whole edit in one project.json and render it
+in one command. Change a number, re-render. Non-destructive: sources are never
+touched, intermediates live in a work directory.
+
+Project format (all keys optional except clips):
+{
+  "output": "final.mp4",
+  "frame": {"aspect": "9:16", "width": 1080, "fps": 30},
+  "clips": [
+    {"src": "a.mp4", "in": "0:05", "out": "0:20"},
+    {"src": "b.mp4", "in": 3, "out": 12, "speed": 1.25},
+    {"src": "c.mp4"}
+  ],
+  "transition": {"type": "fade", "duration": 0.5},
+  "silence": {"threshold": -38, "min_silence": 0.8},
+  "captions": {"text": "cues.txt", "srt": null, "animate": "pop", "karaoke": true, "font": "Noto Sans CJK JP", "size": 28, "position": "bottom"},
+  "overlays": [
+    {"image": "logo.png", "position": "top-right", "scale": 160, "opacity": 0.9},
+    {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}
+  ],
+  "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "fade_out": 2},
+  "loudness": {"lufs": -14, "tp": -1},
+  "fit": {"duration": 60},
+  "export": {"preset": "reels"},
+  "check": {"platform": "reels"}
+}
+
+Stages run in this order: clips (cut) → join → silence → fit → captions →
+overlays → audio → loudness → export → check. Missing stages are skipped.
+
+Examples:
+  python3 render.py --init project.json          # write a commented starter project
+  python3 render.py project.json                 # render
+  python3 render.py project.json --dry-run       # show every command without rendering
+  python3 render.py project.json --fast          # preview quality
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from _common import STATE, add_common, apply_common, die, emit, info, probe
+
+HERE = Path(__file__).resolve().parent
+
+TEMPLATE = {
+    "output": "final.mp4",
+    "frame": {"aspect": "16:9", "width": 1920, "fps": 30},
+    "clips": [{"src": "REPLACE_ME.mp4", "in": "0:00", "out": "0:30"}],
+    "transition": {"type": "fade", "duration": 0.5},
+    "silence": None,
+    "captions": None,
+    "overlays": [],
+    "audio": None,
+    "loudness": {"lufs": -14, "tp": -1},
+    "fit": None,
+    "export": {"preset": "youtube"},
+    "check": {"platform": "youtube"},
+}
+
+
+def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
+    """Run a sibling script, forwarding --fast / --dry-run, returning its printed output path."""
+    cmd = [sys.executable, str(HERE / script)] + [str(a) for a in argv] + (extra or [])
+    if STATE["fast"]:
+        cmd.append("--fast")
+    if STATE["dry_run"]:
+        cmd.append("--dry-run")
+    info("→ " + " ".join(os.path.basename(c) if i < 2 else c for i, c in enumerate(cmd)))
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    for line in proc.stderr.splitlines():
+        if line.startswith("$ ") or line.startswith("[dry-run]"):
+            STATE["commands"].append(line[2:] if line.startswith("$ ") else line)
+        elif line.strip():
+            info("    " + line)
+    if proc.returncode != 0:
+        die(f"{script} failed")
+    out = proc.stdout.strip().splitlines()
+    return out[-1] if out else ""
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("project", nargs="?", help="project.json")
+    ap.add_argument("--init", metavar="FILE", help="write a starter project file and exit")
+    ap.add_argument("--work", help="work directory for intermediates (default: <output>_work)")
+    ap.add_argument("--keep", action="store_true", help="keep intermediates (default: kept only when --work is given)")
+    ap.add_argument("--stop-after", choices=["clips", "join", "silence", "fit", "captions", "overlays", "audio", "loudness", "export"], help="stop after this stage (for iterating)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.init:
+        Path(args.init).write_text(json.dumps(TEMPLATE, indent=2) + "\n", encoding="utf-8")
+        info(f"wrote {args.init}; edit clips/src and run: render.py {args.init}")
+        print(args.init)
+        return 0
+    if not args.project:
+        die("give a project.json (or --init FILE)")
+    try:
+        proj: Dict[str, Any] = json.loads(Path(args.project).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        die(f"cannot read project: {exc}")
+    base = Path(args.project).resolve().parent
+
+    def rel(p: Any) -> str:
+        p = str(p)
+        return p if os.path.isabs(p) else str(base / p)
+
+    clips = proj.get("clips") or []
+    if not clips:
+        die("project.clips is empty")
+    output = rel(proj.get("output") or "final.mp4")
+    work = Path(args.work) if args.work else Path(str(Path(output).with_suffix("")) + "_work")
+    work.mkdir(parents=True, exist_ok=True)
+    frame = proj.get("frame") or {}
+    trans = proj.get("transition") or {}
+    stages_done: List[str] = []
+
+    # ---- clips
+    parts: List[str] = []
+    for i, c in enumerate(clips):
+        src = rel(c["src"])
+        if not STATE["dry_run"]:
+            probe(src)
+        needs_cut = c.get("in") is not None or c.get("out") is not None
+        part = str(work / f"clip{i:02d}.mp4")
+        if needs_cut:
+            argv: List[Any] = [src, "-o", part, "--accurate"]
+            if c.get("in") is not None:
+                argv += ["--start", c["in"]]
+            if c.get("out") is not None:
+                argv += ["--end", c["out"]]
+            sh("cut.py", *argv)
+        else:
+            part = src
+        if c.get("speed"):
+            spd = float(c["speed"])
+            dur = (probe(part).get("duration") or 0.0) if not STATE["dry_run"] else 10.0
+            fitted = str(work / f"clip{i:02d}_speed.mp4")
+            sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)
+            part = fitted
+        parts.append(part)
+    stages_done.append("clips")
+    current = parts[0]
+    if args.stop_after == "clips":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- join
+    if len(parts) > 1:
+        current = str(work / "joined.mp4")
+        argv = list(parts) + ["-o", current, "--transition", trans.get("type", "fade"), "--duration", str(trans.get("duration", 0.5))]
+        if frame.get("width"):
+            argv += ["--width", str(frame["width"])]
+        if frame.get("height"):
+            argv += ["--height", str(frame["height"])]
+        if frame.get("fps"):
+            argv += ["--fps", str(frame["fps"])]
+        sh("join.py", *argv)
+        stages_done.append("join")
+    if args.stop_after == "join":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- silence
+    sil = proj.get("silence")
+    if sil:
+        nxt = str(work / "tight.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin")):
+            if sil.get(k) is not None:
+                argv += [flag, str(sil[k])]
+        sh("silence.py", *argv)
+        current = nxt
+        stages_done.append("silence")
+    if args.stop_after == "silence":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- fit (duration and/or frame)
+    fit = dict(proj.get("fit") or {})
+    if frame.get("aspect"):
+        fit.setdefault("aspect", frame["aspect"])
+    if frame.get("width") and len(parts) == 1:
+        fit.setdefault("width", frame["width"])
+    if frame.get("fps") and len(parts) == 1:
+        fit.setdefault("fps", frame["fps"])
+    if fit:
+        nxt = str(work / "fit.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("fps", "--fps"), ("smooth", "--smooth")):
+            if fit.get(k) is not None:
+                argv += [flag, str(fit[k])]
+        sh("fit.py", *argv)
+        current = nxt
+        stages_done.append("fit")
+    if args.stop_after == "fit":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- captions
+    cap = proj.get("captions")
+    if cap:
+        nxt = str(work / "captioned.mp4")
+        argv = [current, "-o", nxt]
+        if cap.get("text"):
+            argv += ["--text", rel(cap["text"])]
+        elif cap.get("srt"):
+            argv += ["--srt", rel(cap["srt"])]
+        elif cap.get("ass"):
+            argv += ["--ass", rel(cap["ass"])]
+        else:
+            die("captions needs text, srt or ass")
+        for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline")):
+            if cap.get(k) is not None:
+                argv += [flag, str(cap[k])]
+        for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):
+            if cap.get(k):
+                argv.append(flag)
+        sh("caption.py", *argv)
+        current = nxt
+        stages_done.append("captions")
+    if args.stop_after == "captions":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- overlays
+    for i, ov in enumerate(proj.get("overlays") or []):
+        nxt = str(work / f"overlay{i:02d}.mp4")
+        argv = [current, "-o", nxt]
+        if ov.get("image"):
+            argv += ["--image", rel(ov["image"])]
+        elif ov.get("text"):
+            argv += ["--text", ov["text"]]
+        else:
+            die(f"overlays[{i}] needs image or text")
+        for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin")):
+            if ov.get(k) is not None:
+                argv += [flag, str(ov[k])]
+        if ov.get("box"):
+            argv.append("--box")
+        sh("overlay.py", *argv)
+        current = nxt
+        if "overlays" not in stages_done:
+            stages_done.append("overlays")
+    if args.stop_after == "overlays":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- audio
+    au = proj.get("audio")
+    if au:
+        nxt = str(work / "audio.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("music", "--music"), ("replace", "--replace")):
+            if au.get(k):
+                argv += [flag, rel(au[k])]
+        for k, flag in (("music_volume", "--music-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount")):
+            if au.get(k) is not None:
+                argv += [flag, str(au[k])]
+        for k, flag in (("voice", "--voice"), ("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):
+            if au.get(k):
+                argv.append(flag)
+        sh("audio.py", *argv)
+        current = nxt
+        stages_done.append("audio")
+    if args.stop_after == "audio":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- loudness
+    ld = proj.get("loudness")
+    if ld:
+        nxt = str(work / "loudnorm.mp4")
+        argv = [current, "-o", nxt]
+        if ld.get("lufs") is not None:
+            argv += ["-I", str(ld["lufs"])]
+        if ld.get("tp") is not None:
+            argv += ["--tp", str(ld["tp"])]
+        sh("loudness.py", *argv)
+        current = nxt
+        stages_done.append("loudness")
+    if args.stop_after == "loudness":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- export
+    ex = proj.get("export")
+    if ex and ex.get("preset"):
+        argv = [current, "--preset", ex["preset"], "-o", output]
+        if ex.get("fit"):
+            argv += ["--fit", ex["fit"]]
+        if ex.get("crf") is not None:
+            argv += ["--crf", str(ex["crf"])]
+        sh("export.py", *argv)
+        stages_done.append("export")
+    else:
+        if not STATE["dry_run"]:
+            import shutil
+            shutil.copyfile(current, output)
+        info(f"copied final stage to {output}")
+    current = output
+
+    # ---- check
+    ck = proj.get("check")
+    check_result = None
+    if ck and ck.get("platform") and not STATE["dry_run"]:
+        proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        try:
+            check_result = json.loads(proc.stdout)
+        except ValueError:
+            check_result = {"error": proc.stderr.strip()[-300:]}
+        if check_result.get("failed"):
+            info(f"check: {check_result['failed']} FAIL — " + "; ".join(f"{r['check']}={r['value']} ({r['fix']})" for r in check_result["checks"] if r["status"] == "FAIL"))
+        else:
+            info(f"check: OK for {ck['platform']}")
+        stages_done.append("check")
+
+    if not args.keep and not args.work and not STATE["dry_run"]:
+        import shutil
+        shutil.rmtree(work, ignore_errors=True)
+    info(f"rendered {output} via {' → '.join(stages_done)}")
+    emit(output, stages=stages_done, check=check_result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/scenes.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Find scene changes and loud moments, and propose highlight candidates so the
+agent can plan an edit or a digest without watching the whole file.
+
+Scene cuts come from ffmpeg's scdet; energy peaks from a 0.5 s RMS envelope
+of the audio. Highlight candidates are the scenes ranked by audio energy
+(and, optionally, by motion).
+
+Examples:
+  python3 scenes.py talk.mp4                                # scenes + peaks, JSON
+  python3 scenes.py event.mp4 --highlights 5 --target 60   # 5 candidate ranges summing to ~60 s
+  python3 scenes.py event.mp4 --highlights 4 --edl picks.txt   # cut.py --segments compatible list
+  python3 scenes.py event.mp4 --sheet scenes.png             # one thumbnail per scene
+"""
+import argparse
+import math
+import os
+import re
+import struct
+import subprocess
+import sys
+from typing import Dict, List, Tuple
+
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run
+
+SCENE_RE = re.compile(r"lavfi\.scd\.time=([0-9.]+)")
+
+
+def detect_scenes(path: str, threshold: float, min_len: float, duration: float) -> List[float]:
+    ffmpeg = require_tool("ffmpeg")
+    proc = subprocess.run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
+                           f"scale=320:-2,scdet=threshold={threshold}:sc_pass=1,metadata=print:file=-", "-f", "null", "-"],
+                          stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    times = [float(t) for t in SCENE_RE.findall(proc.stdout)]
+    cuts = [0.0]
+    for t in times:
+        if t - cuts[-1] >= min_len:
+            cuts.append(t)
+    if duration - cuts[-1] < min_len and len(cuts) > 1:
+        cuts.pop()
+    return cuts
+
+
+def audio_envelope(path: str, step_s: float) -> List[float]:
+    ffmpeg = require_tool("ffmpeg")
+    proc = subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"],
+                          stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    n = len(proc.stdout) // 2
+    if n == 0:
+        return []
+    samples = struct.unpack(f"<{n}h", proc.stdout[: n * 2])
+    step = max(1, int(8000 * step_s))
+    env = []
+    for i in range(0, n, step):
+        block = samples[i:i + step]
+        env.append(math.sqrt(sum(x * x for x in block) / len(block)) / 32768.0)
+    return env
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("--threshold", type=float, default=10.0, help="scdet threshold 0-100 (default 10; lower = more cuts)")
+    ap.add_argument("--min-scene", type=float, default=1.0, help="ignore cuts closer than this in seconds (default 1)")
+    ap.add_argument("--highlights", type=int, default=0, help="number of highlight ranges to propose")
+    ap.add_argument("--target", type=float, help="with --highlights: total seconds the picks should add up to (trims long scenes)")
+    ap.add_argument("--max-scene", type=float, default=15.0, help="cap a highlight range at this many seconds (default 15)")
+    ap.add_argument("--edl", help="write highlight ranges as START-END lines (cut.py --segments format)")
+    ap.add_argument("--sheet", help="write a contact sheet PNG with the first frame of every scene")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    dur = meta.get("duration") or 0.0
+    cuts = detect_scenes(args.input, args.threshold, args.min_scene, dur)
+    bounds = cuts + [dur]
+    step_s = 0.5
+    env = audio_envelope(args.input, step_s) if meta.get("audio") else []
+
+    scenes = []
+    for i in range(len(bounds) - 1):
+        s, e = bounds[i], bounds[i + 1]
+        if e - s <= 0.05:
+            continue
+        seg = env[int(s / step_s): max(int(s / step_s) + 1, int(e / step_s))] if env else []
+        energy = (sum(seg) / len(seg)) if seg else 0.0
+        peak = max(seg) if seg else 0.0
+        scenes.append({"index": len(scenes), "start": round(s, 3), "end": round(e, 3), "duration": round(e - s, 3),
+                       "audio_rms": round(energy, 4), "audio_peak": round(peak, 4)})
+    peaks = []
+    if env:
+        thr = sorted(env)[int(len(env) * 0.9)] if len(env) > 10 else max(env)
+        for i, val in enumerate(env):
+            if val >= thr and val > 0.02 and (i == 0 or env[i - 1] < val) and (i == len(env) - 1 or env[i + 1] <= val):
+                peaks.append({"time": round(i * step_s, 2), "rms": round(val, 4)})
+        peaks = sorted(peaks, key=lambda p: -p["rms"])[:20]
+        peaks.sort(key=lambda p: p["time"])
+
+    result: Dict = {"file": args.input, "duration": round(dur, 3), "scene_count": len(scenes), "scenes": scenes, "audio_peaks": peaks}
+    info(f"{len(scenes)} scenes, {len(peaks)} audio peaks over {dur:.1f}s")
+
+    if args.highlights:
+        ranked = sorted(scenes, key=lambda sc: (-sc["audio_rms"], sc["start"]))[: args.highlights]
+        picks: List[Tuple[float, float]] = []
+        budget = args.target if args.target else None
+        per = (budget / max(1, len(ranked))) if budget else args.max_scene
+        for sc in ranked:
+            length = min(sc["duration"], per, args.max_scene)
+            # take the loudest window inside the scene
+            best_s = sc["start"]
+            if env and length < sc["duration"]:
+                best, best_s = -1.0, sc["start"]
+                win = max(1, int(length / step_s))
+                lo, hi = int(sc["start"] / step_s), max(int(sc["start"] / step_s) + 1, int(sc["end"] / step_s) - win)
+                for i in range(lo, hi + 1):
+                    val = sum(env[i:i + win])
+                    if val > best:
+                        best, best_s = val, i * step_s
+            picks.append((round(best_s, 2), round(min(sc["end"], best_s + length), 2)))
+        picks.sort()
+        result["highlights"] = [{"start": s, "end": e, "duration": round(e - s, 2)} for s, e in picks]
+        result["highlights_total"] = round(sum(e - s for s, e in picks), 2)
+        info(f"proposed {len(picks)} highlight ranges totalling {result['highlights_total']:.1f}s")
+        if args.edl:
+            with open(args.edl, "w", encoding="utf-8") as fh:
+                for s, e in picks:
+                    fh.write(f"{s:.2f}-{e:.2f}\n")
+            info(f"wrote {args.edl}")
+
+    if args.sheet:
+        n = len(scenes)
+        cols = min(4, max(1, n))
+        rows = max(1, math.ceil(n / cols))
+        tile_w = 1280 // cols // 2 * 2
+        # exactly one frame per scene: the frame index at the scene start
+        fps = meta["video"].get("fps") or 30.0
+        expr = "+".join(f"eq(n\\,{int(round(sc['start'] * fps))})" for sc in scenes)
+        vf = (f"select='{expr}',scale={tile_w}:-2,drawtext=text='%{{pts\\:hms}}':fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6,"
+              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
+        run(ffmpeg_base() + ["-i", args.input, "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", args.sheet])
+        info(f"wrote {args.sheet}")
+        result["sheet"] = args.sheet
+
+    if args.json:
+        emit(None, **result)
+    else:
+        print_json(result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/silence.py

@@ -16,7 +16,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
+from _common import video_args, aac_args, add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run, x264_args
 
 SIL_RE = re.compile(r"silence_(start|end): ([0-9.]+)")
 
@@ -110,7 +110,7 @@ def main() -> int:
     af = f"aselect='{expr}',asetpts=N/SR/TB"
     cmd = ffmpeg_base() + ["-i", args.input]
     if meta.get("video"):
-        cmd += ["-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+        cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += ["-af", af] + aac_args() + [output]
     run(cmd)
     r = probe(output)

package/scripts/sync.py

@@ -26,7 +26,7 @@ import subprocess
 import sys
 from typing import List
 
-from _common import add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
 
 SR = 8000  # decode sample rate
 
@@ -253,14 +253,14 @@ def main() -> int:
             if proc.returncode != 0:
                 cmd = [c for c in cmd if c != "copy"]
                 idx = cmd.index("-c:v"); del cmd[idx]
-                cmd = cmd[:-1] + x264_args(args.crf) + [output]
+                cmd = cmd[:-1] + video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) + [output]
                 run(cmd)
         else:
             if head_trim > 0 and not drift_af:
                 cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy", "-avoid_negative_ts", "make_zero", output]
                 proc = run(cmd, check=False)
                 if proc.returncode != 0:
-                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (x264_args(args.crf) if has_video else []) + audio_codec_for(output) + [output]
+                    cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]
                     run(cmd)
             else:
                 cmd = ffmpeg_base()
@@ -278,7 +278,7 @@ def main() -> int:
                         vf.append(f"setpts=PTS/{drift_ratio:.9f}")
                     if vf:
                         cmd += ["-vf", ",".join(vf)]
-                    cmd += x264_args(args.crf)
+                    cmd += video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf)
                 if af_parts:
                     cmd += ["-af", ",".join(af_parts)]
                 cmd += audio_codec_for(output) + [output]

package/scripts/verify.py

@@ -47,6 +47,14 @@ def collect(paths: List[str]) -> List[Path]:
 
 def step(name: str, argv: List[str], timeout: float) -> Dict:
     t0 = time.time()
+    if argv[0] == "__check_hdr__":
+        try:
+            v = probe(argv[1]).get("video") or {}
+            ok = bool(v.get("hdr")) and v.get("bit_depth", 8) >= 10
+            err = "" if ok else f"re-encode lost HDR: {v.get('color_transfer')}/{v.get('pix_fmt')}"
+        except SystemExit:
+            ok, err = False, "output missing"
+        return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
     try:
         proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout)
         ok = proc.returncode == 0
@@ -110,7 +118,8 @@ def main() -> int:
                 plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
                 plan.append(("look sheet", ["look.py", cut, "-o", f"{stem}_sheet.png"]))
                 if (meta.get("video") or {}).get("hdr"):
-                    plan.append(("color to-sdr", ["color.py", cut, "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
+                    plan.append(("color to-sdr", ["color.py", str(f), "--to-sdr", "-o", f"{stem}_sdr.mp4"] + fast))
+                    plan.append(("hdr preserved", ["__check_hdr__", f"{stem}_acc.mp4"]))
                 plan.append(("probe analyze", ["probe.py", cut, "--analyze"]))
             plan.append(("export x", ["export.py", cut, "--preset", "x", "-o", f"{stem}_x.mp4"]))
         if has_a and not args.quick: