ffmpeg-skill 2.11.0 → 2.12.1

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