ffmpeg-skill 1.14.0 → 1.15.1

package/scripts/_common/emit.py

@@ -0,0 +1,287 @@
+"""Result documents: die(), info(), emit(), the brief and 2.0 shapes, and the plan file.
+
+Every script ends in exactly one of these: emit() on success, die() on failure. Both print a
+single JSON document when --json is on and record the Context the caller passed.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
+
+
+def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None, **extra: Any) -> "None":
+    """Exit with a message. Under --json also print a machine-readable failure document
+    (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged.
+
+    `extra` fields are added to the failure document: a tool whose *result* failed (check.py's
+    platform rows, render.py's check stage, batch.py's per-item results, verify.py's steps) keeps
+    reporting that detail while the top-level status says failed. Before 1.4.3 those four printed
+    `status: "completed"` next to a non-zero exit code, so a caller keying on the status alone
+    read a failed delivery as a success."""
+    hint = extra.pop("hint", None)
+    ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
+    _set_current_ctx(ctx)  # the atexit hook has no argument: it reads the ctx emit()/die() last used
+    ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
+    STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
+    sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
+    if ctx.json:
+        doc: Dict[str, Any] = {
+            "status": "failed", "exit_code": code,
+            "error": {
+                "kind": kind, "message": msg,
+                "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
+                "retryable": ERROR_RETRYABLE,
+            },
+            "commands": list(ctx.commands),
+        }
+        if hint:
+            doc["error"]["hint"] = hint
+        doc.update(extra)
+        print_json(doc)
+    sys.exit(code)
+
+
+def info(msg: str, ctx: "Optional[Context]" = None) -> None:
+    # under --dry-run nothing is written; do not let scripts claim otherwise
+    ctx = ctx or STATE
+    if msg.startswith("wrote ") and ctx.dry_run:
+        msg = "[dry-run] would write " + msg[len("wrote "):]
+    sys.stderr.write(f"{msg}\n")
+
+
+# The atexit plan hook takes no arguments, so emit()/die() record the Context they were given
+# here; nothing passed a ctx = it stays None and the hook falls back to STATE, as before (1.10).
+_CURRENT_CTX: "Optional[Context]" = None
+
+
+def _set_current_ctx(ctx: "Context") -> None:
+    global _CURRENT_CTX
+    _CURRENT_CTX = ctx
+
+
+def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
+    """Final stdout line: the output path, or a JSON document with --json.
+
+    `ctx` is the optional per-request Context added in 1.10 (2.0 makes it required, issue #189 B);
+    omitted, every read falls back to the process-global STATE as before."""
+    ctx = ctx or STATE
+    _set_current_ctx(ctx)  # so the atexit hook writes (or skips) this ctx's plan, not STATE's
+    meta: Dict[str, Any] = {}
+    if output and not ctx.dry_run:
+        meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
+    if ctx.json:
+        doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
+        if meta:
+            doc["probe"] = meta
+        # What this tool itself verified about its artifact (issue #189 C, "verify as part of the
+        # contract"): the probe every writing tool runs, plus the measurements a tool adds
+        # (`verification` extra: loudness after the write, a platform check). `verified` is true
+        # only when the file was written, probed, and every self-check met its target; a dry run
+        # verified nothing. Spec failures the tool cannot fix on its own (export's loudness gap)
+        # keep status completed and say verified: false, so a caller keys on one field.
+        steps: List[Dict[str, Any]] = ([{"step": "probe", "ok": True}] if meta else []) + list(extra.pop("verification", None) or [])
+        if output and not ctx.dry_run and os.path.splitext(output)[1].lower() not in MEDIA_EXT:
+            steps.insert(0, {"step": "exists", "ok": True})
+        doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
+        doc["verification"] = steps
+        doc.update(extra)
+        if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
+            doc["result_v2"] = _result_v2(output, meta, dict(extra, verified=doc["verified"], verification=steps))
+        if ctx.plan:
+            doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
+        print_json(_brief(doc, meta) if ctx.json_brief else doc)
+    elif ctx.plan:
+        print(write_plan(ctx.plan, output, extra, ctx=ctx))
+    elif output:
+        print(output)
+
+
+# Keys the brief document replaces or drops: the full probe (summarised), the command lines
+# (counted), the per-step verification list (its verdict stays as `verified`) and the 2.0 preview.
+_BRIEF_DROP = ("probe", "commands", "verification", "result_v2")
+
+
+def _brief_summary(meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+    """The handful of output facts a caller reports or branches on, from the probe this tool
+    already ran -- plus the measured loudness when the tool measured one. Keys whose value is
+    unknown are left out rather than emitted as null."""
+    video = (meta or {}).get("video") or {}
+    audio = (meta or {}).get("audio") or {}
+    summary: Dict[str, Any] = {}
+    duration = (meta or {}).get("duration")
+    if duration is not None:
+        summary["duration_s"] = round(float(duration), 3)
+    for key, value in (("width", video.get("width")), ("height", video.get("height")), ("fps", video.get("fps")),
+                       ("vcodec", video.get("codec")), ("acodec", audio.get("codec")), ("channels", audio.get("channels"))):
+        if value is not None:
+            summary[key] = value
+    lufs = None
+    for source, key in ((extra.get("result"), "input_i"), (extra.get("measured"), "input_i")):
+        if lufs is None and isinstance(source, dict):
+            lufs = _to_float(source.get(key))
+    for step in extra.get("verification") or []:
+        if lufs is None and isinstance(step, dict):
+            lufs = _to_float(step.get("lufs"))
+    # a silent file measures -inf, which json.dumps writes as the non-standard -Infinity: the
+    # brief document stays valid JSON by leaving the key out instead (the full document's own
+    # `measured`/`result` still carries whatever the tool reported).
+    if lufs is not None and math.isfinite(lufs):
+        summary["lufs"] = round(lufs, 2)
+    return summary
+
+
+def _brief(doc: Dict[str, Any], meta: Dict[str, Any]) -> Dict[str, Any]:
+    """--json-brief: the same success document with the bulky parts replaced by what a caller
+    acts on. Same keys, same meanings -- `commands` becomes the count of the command lines,
+    `probe` becomes `summary` -- plus every tool-specific key the tool itself passed to emit().
+    Failures are untouched: die() prints the full failure document either way."""
+    brief: Dict[str, Any] = {"status": doc["status"], "output": doc["output"], "dry_run": doc["dry_run"],
+                             "verified": doc.get("verified", False)}
+    summary = _brief_summary(meta, doc)
+    if summary:
+        brief["summary"] = summary
+    brief["commands"] = len(doc.get("commands") or [])
+    for key, value in doc.items():
+        if key not in brief and key not in _BRIEF_DROP:
+            brief[key] = value
+    # the emoji report is a full inventory in the long document; brief keeps the two fields a
+    # caller branches on (did colour happen, and how many)
+    if isinstance(brief.get("emoji"), dict):
+        brief["emoji"] = {k: v for k, v in brief["emoji"].items() if k in ("mode", "count")}
+    return brief
+
+
+PLAN_VERSION = 1
+
+
+_PLAN_STRIP = ("--plan", "--dry-run", "--json")
+
+
+def _plan_at_exit() -> None:
+    ctx = _CURRENT_CTX or STATE
+    if ctx.plan and not ctx.plan_written:
+        try:
+            write_plan(ctx.plan, None, {}, ctx=ctx)
+        except SystemExit:
+            pass
+
+
+def _plan_inputs(commands: Sequence[str], argv: Sequence[str] = (), ctx: "Optional[Context]" = None) -> List[str]:
+    """Every existing file the plan depends on: the `-i` inputs of the planned commands, any
+    existing file named in argv (a recipe, a project, an SRT, a LUT, a still), and the side
+    inputs tools register through escape_filter_path() (review 6: only `-i` files were bound)."""
+    import shlex
+    seen: List[str] = []
+    for a in list(argv) + list((ctx or STATE).plan_inputs):
+        if a and not a.startswith("-") and os.path.isfile(a) and a not in seen:
+            seen.append(a)
+    for line in commands:
+        try:
+            toks = shlex.split(line.split("] ", 1)[1] if line.startswith("[dry-run] ") else line)
+        except ValueError:
+            continue
+        for i, tok in enumerate(toks[:-1]):
+            if tok == "-i" and os.path.isfile(toks[i + 1]) and toks[i + 1] not in seen:
+                seen.append(toks[i + 1])
+    return seen
+
+
+def write_plan(path: str, output: Optional[str], extra: Dict[str, Any], ctx: "Optional[Context]" = None) -> str:
+    """The dry run as an artifact: what will run, on which exact inputs, producing what, checked
+    how. `render.py PLAN` executes it after re-fingerprinting the inputs (issue #189 C).
+
+    `ctx` is the Context whose commands and inputs the plan describes (emit()/die() pass the one
+    they were given); omitted, it is the process-global STATE as before."""
+    import datetime
+    ctx = ctx or STATE
+    argv = [a for a in sys.argv[1:]]
+    cleaned: List[str] = []
+    skip = False
+    for a in argv:
+        if skip:
+            skip = False
+            continue
+        if a in _PLAN_STRIP:
+            skip = a == "--plan"
+            continue
+        if a.startswith("--plan="):
+            continue
+        cleaned.append(a)
+    tool = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+    verify: List[Dict[str, Any]] = [{"tool": "probe"}] if output else []
+    platform = None
+    if "--platform" in cleaned:
+        platform = cleaned[cleaned.index("--platform") + 1]
+    elif tool == "export" and "--preset" in cleaned:
+        platform = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}.get(cleaned[cleaned.index("--preset") + 1])
+    if platform and output and tool != "check":
+        verify.append({"tool": "check", "platform": platform})
+    doc = {
+        "plan_version": PLAN_VERSION,
+        "created": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "tool": tool,
+        "argv": cleaned,
+        "cwd": os.getcwd(),
+        "inputs": [fingerprint(p) for p in _plan_inputs(ctx.commands, cleaned, ctx)],
+        "commands": list(ctx.commands),
+        "output": os.path.abspath(output) if output else None,
+        "verify": verify,
+        "notes": list(extra.get("notes") or []),
+    }
+    try:
+        tmp = f"{path}.tmp{os.getpid()}"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(doc, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp, path)
+    except OSError as exc:
+        die(f"cannot write plan {path}: {exc}", kind="output")
+    ctx.plan_written = True
+    info(f"plan written: {path} ({len(doc['commands'])} command(s), {len(doc['inputs'])} input(s)); run it with render.py {path}", ctx)
+    return path
+
+
+_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams", "verified", "verification")
+
+
+def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+    """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
+    FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
+    `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
+    dicts flattened, plus every top-level numeric extra such as `expected_duration` or
+    `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
+    and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
+    this key is additive and its shape is what 2.0 promotes to the top level."""
+    metrics: Dict[str, Any] = {}
+    for key in ("measured", "result"):
+        if isinstance(extra.get(key), dict):
+            metrics.update(extra[key])
+    for key, value in extra.items():
+        if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
+            metrics[key] = value
+    notes = extra.get("notes")
+    return {
+        "schema": 2,
+        "output": output,
+        "probe": meta or None,
+        "commands": list(STATE.commands),
+        "metrics": metrics,
+        "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
+        "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
+        "verified": bool(extra.get("verified", False)),
+        "verification": list(extra.get("verification") or []),
+        "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
+    }
+
+
+def print_json(obj: Any) -> None:
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+# Deferred for the same reason as runner's import of this module: probe needs die() from here, and
+# emit() needs verify_output() from there, but only ever at call time.
+from _common.probe import MEDIA_EXT, _to_float, fingerprint, verify_output  # noqa: E402

package/scripts/_common/probe.py

@@ -0,0 +1,382 @@
+"""ffprobe and the measured facts read back off a file: the probe document every script starts
+from, the verification every script ends with, and the level/waveform measurements.
+
+Reading only -- the choices made from these facts live in decision.py.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from fractions import Fraction
+from typing import Any, Dict, List, Optional, Sequence
+from _common.emit import die
+from _common.runner import STATE, require_tool, run, run_analysis
+
+
+def fingerprint(path: str) -> Dict[str, Any]:
+    """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
+    or a swapped file, cheap enough for a multi-GB source (hashing a whole master would make
+    planning slower than the edit)."""
+    import hashlib
+    st = os.stat(path)
+    h = hashlib.sha256()
+    chunk = 8 * 1024 * 1024
+    with open(path, "rb") as f:
+        h.update(f.read(chunk))
+        if st.st_size > 2 * chunk:
+            f.seek(-chunk, os.SEEK_END)
+            h.update(f.read(chunk))
+        elif st.st_size > chunk:
+            h.update(f.read())
+    return {"path": os.path.abspath(path), "size": st.st_size, "sha256_head_tail": h.hexdigest()}
+
+
+def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None, start: float = 0.0,
+                    *, check: bool = True) -> List[float]:
+    """Decode (part of) a file's audio to mono float samples in [-1, 1) at `sample_rate` via a
+    single ffmpeg pass under --timeout. Shared by scenes.py (audio envelope for cut scoring) and
+    sync.py (cross-correlation); an undecodable input is kind ffmpeg when check=True, else []."""
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin"]
+    if start:
+        cmd += ["-ss", f"{start:.3f}"]
+    cmd += ["-i", path]
+    if seconds is not None:
+        cmd += ["-t", f"{seconds:.3f}"]
+    cmd += ["-vn", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    proc = run_analysis(cmd, check=False, text=False)
+    if proc.returncode != 0 or not proc.stdout:
+        if check:
+            die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
+        return []
+    n = len(proc.stdout) // 2
+    import struct
+    return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+
+
+def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:
+    """RMS per block of `step` samples. full_blocks_only drops a short tail block (sync.py: every
+    block must be the same length for the correlation); remove_mean subtracts the envelope's mean
+    (sync.py: so silence does not correlate). scenes.py keeps the tail and the absolute level."""
+    step = max(1, int(step))
+    n = len(samples)
+    stop = n - step + 1 if full_blocks_only else n
+    env: List[float] = []
+    for i in range(0, max(0, stop), step):
+        block = samples[i:i + step]
+        env.append(math.sqrt(sum(x * x for x in block) / len(block)))
+    if remove_mean and env:
+        mean = sum(env) / len(env)
+        env = [e - mean for e in env]
+    return env
+
+
+MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".m2ts", ".mxf", ".3gp", ".wmv", ".gif",
+             ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".aif", ".aiff", ".caf", ".wma", ".png", ".jpg", ".jpeg", ".webp"}
+
+
+def _output_failed(path: str, why: str) -> "None":
+    """An ffmpeg run reported success but the artifact is not usable: say so, and do not leave a
+    0-byte file behind that a later step could mistake for a result."""
+    try:
+        if os.path.exists(path) and os.path.getsize(path) == 0:
+            os.remove(path)
+            why += " (empty file removed)"
+    except OSError:
+        pass
+    die(f"output verification failed: {path}: {why}", kind="output")
+
+
+def verify_output(path: str) -> Dict[str, Any]:
+    """The success criterion for every writing tool: the file exists, is not empty and ffprobe
+    can read at least one stream from it. Non-media artifacts (srt, edl, html, md) only need to
+    exist and be non-empty. Returns the probe (empty dict for non-media)."""
+    if not os.path.exists(path):
+        _output_failed(path, "not written")
+    if os.path.getsize(path) == 0:
+        _output_failed(path, "0 bytes")
+    if os.path.splitext(path)[1].lower() not in MEDIA_EXT:
+        return {}
+    meta = probe(path, role="output")
+    if not meta.get("video") and not meta.get("audio"):
+        _output_failed(path, "no video or audio stream")
+    return meta
+
+
+def probe(path: str, role: str = "input") -> Dict[str, Any]:
+    """Return a compact, script-friendly description of a media file.
+
+    role="output" marks a file this tool just wrote: a read failure is then reported as an
+    output-verification failure (kind "output") instead of an input problem."""
+    if not os.path.exists(path):
+        if role == "output" and not STATE.dry_run:
+            _output_failed(path, "not written")
+        if STATE.dry_run:
+            # width/height/fps are honestly 0/0/0.0 -- "not measured", matching duration/size_bytes
+            # below -- because this is a dry run: the file doesn't exist yet, so there is nothing to
+            # probe. Earlier this stub used plausible-looking placeholders (1920x1080x30.0) instead,
+            # which some tools' dry-run summary line echoed verbatim as if it were a real computed
+            # preview (#77). That was reverted once, because a couple of call sites divided by these
+            # values for aspect-ratio math and crashed on a real 0 (join.py, fit.py); those call
+            # sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
+            # by it, so the stub can finally report the honest, unknown value.
+            return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
+                    "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
+                              "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
+                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
+        die(f"input not found: {path}")
+    ffprobe = require_tool("ffprobe")
+    proc = run(
+        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
+        quiet=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        if role == "output":
+            _output_failed(path, f"ffprobe cannot read it:\n{proc.stderr.strip()}")
+        die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
+    try:
+        raw = json.loads(proc.stdout or "{}")
+    except ValueError as e:
+        if role == "output":
+            _output_failed(path, f"ffprobe printed unreadable JSON: {e}")
+        die(f"ffprobe printed unreadable JSON for {path}: {e}", kind="ffmpeg")
+    fmt = raw.get("format", {})
+    streams = raw.get("streams", [])
+    video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
+    audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
+    subs = [s for s in streams if s.get("codec_type") == "subtitle"]
+    data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
+
+    duration = _to_float(fmt.get("duration"))
+    if duration is None and video:
+        duration = _to_float(video.get("duration"))
+    if duration is None and audio:
+        duration = _to_float(audio.get("duration"))
+    if duration and STATE.duration_hint is None:
+        STATE.duration_hint = duration
+
+    out: Dict[str, Any] = {
+        "file": path,
+        "format": fmt.get("format_name"),
+        "duration": duration,
+        "size_bytes": _to_int(fmt.get("size")),
+        "bitrate": _to_int(fmt.get("bit_rate")),
+        "video": None,
+        "audio": None,
+        "subtitle_streams": len(subs),
+        "data_streams": data_stream_count,
+        # container-level chapter markers and the common tags, so metadata.py's result is
+        # verifiable the same way every other tool's is (additive keys, 1.x-safe)
+        "chapters": [{
+            "index": n,
+            "start": _to_float(ch.get("start_time")),
+            "end": _to_float(ch.get("end_time")),
+            "title": (ch.get("tags") or {}).get("title"),
+        } for n, ch in enumerate(raw.get("chapters") or [])],
+        "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
+        # every subtitle stream in file order: index n here is `-map 0:s:n`
+        "subtitle_stream_details": [{
+            "index": n,
+            "codec": s.get("codec_name"),
+            "language": (s.get("tags") or {}).get("language"),
+            "title": (s.get("tags") or {}).get("title"),
+        } for n, s in enumerate(subs)],
+    }
+    if video:
+        r_rate = _fraction(video.get("r_frame_rate"))
+        avg_rate = _fraction(video.get("avg_frame_rate"))
+        fps = float(avg_rate) if avg_rate else (float(r_rate) if r_rate else None)
+        vfr = bool(r_rate and avg_rate and abs(float(r_rate) - float(avg_rate)) > 0.01)
+        w, h = _to_int(video.get("width")), _to_int(video.get("height"))
+        rotation = 0
+        for sd in video.get("side_data_list", []) or []:
+            if "rotation" in sd:
+                rotation = int(round(float(sd["rotation"])))
+        if "rotate" in (video.get("tags") or {}):
+            try:
+                rotation = int(video["tags"]["rotate"])
+            except ValueError:
+                pass
+        pix = video.get("pix_fmt") or ""
+        trc = video.get("color_transfer") or ""
+        prim = video.get("color_primaries") or ""
+        hdr = trc in ("smpte2084", "arib-std-b67") or prim == "bt2020"
+        dovi = None
+        for sd in video.get("side_data_list", []) or []:
+            if "dv_profile" in sd or "DOVI" in str(sd.get("side_data_type", "")):
+                dovi = {"profile": sd.get("dv_profile"), "level": sd.get("dv_level"), "bl_compatibility_id": sd.get("dv_bl_signal_compatibility_id")}
+        if dovi:  # a Dolby Vision stream is HDR even when its base layer tags are missing
+            hdr = True
+        out["video"] = {
+            "codec": video.get("codec_name"),
+            "profile": video.get("profile"),
+            "width": w,
+            "height": h,
+            "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
+            "fps": round(fps, 3) if fps else None,
+            "r_frame_rate": video.get("r_frame_rate"),
+            "avg_frame_rate": video.get("avg_frame_rate"),
+            "variable_frame_rate_suspected": vfr,
+            "pix_fmt": video.get("pix_fmt"),
+            "bit_depth": _bit_depth(pix),
+            "hdr": hdr,
+            # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
+            # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
+            # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
+            "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
+            "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
+                           "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
+            "dolby_vision": dovi,
+            "color_space": video.get("color_space"),
+            "color_primaries": video.get("color_primaries"),
+            "color_transfer": video.get("color_transfer"),
+            "color_range": video.get("color_range"),
+            "rotation": rotation,
+            "nb_frames": _to_int(video.get("nb_frames")),
+            "bitrate": _to_int(video.get("bit_rate")),
+        }
+    if audio:
+        out["audio"] = {
+            "codec": audio.get("codec_name"),
+            "channels": _to_int(audio.get("channels")),
+            "channel_layout": audio.get("channel_layout"),
+            "sample_rate": _to_int(audio.get("sample_rate")),
+            "bitrate": _to_int(audio.get("bit_rate")),
+        }
+        # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
+        out["audio_streams"] = [{
+            "index": n,
+            "codec": a.get("codec_name"),
+            "channels": _to_int(a.get("channels")),
+            "channel_layout": a.get("channel_layout"),
+            "sample_rate": _to_int(a.get("sample_rate")),
+            "language": (a.get("tags") or {}).get("language"),
+            "title": (a.get("tags") or {}).get("title"),
+        } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
+    return out
+
+
+def _bit_depth(pix_fmt: Optional[str]) -> int:
+    """Bits per component from a pixel format name. `"10" in pix` used to read yuv410p (4:1:0
+    chroma) as 10-bit; the depth is the number that ends the name (before an le/be suffix):
+    yuv420p10le -> 10, gbrp12be -> 12, gray16le -> 16, yuv410p / yuv420p / rgb24 -> 8."""
+    m = re.search(r"(\d{1,2})(?:le|be)?$", pix_fmt or "")
+    if not m:
+        return 8
+    n = int(m.group(1))
+    if n in (24, 32):      # packed 8-bit rgb24/bgr32/rgb0 etc.
+        return 8
+    if n in (48, 64):      # packed 16-bit rgb48/rgba64
+        return 16
+    return n if 8 <= n <= 16 else 8
+
+
+def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
+    """Video keyframe timestamps within +-window seconds of t, ascending. Read with
+    -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
+    ffprobe = require_tool("ffprobe")
+    lo = max(0.0, t - window)
+    proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
+                "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
+                "-of", "csv=p=0", path], quiet=True, check=False)
+    if proc.returncode != 0:
+        return []
+    out: List[float] = []
+    for line in proc.stdout.splitlines():
+        try:
+            out.append(round(float(line.strip().rstrip(",")), 3))
+        except ValueError:
+            continue
+    return sorted(set(out))
+
+
+def measured_level_dbfs(path: str, seconds: float = 120.0) -> Optional[Dict[str, float]]:
+    """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
+    Cheap enough to run once as a hint when a threshold-based tool found nothing."""
+    ffmpeg = require_tool("ffmpeg")
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.0f}", "-i", path, "-vn",
+                         "-af", "volumedetect", "-f", "null", "-"], check=False)
+    m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+    m_max = re.search(r"max_volume:\s*(-?[0-9.]+) dB", proc.stderr)
+    if not (m_mean and m_max):
+        return None
+    return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
+
+
+def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
+    """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
+
+    Log gammas (S-Log3, V-Log, C-Log, HLG-looking flat profiles) put black around 90-95/255 and
+    white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
+    """
+    ffmpeg = require_tool("ffmpeg")
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
+           "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
+    proc = run_analysis(cmd, check=False)
+    vals: Dict[str, List[float]] = {}
+    for line in proc.stdout.splitlines():
+        if "lavfi.signalstats." in line and "=" in line:
+            key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
+            try:
+                vals.setdefault(key, []).append(float(val))
+            except ValueError:
+                pass
+    if not vals.get("YAVG"):
+        return {"error": "no frames analysed"}
+    def mean(k: str) -> float:
+        v = vals.get(k) or [0.0]
+        return sum(v) / len(v)
+    ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
+    # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
+    scale = 1.0
+    if ymax > 255 or yavg > 255:
+        scale = 1 / 4.0 if ymax <= 1023 else (1 / 16.0 if ymax <= 4095 else 1 / 256.0)  # 10 / 12 / 16-bit
+    ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
+    # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
+    lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
+    highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
+    p_low = lows[len(lows) // 20]
+    p_high = highs[-1 - len(highs) // 20]
+    looks_log = p_low >= 64 and p_high <= 235 and sat < 40
+    return {
+        "scale": "8-bit equivalent",
+        "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
+        "saturation_avg": round(sat, 1),
+        "looks_like_log": looks_log,
+        "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "
+                 "Apply the camera's conversion LUT with color.py --lut" if looks_log else "contrast and saturation look like normal display-referred SDR"),
+    }
+
+
+def _to_float(v: Any) -> Optional[float]:
+    try:
+        return float(v) if v is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_int(v: Any) -> Optional[int]:
+    try:
+        return int(v) if v is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _fraction(v: Optional[str]) -> Optional[Fraction]:
+    if not v or v in ("0/0", "0"):
+        return None
+    try:
+        f = Fraction(v)
+        return f if f > 0 else None
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
+    if not w or not h:
+        return None
+    f = Fraction(w, h)
+    return f"{f.numerator}:{f.denominator}"