ffmpeg-skill 2.10.11 → 2.12.0

package/scripts/report.py

@@ -17,32 +17,57 @@ import os
 import sys
 import tempfile
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, read_text_or_die, run_tool
+from _common.emit import record_skip, warn
 
 HERE = Path(__file__).resolve().parent
 
 
-def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> Optional[str]:
+def _child_failure(proc: Any, doc: Any) -> Dict[str, Any]:
+    """Why a sibling tool produced nothing usable: its own error (kind, reason, message), or the
+    last stderr line and the exit code when it printed no failure document."""
+    err = (doc or {}).get("error") if isinstance(doc, dict) and isinstance(doc.get("error"), dict) else {}
+    out: Dict[str, Any] = {"exit_code": proc.returncode,
+                           "message": str(err.get("message") or (proc.stderr.strip().splitlines() or ["?"])[-1])[:300]}
+    for k in ("kind", "reason"):
+        if err.get(k):
+            out[k] = err[k]
+    return out
+
+
+def sheet_b64(path: str, tiles: str = "4x2", width: int = 1200) -> "Tuple[Optional[str], Dict[str, Any]]":
+    """(the contact sheet as base64, or None; why there is none)."""
+    if STATE.dry_run:
+        return None, {"reason": "dry_run", "message": "a dry run draws no contact sheet"}
     with tempfile.TemporaryDirectory(prefix="ffskill_report_") as tmp:
         png = os.path.join(tmp, "sheet.png")
-        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png] + child_args())
+        proc = run_tool([str(HERE / "look.py"), path, "--tiles", tiles, "--width", str(width), "-o", png, "--json"] + child_args())
+        try:
+            doc = json.loads(proc.stdout)
+        except ValueError:
+            doc = None
         if proc.returncode != 0 or not os.path.exists(png):
-            return None
-        return base64.b64encode(Path(png).read_bytes()).decode("ascii")
+            return None, dict(_child_failure(proc, doc), reason=((doc or {}).get("error") or {}).get("reason") or "look_failed")
+        return base64.b64encode(Path(png).read_bytes()).decode("ascii"), {}
 
 
-def loudness(path: str) -> Dict[str, Any]:
+def loudness(path: str) -> "Tuple[Dict[str, Any], Dict[str, Any]]":
+    """(lufs/tp/lra, or {}; why there is no measurement)."""
     proc = run_tool([str(HERE / "loudness.py"), path, "--measure-only"] + child_args())
     try:
         d = json.loads(proc.stdout)
-        return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}
-    except (ValueError, KeyError):
-        return {}
+    except ValueError:
+        d = None
+    try:
+        return {"lufs": round(float(d["input_i"]), 1), "tp": round(float(d["input_tp"]), 1), "lra": round(float(d["input_lra"]), 1)}, {}
+    except (TypeError, ValueError, KeyError):
+        return {}, dict(_child_failure(proc, d), reason="loudness_not_measured")
 
 
-def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
+def check(path: str, platform: str) -> "Tuple[Optional[Dict[str, Any]], Dict[str, Any]]":
+    """(check.py's document, or None when it could not run at all; why)."""
     proc = run_tool([str(HERE / "check.py"), path, "--platform", platform, "--json"] + child_args())
     try:
         doc = json.loads(proc.stdout)
@@ -51,10 +76,10 @@ def check(path: str, platform: str) -> Optional[Dict[str, Any]]:
     if not isinstance(doc, dict) or "checks" not in doc:
         # check.py could not run at all (missing ffmpeg, unreadable file): its failure document
         # has no rows to render. A failed *verification* still carries its rows and is shown.
-        reason = ((doc or {}).get("error") or {}).get("message") or (proc.stderr.strip().splitlines() or ["?"])[-1]
-        info(f"check.py could not run: {reason[:200]}")
-        return None
-    return doc
+        why = dict(_child_failure(proc, doc), reason=((doc or {}).get("error") or {}).get("reason") or "check_failed")
+        info(f"check.py could not run: {why['message'][:200]}")
+        return None, why
+    return doc, {}
 
 
 def fmt_dur(sec: Optional[float]) -> str:
@@ -167,15 +192,44 @@ def main() -> int:
         die("--after is required (or --pack FILE for a social pack table)")
     after = probe(args.after)
     before = probe(args.before) if args.before else None
-    ld_after = loudness(args.after) if after.get("audio") else {}
-    ld_before = loudness(args.before) if before and before.get("audio") else {}
-    chk = check(args.after, args.platform) if args.platform else None
-    sheets = {}
+    # every section the report would show is either in it or accounted for: a section that could
+    # not be built is a failing verification step (and a warning), never just absent from the page
+    verification: List[Dict[str, Any]] = []
+
+    def section(step: str, which: Optional[str], why: Dict[str, Any], what: str) -> None:
+        entry: Dict[str, Any] = {"step": step, "ok": not why}
+        if which:
+            entry["file"] = which
+        if why:
+            if why.get("reason") == "dry_run":
+                record_skip(f"{what}: {why['message']}", "report_section_dry_run", section=step, file=which)
+                return
+            entry.update({k: v for k, v in why.items() if k != "message"}, message=why.get("message"))
+            warn(f"the report has no {what}: {why.get('message')}", "report_section_missing", section=step, file=which,
+                 reason=why.get("reason"))
+        verification.append(entry)
+
+    ld_after: Dict[str, Any] = {}
+    ld_before: Dict[str, Any] = {}
+    if after.get("audio"):
+        ld_after, why = loudness(args.after)
+        section("loudness", "after", why, "loudness for --after")
+    if before and before.get("audio"):
+        ld_before, why = loudness(args.before)
+        section("loudness", "before", why, "loudness for --before")
+    chk = None
+    if args.platform:
+        chk, why = check(args.after, args.platform)
+        section("compliance", None, why, f"{args.platform} compliance table")
+        if chk is not None and verification:
+            # ok: the table is in the report; passed: what the table says about the file
+            verification[-1].update(platform=args.platform, passed=bool(chk.get("ok")))
+    sheets: Dict[str, Optional[str]] = {}
     if not args.no_sheets:
-        if before and before.get("video"):
-            sheets["before"] = sheet_b64(args.before)
-        if after.get("video"):
-            sheets["after"] = sheet_b64(args.after)
+        for which, path, meta in (("before", args.before, before), ("after", args.after, after)):
+            if meta and meta.get("video"):
+                sheets[which], why = sheet_b64(path)
+                section("contact_sheet", which, why, f"{which} contact sheet")
     commands = read_text_or_die(args.commands, "--commands").splitlines() if args.commands else []
     notes = read_text_or_die(args.notes, "--notes") if args.notes else ""
     title = args.title or f"Delivery report — {Path(args.after).name}"
@@ -235,7 +289,7 @@ def main() -> int:
         except OSError as e:
             die(f"cannot write {output}: {e}", kind="output")
         info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
-    emit(None, report=output, check=chk, verification=([{"step": "exists", "ok": True}] if not STATE.dry_run else []))
+    emit(None, report=output, check=chk, verification=([{"step": "exists", "ok": True}] + verification if not STATE.dry_run else []))
     if not args.json:
         print(output)
     return 0

package/scripts/reverse.py

@@ -15,6 +15,7 @@ import argparse
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
+from _common.emit import warn
 
 
 def main() -> int:
@@ -35,8 +36,9 @@ def main() -> int:
 
     output = args.output or default_output(args.input, "reverse")
     if (meta.get("duration") or 0) > 60:
-        info(f"warning: reverse buffers every decoded frame in memory; {meta['duration']:.0f}s of "
-             f"{meta['video']['width']}x{meta['video']['height']} can exhaust RAM -- cut the part to reverse first (cut.py)")
+        warn(f"reverse buffers every decoded frame in memory; {meta['duration']:.0f}s of "
+             f"{meta['video']['width']}x{meta['video']['height']} can exhaust RAM -- cut the part to reverse first (cut.py)",
+             "memory_heavy", duration=meta["duration"])
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", "reverse"]
     if has_audio:
         cmd += ["-af", "areverse"]

package/scripts/sequence.py

@@ -21,6 +21,7 @@ import tempfile
 from pathlib import Path
 
 from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, concat_list_line, fmt_secs
+from _common.emit import warn
 
 
 def even(n: float) -> int:
@@ -97,8 +98,9 @@ def main() -> int:
         # to be dropped silently, giving a shorter video; name the gap and what was left out
         later = _frames_after(directory, args.pattern, i)
         if later:
-            info(f"WARNING: frame {args.pattern % i} is missing; {len(later)} later frame(s) "
-                 f"(from {later[0].name}) are NOT in the sequence -- fill the gap or rename them")
+            warn(f"frame {args.pattern % i} is missing; {len(later)} later frame(s) "
+                 f"(from {later[0].name}) are NOT in the sequence -- fill the gap or rename them", "sequence_gap",
+                 missing=args.pattern % i, frames_left_out=len(later), first_left_out=later[0].name)
 
     frame_meta = probe(str(frames[0]))
     if not frame_meta.get("video"):

package/scripts/silence.py

@@ -22,6 +22,7 @@ from typing import List, Tuple
 from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS,
                      FILLER_PAD, read_text_or_die)
 from _common import asr as _asr
+from _common.emit import warn
 from _common import detect_silences as detect, STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, run, X264_PRESETS, measured_level_dbfs, fmt_secs
 
 
@@ -101,13 +102,14 @@ def resolve_filler(args, meta):
             "timestamps) or --transcribe. There is no way to find a filler word without them -- "
             "cutting the short quiet blips instead would remove real speech.", kind="input")
     source, engine, raw, transcription = None, None, None, {}
+    untimed: list = []  # transcript words without a usable timing (a --words file can carry them)
     if args.words:
         try:
             raw = json.loads(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         source = f"whisper-json:{args.words}"
-        words, had_segments = _words_from_transcript(raw)
+        words, had_segments, untimed = _words_from_transcript(raw)
         if not words:
             if had_segments:
                 die(f"the transcript in {args.words} has segment timings but no word timings; "
@@ -186,7 +188,8 @@ def resolve_filler(args, meta):
     wordlist |= set(_word_list(args.filler_extra))
     wordlist -= set(_word_list(args.filler_keep))
 
-    spans = filler_spans(words, wordlist, pad=args.filler_pad)
+    kept: dict = {}
+    spans = filler_spans(list(words) + untimed, wordlist, pad=args.filler_pad, stats=kept)
     removed_words = sorted({s["word"] for s in spans})
     warnings = []
     ambiguous = sorted(set(FILLER_AMBIGUOUS.get(lang, ())) & set(
@@ -210,12 +213,21 @@ def resolve_filler(args, meta):
         "removed_seconds": round(sum(s["end"] - s["start"] for s in spans), 3),
         "word_timings": len(words), "list": listname, "removed_words": removed_words,
         "warnings": warnings,
+        # listed words this run did not cut, and why: a transcript word with no timing has
+        # nothing to cut on, and one longer than a filler is a held vowel someone meant
+        "matched_untimed": kept.get("matched_untimed", 0),
+        "matched_too_long": kept.get("matched_too_long", 0),
     }
+    if block["matched_untimed"]:
+        warn(f"--filler: {block['matched_untimed']} listed word(s) in the transcript carry no usable timing and were "
+             "not removed (nothing measured to cut on)", "filler_words_untimed", count=block["matched_untimed"])
     return block, [(s["start"], s["end"]) for s in spans]
 
 
 def _words_from_transcript(data):
-    """([{word,start,end}], whether the document had segments at all) from a whisper JSON."""
+    """([{word,start,end}], whether the document had segments at all, [{word}] of the words
+    that carried no usable timing) from a whisper JSON. The third list lets --filler count a
+    listed word it could not cut instead of dropping it unseen."""
     raw, had_segments = [], False
     if isinstance(data, dict):
         raw = list(data.get("words") or [])
@@ -225,7 +237,7 @@ def _words_from_transcript(data):
             raw.extend((seg or {}).get("words") or [])
     elif isinstance(data, list):
         raw = list(data)
-    out = []
+    out, untimed = [], []
     for w in raw:
         if not isinstance(w, dict):
             continue
@@ -233,8 +245,8 @@ def _words_from_transcript(data):
             out.append({"word": str(w.get("word") or w.get("text") or ""),
                         "start": float(w["start"]), "end": float(w["end"])})
         except (KeyError, TypeError, ValueError):
-            continue
-    return out, had_segments
+            untimed.append({"word": str(w.get("word") or w.get("text") or "")})
+    return out, had_segments, untimed
 
 
 def main() -> int:
@@ -353,7 +365,7 @@ def main() -> int:
              f"{filler_info['removed_seconds']:.2f}s, from {filler_info['word_timings']} word timings "
              f"({filler_info['lang']}, list {filler_info['list']})")
         for warning in filler_info.get("warnings") or []:
-            info("warning: " + warning)
+            warn(warning, "filler_removal_caution")
     if getattr(args, "_asr_notes", None):
         # an English-only transcript made on an assumption (asr.assumed_english_note): the
         # bridge already logged the warning; the result document carries it at the top level

package/scripts/sync.py

@@ -33,6 +33,7 @@ import sys
 from typing import Dict, List
 
 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, run_analysis, x264_args, decode_pcm_mono, rms_envelope
+from _common.emit import record_skip, warn
 
 SR = 8000  # decode sample rate
 
@@ -218,6 +219,9 @@ def measure_one(reference: str, path: str, args) -> Dict:
     offset, score = measure_offset(reference, path, 0.0, args.analyze_seconds, args.step_ms, args.max_offset, args.fine_ms)
     drift_ratio = 1.0
     drift_info = None
+    # why a requested --fix-drift was not applied: too_short (no tail window far enough from
+    # the head to measure over) or low_confidence (the tail did not correlate); None when applied
+    skipped_reason = None
     if args.fix_drift:
         ref_dur = probe(reference)["duration"] or 0.0
         sec_dur = probe(path)["duration"] or 0.0
@@ -225,7 +229,10 @@ def measure_one(reference: str, path: str, args) -> Dict:
         head_len = min(args.analyze_seconds, overlap_end)
         tail_start = overlap_end - args.drift_window
         if tail_start <= head_len / 2 + 5:
-            info(f"warning: {path} too short to measure drift reliably; skipping drift correction")
+            skipped_reason = "too_short"
+            record_skip(f"{path} too short to measure drift reliably; skipping drift correction", "drift_correction_skipped",
+                        path=path, reason=skipped_reason, overlap_seconds=round(overlap_end, 3),
+                        drift_window=args.drift_window)
         else:
             ref_start = tail_start
             sec_start = tail_start - offset
@@ -251,10 +258,13 @@ def measure_one(reference: str, path: str, args) -> Dict:
                                   abs(drift_ratio - 1) * 1e6, "long/slow" if drift_ratio > 1 else "short/fast", abs(residual), elapsed),
                               "confidence": round(end_score, 3)}
             else:
-                info(f"warning: could not measure drift with confidence for {path}; skipping drift correction")
+                skipped_reason = "low_confidence"
+                record_skip(f"could not measure drift with confidence for {path}; skipping drift correction",
+                            "drift_correction_skipped", path=path, reason=skipped_reason,
+                            confidence=round(max(0.0, end_score), 3), measured_over_seconds=round(elapsed, 2))
     return {"path": path, "offset_seconds": round(offset, 4), "offset_s": round(offset, 4),
             "confidence": round(max(0.0, min(1.0, score)), 3), "drift_ratio": drift_ratio, "drift": drift_info,
-            "drift_ppm": (drift_info["drift_ppm"] if drift_info else None)}
+            "drift_ppm": (drift_info["drift_ppm"] if drift_info else None), "drift_skipped_reason": skipped_reason}
 
 
 def main() -> int:
@@ -301,10 +311,11 @@ def main() -> int:
     measured = [measure_one(args.reference, p, args) for p in args.sources]
     for p, m in zip(args.sources, measured):
         if m["confidence"] < 0.1:
-            info(f"warning: {p}: low correlation confidence; check that it shares an audio event with the reference")
+            warn(f"{p}: low correlation confidence; check that it shares an audio event with the reference",
+                 "sync_low_confidence", path=p, confidence=m["confidence"])
 
     sources_block = [{"path": p, "offset_s": m["offset_s"], "confidence": m["confidence"],
-                      **({"drift_ppm": m["drift_ppm"]} if args.fix_drift else {})}
+                      **({"drift_ppm": m["drift_ppm"], "drift_skipped_reason": m["drift_skipped_reason"]} if args.fix_drift else {})}
                      for p, m in zip(args.sources, measured)]
 
     if n_sources == 1:
@@ -323,8 +334,8 @@ def main() -> int:
         }
         if drift_info:
             result["drift"] = drift_info
-        if score < 0.1:
-            info("warning: low correlation confidence; check that both files contain the same audio event")
+        if args.fix_drift:
+            result["drift_skipped_reason"] = m["drift_skipped_reason"]
     else:
         offset = drift_ratio = drift_info = None  # not used below; output writing is 1-source only
         result = {"reference": args.reference, "sources": sources_block}

package/scripts/verify.py

@@ -15,6 +15,8 @@ Examples:
   python3 verify.py clip.mov --keep --out ./verify_out
 """
 import argparse
+import contextlib
+import io
 import json
 import os
 import subprocess
@@ -22,7 +24,7 @@ import sys
 import tempfile
 import time
 from pathlib import Path
-from typing import Dict, List
+from typing import Any, Dict, List, Optional, Tuple
 
 from _common import STATE, add_common, apply_common, die, emit, info, probe
 
@@ -67,26 +69,77 @@ def collect(paths: List[str]) -> List[Path]:
     return files
 
 
+def _cell(message: str) -> str:
+    """A failure message as one Markdown table cell: one line, no pipes, at most 200 characters."""
+    return " / ".join(line.strip() for line in str(message).splitlines() if line.strip()).replace("|", "/")[:200]
+
+
+def _probe_capturing(path: str) -> "Tuple[Optional[Dict[str, Any]], Dict[str, Any]]":
+    """probe() in this process, with its failure kept: (the probe, {}) or (None, the failure's
+    kind/reason/message). probe() dies on an unreadable file; its failure document is read back
+    instead of a fixed string standing in for it (one JSON document per run: it is not printed)."""
+    was_json, STATE.json = STATE.json, True
+    out, err = io.StringIO(), io.StringIO()
+    try:
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            return probe(path), {}
+    except SystemExit as exc:
+        try:
+            doc = json.loads(out.getvalue())
+        except ValueError:
+            doc = {}
+        e = doc.get("error") if isinstance(doc.get("error"), dict) else {}
+        failure = {k: e[k] for k in ("kind", "reason", "message") if e.get(k)}
+        failure.setdefault("message", (err.getvalue().strip().splitlines() or [f"probe exited {exc.code}"])[-1])
+        return None, failure
+    finally:
+        STATE.json = was_json
+
+
 def step(name: str, argv: List[str], timeout: float) -> Dict:
+    """Run one step and keep what its tool said: `ok` (it completed), and on a failure the tool's
+    own `kind`, `reason` and `message` (its --json failure document), `error` being that message
+    for the table. A completed step also carries the tool's `verified`."""
     t0 = time.time()
     if argv[0] == "__check_hdr__":
-        was_json, STATE.json = STATE.json, False  # probe()'s die() would print a JSON document of its own
-        try:
-            v = probe(argv[1]).get("video") or {}
-            ok = bool(v.get("bt2020_or_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"
-        finally:
-            STATE.json = was_json
-        return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
+        meta, failure = _probe_capturing(argv[1])
+        if meta is None:
+            return dict({"step": name, "ok": False, "seconds": round(time.time() - t0, 1), "error": _cell(failure.get("message", ""))}, **failure)
+        v = meta.get("video") or {}
+        ok = bool(v.get("bt2020_or_hdr")) and v.get("bit_depth", 8) >= 10
+        r: Dict[str, Any] = {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1),
+                             "error": "" if ok else f"re-encode lost HDR: {v.get('color_transfer')}/{v.get('pix_fmt')}"}
+        if not ok:
+            r.update(kind="verification", reason="hdr_lost", message=r["error"])
+        return r
     try:
-        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=timeout)
-        ok = proc.returncode == 0
-        err = "" if ok else (proc.stderr.strip().splitlines() or ["?"])[-1][:200]
+        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:] + ["--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                              text=True, encoding="utf-8", errors="replace", timeout=timeout)
     except subprocess.TimeoutExpired:
-        ok, err = False, f"timeout after {timeout:.0f}s"
-    return {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": err}
+        msg = f"timeout after {timeout:.0f}s"
+        return {"step": name, "ok": False, "seconds": round(time.time() - t0, 1), "error": msg,
+                "kind": "timeout", "reason": "step_timeout", "message": msg}
+    try:
+        doc = json.loads(proc.stdout)
+    except ValueError:
+        doc = None
+    doc = doc if isinstance(doc, dict) else {}
+    ok = proc.returncode == 0
+    r = {"step": name, "ok": ok, "seconds": round(time.time() - t0, 1), "error": ""}
+    if ok:
+        if "verified" in doc:
+            r["verified"] = doc["verified"]
+        return r
+    e = doc.get("error") if isinstance(doc.get("error"), dict) else {}
+    r["message"] = str(e.get("message") or (proc.stderr.strip().splitlines() or [f"exit {proc.returncode}"])[-1])
+    r["error"] = _cell(r["message"])
+    for k in ("kind", "reason", "details"):
+        if e.get(k) is not None:
+            r[k] = e[k]
+    if not e:
+        r["reason"] = "step_output_unparsed"
+    r["exit_code"] = proc.returncode
+    return r
 
 
 def main() -> int:
@@ -117,16 +170,13 @@ def main() -> int:
     results = []
     for f in files:
         info(f"=== {f}")
-        entry: Dict = {"file": str(f), "steps": []}
-        was_json, STATE.json = STATE.json, False  # same: one JSON document per run, printed at the end
-        try:
-            meta = probe(str(f))
-        except SystemExit:
-            entry["steps"].append({"step": "probe", "ok": False, "seconds": 0, "error": "ffprobe failed"})
+        entry: Dict = {"file": str(f), "steps": [], "skipped": []}
+        meta, failure = _probe_capturing(str(f))
+        if meta is None:
+            entry["steps"].append(dict({"step": "probe", "ok": False, "seconds": 0, "error": _cell(failure.get("message", ""))}, **failure))
+            entry["skipped"].append({"step": "*", "reason": "input_unreadable", "message": "no other step runs on a file probe cannot read"})
             results.append(entry)
             continue
-        finally:
-            STATE.json = was_json
         entry["probe"] = {k: meta.get(k) for k in ("duration", "format")}
         entry["probe"]["video"] = {k: (meta.get("video") or {}).get(k) for k in ("codec", "width", "height", "fps", "pix_fmt", "hdr_format", "rotation", "variable_frame_rate_suspected")}
         entry["probe"]["audio"] = {k: (meta.get("audio") or {}).get(k) for k in ("codec", "channels", "sample_rate")}
@@ -138,6 +188,10 @@ def main() -> int:
         seg_end = min(dur, args.seconds) if dur else args.seconds
         fast = ["--fast"]
         plan = []
+        skipped: List[Dict[str, str]] = entry["skipped"]
+
+        def skip(step_name: str, reason: str, message: str) -> None:
+            skipped.append({"step": step_name, "reason": reason, "message": message})
         plan.append(("cut copy", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "-o", cut]))
         if has_v:
             plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))
@@ -152,12 +206,30 @@ def main() -> int:
                     plan.append(("color to-sdr", ["color.py", f"{stem}_acc.mp4", "--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"]))
+            else:
+                for n in ("overlay text", "look sheet", "color to-sdr", "hdr preserved", "probe analyze"):
+                    skip(n, "quick", "--quick runs probe, copy cut, fit, caption and export only")
+            if not args.quick and not (meta.get("video") or {}).get("bt2020_or_hdr"):
+                for n in ("color to-sdr", "hdr preserved"):
+                    skip(n, "not_hdr", "the file is not HDR")
             plan.append(("export x", ["export.py", cut, "--preset", "x", "-o", f"{stem}_x.mp4"]))
+        else:
+            for n in ("cut accurate", "fit 9:16", "caption", "overlay text", "look sheet", "color to-sdr", "hdr preserved",
+                      "probe analyze", "export x"):
+                skip(n, "no_video", "the file has no video stream")
         if has_a and not args.quick:
             plan.append(("loudness measure", ["loudness.py", str(f), "--measure-only"]))
             plan.append(("silence list", ["silence.py", cut, "--list"]))
             if (meta.get("audio") or {}).get("channels", 0) > 2:
                 plan.append(("audio downmix", ["audio.py", cut, "--downmix", "-o", f"{stem}_st.mp4"]))
+            else:
+                skip("audio downmix", "not_multichannel", "the audio has 2 channels or fewer")
+        elif not has_a:
+            for n in ("loudness measure", "silence list", "audio downmix"):
+                skip(n, "no_audio", "the file has no audio stream")
+        else:
+            for n in ("loudness measure", "silence list", "audio downmix"):
+                skip(n, "quick", "--quick runs probe, copy cut, fit, caption and export only")
         for name, argv in plan:
             r = step(name, argv, args.timeout)
             entry["steps"].append(r)
@@ -179,6 +251,8 @@ def main() -> int:
         lines.append("|---|---|---|---|")
         for s in e["steps"]:
             lines.append(f"| {s['step']} | {'PASS' if s['ok'] else 'FAIL'} | {s['seconds']}s | {s['error']} |")
+        for s in e.get("skipped") or []:
+            lines.append(f"| {s['step']} | SKIP | - | {s['message']} |")
         lines.append("")
     report = "\n".join(lines)
     if args.report:

package/scripts/waveform.py

@@ -38,7 +38,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import (add_common, apply_common, aac_args, default_output, die, draws_chroma, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs)
-from _common.emit import absorb_stage_hw
+from _common.emit import absorb_stage_hw, warn
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -272,7 +272,8 @@ def main() -> int:
                          f"{overlap}px: the captions or the app's own UI will sit over the waveform "
                          f"(lower --vis-height to {max(0.05, (args.height - safe_px) / args.height):.2f})")
     if silent_peak is not None:
-        info(f"warning: {args.input} is silent (peak {silent_peak:g} dBFS); the visualisation is a flat line")
+        warn(f"{args.input} is silent (peak {silent_peak:g} dBFS); the visualisation is a flat line", "silent_input",
+             path=args.input, peak_db=silent_peak)
         notes.append(f"the input audio is silent (peak {silent_peak:g} dBFS, at or below --silence-threshold "
                      f"{args.silence_threshold:g}): the visualisation is a flat line; pass --on-silent fail to refuse instead")
     duration_ok = True