ffmpeg-skill 3.8.8 → 3.8.9

package/README.md

@@ -400,7 +400,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Filler words (1.17).** `silence.py --filler --words transcript.json` removes "um" and "uh" through the same cut graph the silences use. Never without measured word timings — there is no heuristic that finds an "um" without them that would not also cut real speech — and `like`, `tipo` and `cioè` are deliberately not in the built-in lists, because a discourse marker is a content word. Built-in lists since 2.19: English, Japanese, Korean, Chinese, Spanish, German, French, Portuguese, Italian, Dutch, Polish, Russian and Turkish; any other language takes `--filler-words FILE`. Whisper stays optional: `--transcribe` with no engine installed refuses and names the five installs.
 - **Throughput (1.17).** `batch.py --jobs N` runs several files at once, capped at `min(N, cpu_count, 8)` and sharing one `--timeout` budget rather than one per item; the per-item table keeps its order. `render.py --cache DIR` reuses stages whose inputs and arguments did not change, so swapping an export preset re-runs export only. The cache is opt-in with no default directory, and the ffmpeg, skill and contract versions are part of every key, so a cache is never reused across them.
 - **Audiogram (1.16).** `waveform.py --image cover.png` (or `render.py --template audiogram`) puts the waveform over a still plate for an episode that has no picture, with `--platform` for the frame, `--title` and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.
-- **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji/Noto naming, `1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the run still succeeds and reports `mode: mono`. Nothing is ever downloaded.
+- **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji naming, `1f389.png`, or Noto's `emoji_u1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the result's `emoji.mode` says which of three things happened: `color` when this build's libass draws the colour glyph (also for `--emoji mono` on such a build, with a warning), `mono` when it draws a monochrome one, and `none` when nothing here draws the glyph, in which case the emoji are left out of the text with an `emoji_not_drawn` warning (and a `graphics.py` title that is nothing but emoji is refused). Nothing is ever downloaded.
 - **Indic and Thai text shaped correctly in titles and lower-thirds (1.15).** `graphics.py` renders Devanagari, Bengali, Tamil, Thai and Lao through libass automatically (`text_renderer: "ass"`), because drawtext never reorders matras or re-clusters marks; Arabic and Hebrew were already correct on a fribidi build. `--text-render drawtext` with such a script is refused, never rendered wrongly.
 - **Non-Latin text picks a font by script (1.12).** Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (`kind: input`) instead of rendering boxes. `doctor --json`'s `fonts.scripts` says which languages this machine can render; `--lang ja|ko` disambiguates Han-only text, and `--lang zh-TW` (or `zh-HK`, `zh-Hant`) picks a Traditional Chinese face (2.19); an explicit `--font`/`--font-file` is always kept.
 - **Silence detection finds nothing?** The default threshold is −35 dBFS. The tool prints a hint with the track's measured level; raise the threshold (`silence.py --threshold -25`) or shorten `--min-silence`.

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.8`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.9`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.8", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.9", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -878,7 +878,17 @@ An ffmpeg run that fails keeps `kind: ffmpeg` and exit code 1, and since 3.1.0 c
 (`_common.runner.FFMPEG_FAILURE_CLASSES`): `disk_full` ("No space left on device"),
 `encoder_missing` and `filter_missing` (`details.name`; the build lacks it, `doctor` says how to
 get one that has it), `input_incomplete` ("moov atom not found": a cut-off recording or an
-unfinished copy, which `--repair` cannot rebuild) and `input_unreadable`. A tool that copies the
+unfinished copy, which `--repair` cannot rebuild) and `input_unreadable`. After 3.8.4 an ffmpeg
+command a tool runs through `run()` that names an encoder (`-c:v`/`-c:a`/`-c:s` and their
+spellings, after the last input, for a stream kind the output keeps: not one `-an`/`-vn`/`-sn`
+drops or no input file carries) or a filter (`-vf`, `-af`, `-filter:v`, `-filter:a`,
+`-filter_complex`, `-lavfi`) the build's own list lacks is refused with that same `kind`, `reason`
+and `details.name` before ffmpeg runs, under `--dry-run` too
+(`_common.runner._check_build_components()`). Not checked: a measurement pass run through
+`run_analysis()` (`loudness.measure()` and its loudnorm filter, for one: a pass that reports its
+own failure carries ffmpeg's `reason` after the run, `ffmpeg_failure_extra()`), a VideoToolbox encoder,
+a `-filter_complex_script` or lavfi input, an explicit `-map` selection, and any command when the
+list could not be read (that refuses nothing). A tool that copies the
 source's subtitle and data streams retried the whole encode without them after any failure; it
 now retries only when the source has such a stream and the failure is none of these.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.8",
+  "version": "3.8.9",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/references/gotchas.md

@@ -271,9 +271,11 @@ directory of PNGs — and on most builds only the second one exists.
   to 48 pixels: invalid library handle`, and at the font's own strike
   `Monocromatic (1bpp) fonts are not supported.`) and no file is written. That
   is why the colour route is a PNG overlay, never a drawtext font.
-- **PNGs**: `--emoji-assets DIR`, a directory of files named by code point in
-  the Twemoji/Noto convention — lowercase hex joined by `-`: `1f389.png`,
-  `1f1ef-1f1f5.png`, `1f469-200d-1f4bb.png`. Twemoji's `assets/72x72`
+- **PNGs**: `--emoji-assets DIR`, a directory of files named by code point:
+  Twemoji's lowercase hex joined by `-` (`1f389.png`, `1f1ef-1f1f5.png`,
+  `1f469-200d-1f4bb.png`), or Noto Emoji's `emoji_u` names, each code point at
+  least four hex digits, joined by `_` (`emoji_u1f389.png`,
+  `emoji_u0031_20e3.png`). Twemoji's `assets/72x72`
   (CC-BY 4.0) and Noto Emoji's `png/128` (OFL/Apache-2.0) are the two people
   already have. **The skill never downloads anything**: a missing directory is
   `kind: input`, never a silent fetch. The same directory can come from

package/references/scripts.md

@@ -353,7 +353,9 @@ the stored size, because the filter measures the picture after ffmpeg applies
 the tag. Distinct from
 `fit.py --fit crop`, which crops to a target aspect ratio it computes
 itself with no black-bar measurement involved. A rectangle that matches the
-full source frame means no bars were found. Does not decide whether
+full source frame means no bars were found: a picture that reaches every edge
+is reported as the frame itself, and `--round` (default 16) rounds a detected
+crop only (1080 is not a multiple of 16). Does not decide whether
 removing detected bars is wanted -- genuine letterboxed content (a
 scope-ratio film in a 16:9 frame) "detects" the same way as accidental
 bars; look at the frame before cropping it away. `windows` / `windows_failed`
@@ -653,7 +655,8 @@ metadata.py INPUT [--chapters chapters.txt | --clear-chapters | --auto-chapters]
                   [--title T] [--artist A] [--album A] [--comment C] [--date D] [--genre G] [-o OUT]
 ```
 `chapters.txt` holds one chapter per line, `TIME TITLE` (cut.py's time syntax:
-seconds, mm:ss, hh:mm:ss.ms); each chapter ends where the next starts and the
+seconds, mm:ss, hh:mm:ss.ms; a `-`, dash, `|` or `:` between the two, as in
+`0:00 - Intro`, is not part of the title); each chapter ends where the next starts and the
 last runs to the end of the file. Starts must ascend and lie inside the file.
 Every stream is `-c copy` (bit for bit; `probe` reports the result under
 `chapters` and `tags`), so this is instant and lossless. Chapter markers need a
@@ -766,7 +769,7 @@ leaves none. A dry run writes nothing.
 **`--filler` (1.17)** removes filler words as well, through the same
 `keep_ranges()` graph with more, shorter ranges. It is **never**
 applied without measured word timings: pass `--words` (a whisper JSON carrying
-per-word `start`/`end`) or `--transcribe` (the same local engine `caption.py`
+per-word `start`/`end`, or whisper.cpp's `--output-json-full` document) or `--transcribe` (the same local engine `caption.py`
 uses, never required). There is no heuristic fallback — finding an "um" by
 looking for short quiet blips would cut real speech, so the tool refuses
 instead. `--filler-list` reports what would go and writes nothing.
@@ -871,7 +874,9 @@ packet count must equal the clips' total and its video length their summed lengt
 `copy`. `--copy` does not take `--width`, `--height`, `--fps`, `--sample-rate`, `--channels` or a transition, and an
 audio-only join (which resamples every clip to one format) is refused with it.
 `--list FILE` (2.2) reads the clips from a file, one per line in order, paths relative to the
-file (blank lines and `#` comments ignored; ffmpeg's `file 'x.wav'` lines accepted), for the
+file (blank lines and `#` comments ignored; ffmpeg's `file 'x.wav'` lines and the `ffconcat version` header accepted,
+any other concat directive -- `inpoint`, `outpoint`, `duration`, the argument-free `stream` -- refused, since join.py
+applies none, unless the line names a file that is there), for the
 segments a TTS or render step wrote. Every input -- listed or given as arguments -- is checked
 before anything runs: missing, empty (0 bytes) or unreadable as media. By default all of them
 are named in one refusal (`kind: input`, `problems: [{index, path, reason}]`, nothing encoded);
@@ -1795,8 +1800,8 @@ stays text (escaped), and under `--karaoke` `<font color>` is dropped for the hi
 colours. The ASS is kept next to the
 user can hand-tune timings and re-run with `--ass`.
 Emoji (1.15): `--emoji-assets DIR` is a directory of PNGs named by code point
-(`1f389.png`, `1f1ef-1f1f5.png`, `1f469-200d-1f4bb.png` — the Twemoji/Noto
-convention), also read from `brand.json` `styles.caption.emoji_assets` and
+(`1f389.png`, `1f1ef-1f1f5.png`, `1f469-200d-1f4bb.png` — the Twemoji
+convention; Noto Emoji's `emoji_u1f389.png`, `emoji_u0031_20e3.png` are found too), also read from `brand.json` `styles.caption.emoji_assets` and
 `FFMPEG_SKILL_EMOJI_ASSETS`. With one, the cue text keeps its place in the ASS
 with an invisible placeholder reserving the emoji's box and each PNG is
 composited on top (`--emoji-scale` sizes the box, `--emoji-max` caps the count).

package/scripts/_common/asr.py

@@ -128,11 +128,22 @@ def srt_timing_times(line: str) -> Tuple[str, str]:
     return a.strip(), words[0] if words else ""
 
 
+# WebVTT's inline word timestamps and its class, voice and language spans (YouTube's automatic
+# captions: `hello<00:00:01.500><c> world</c>`); <i>, <b> and <u> are SRT's too and stay
+_VTT_INLINE = re.compile(r"<\d{1,2}:\d{2}(?::\d{2})?\.\d{3}>|</?(?:c|v|lang)(?:[.\s][^>]*)?>")
+
+
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
-    for times, body in srt_blocks(read_text_or_die(path, "--srt")):
+    source = read_text_or_die(path, "--srt")
+    # only in a file that says it is WebVTT: ffmpeg's own WebVTT reader drops these tags, and the
+    # cues this function returns were burned with them in the text (#404)
+    vtt = source.lstrip().upper().startswith("WEBVTT")
+    for times, body in srt_blocks(source):
         a, b = srt_timing_times(times)
         text = "\n".join(body).strip()
+        if vtt:
+            text = _VTT_INLINE.sub("", text).strip()
         try:
             cues.append((parse_time(a), parse_time(b), text))
         except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames

package/scripts/_common/drawtext.py

@@ -121,6 +121,17 @@ def drawtext_shaping() -> "Dict[str, bool]":
     return dict(_SHAPING_BUILD_CACHE)
 
 
+def shaping_refusal(script: str) -> str:
+    """Why drawtext cannot draw `script` here, as the clause after "<Language> text": on any build
+    for the scripts harfbuzz reorders, on this build for Arabic and Hebrew, which a build with
+    fribidi draws (#402: both were refused as "on any ffmpeg build")."""
+    if script in BIDI_SCRIPTS:
+        return ("cannot be shaped by drawtext on this ffmpeg build (it was built without libfribidi, which "
+                "drawtext needs for right-to-left order and Arabic joining; a build with it draws this text)")
+    return ("cannot be shaped by drawtext on any ffmpeg build (the marks are reordered by harfbuzz, which "
+            "drawtext does not use)")
+
+
 def needs_shaping(script: str) -> bool:
     """Whether drawtext would render `script` wrongly on this build."""
     if script in SHAPING_SCRIPTS:

package/scripts/_common/emit.py

@@ -778,8 +778,10 @@ def decode_step(path: str, meta: Dict[str, Any], kinds: Sequence[str], window: f
             # (bounded, so a failing hour-long stream is not decoded whole)
             frames[kind]["tail"] = tail_frames(max(0.0, end - origin - window - DECODE_LONG_GOP_SECONDS))
     bad = [k for k in kinds if not all(frames[k].values())]
+    # no provenance: it says where an expected value came from, and this step has none (#403: it
+    # said "measurement", which is not one of the contract's values)
     step: Dict[str, Any] = {"step": "decode", "property": "decodable", "frames": frames, "window": window,
-                            "provenance": "measurement", "ok": not bad}
+                            "ok": not bad}
     if bad:
         step["undecodable"] = [k for k in bad if k not in unmeasured]
     if unmeasured:

package/scripts/_common/emoji.py

@@ -187,7 +187,7 @@ def has_emoji(text: str) -> bool:
 
 def emoji_codepoint_name(cluster: str) -> str:
     """The asset filename stem for a cluster: lowercase hex code points joined by '-', the
-    Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
+    Twemoji convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5); emoji_asset_for() also tries Noto's."""
     return "-".join(f"{ord(c):x}" for c in cluster)
 
 
@@ -214,13 +214,36 @@ def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]
     if not assets_dir or not os.path.isdir(assets_dir):
         return None
     for name in _emoji_name_candidates(cluster):
-        for ext in (".png", ".PNG"):
-            candidate = os.path.join(assets_dir, name + ext)
-            if os.path.isfile(candidate):
-                return candidate
+        # Twemoji's name (1f469-200d-1f4bb.png, 31-20e3.png), then Noto Emoji's, whose code points
+        # are at least four hex digits (emoji_u1f469_200d_1f4bb.png, emoji_u0031_20e3.png): the hint
+        # names noto-emoji/png/128, whose files were never found (#404)
+        for stem in (name, "emoji_u" + "_".join(cp.zfill(4) for cp in name.split("-"))):
+            for ext in (".png", ".PNG"):
+                candidate = os.path.join(assets_dir, stem + ext)
+                if os.path.isfile(candidate):
+                    return candidate
     return None
 
 
+def emoji_mono_on_colour_note(support: "Dict[str, Any]") -> str:
+    """--emoji mono on a build whose libass draws the emoji face in colour: nothing here makes that
+    glyph monochrome (mono and color build the same text), so the result says color (#403: the
+    warning said "no colour path" beside a detail saying it renders in colour)."""
+    return ("--emoji mono: libass draws the emoji face in colour on this build and nothing here makes it "
+            "monochrome, so the emoji are drawn in colour (mode: color). " + str(support.get("detail") or ""))
+
+
+def emoji_missing_asset_note(missing: "List[str]", support: "Dict[str, Any]") -> str:
+    """What happens to the clusters --emoji-assets has no PNG for: they stay in the text for libass,
+    which is said as measured (libass_glyph), not as "drawn by the text font" (#403)."""
+    names = ", ".join(missing)
+    if support.get("libass_glyph") is False:
+        return (f"no PNG in the assets directory for {names} -- those clusters stay in the text, and libass draws no "
+                "emoji glyph on this build: an empty box at best")
+    return (f"no PNG in the assets directory for {names} -- those clusters stay in the text for libass to draw "
+            "with an installed face" + ("" if support.get("libass_glyph") else " (whether one has the glyph was not measured)"))
+
+
 EMOJI_ASSET_HINT = (
     "point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
     "twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "

package/scripts/_common/probe.py

@@ -13,7 +13,7 @@ import statistics
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
-from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
+from _common.runner import ffmpeg_failure_extra, STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
 # The streams probe() describes, as stream specifiers: its `video` is the first picture that is not
 # a cover (`V`), its `audio` the first sound stream. Without a -map, FFmpeg picks the largest
@@ -63,7 +63,7 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
     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")
+            die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr.decode(errors="replace")))
         return []
     n = len(proc.stdout) // 2
     import struct
@@ -113,7 +113,7 @@ def decode_gray_frames(path: str, fps: float, width: int, height: int, *, start:
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         if check:
-            die(f"could not decode frames from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg")
+            die(f"could not decode frames from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr.decode(errors="replace")))
         return []
     frame_size = width * height
     data = proc.stdout
@@ -208,10 +208,12 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
 
     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 not os.path.exists(path) or (role == "output" and STATE.dry_run):
         if role == "output" and not STATE.dry_run:
             _output_failed(path, "not written")
         if STATE.dry_run:
+            # also for an output path that holds a file: a dry run did not write it, and reading it
+            # reported an earlier run's file as this plan's result (#403: cut.py's output_duration)
             # 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,
@@ -840,6 +842,24 @@ def measure_signal_range(path: str, standard: str, window: float = 10.0,
     return doc
 
 
+def refuse_not_a_still(path: str, meta: Dict[str, Any], flag: str, instead: str) -> None:
+    """`flag` takes a still image and is read with `-loop 1`, an option of the image demuxers only:
+    a video or a GIF (one frame or many: the gif demuxer has no such option) given there failed as
+    "Option loop not found" / "Option framerate not found", naming neither the file nor the flag
+    (#404). `instead` says what takes a video."""
+    fmt = str(meta.get("format") or "")
+    if STATE.dry_run and meta.get("dry_run"):
+        return  # a pending input: nothing was read
+    if fmt == "image2" or fmt.endswith("_pipe"):
+        return
+    if fmt == "gif":
+        die(f"{flag} {path} is a GIF, and {flag} reads a still image through the image demuxers, which do not "
+            "open GIF: convert it to PNG first (`look.py FILE --at 0 -o still.png` writes its first frame)", kind="input")
+    length = meta.get("duration")
+    die(f"{flag} {path} is not a still image: it is a {fmt.split(',')[0] or 'media'} file"
+        + (f" ({length:.3f}s)" if length else "") + f", and {flag} is read as one picture", kind="input", hint=instead)
+
+
 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.
 
@@ -1023,7 +1043,7 @@ def detect_silences(path: str, threshold: float, min_silence: float) -> "List[Tu
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
     proc = run_analysis(cmd, check=False, record=True)
     if proc.returncode != 0:
-        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
+        die(f"silencedetect failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
     silences: "List[Tuple[float, float]]" = []
     start = None
     for kind, val in SIL_RE.findall(proc.stderr):
@@ -1085,7 +1105,7 @@ def detect_content(path: str, duration: float, *, video: bool = True, audio: boo
         cmd += ["-map", "0:a:0", "-af", f"silencedetect=noise={SILENT_PEAK_DBFS:g}dB:d={CONTENT_SILENCE_MIN}"]
     proc = run_analysis(cmd + ["-f", "null", "-"], check=False, record=True)
     if proc.returncode != 0:
-        die(f"content detection failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
+        die(f"content detection failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
     end = max(duration, 0.0)
     out: Dict[str, Any] = {}
     if video:
@@ -1129,7 +1149,7 @@ def _detect_dropouts(path: str, end: float) -> "List[Tuple[float, float]]":
                          f"silencedetect=noise={CONTENT_DROPOUT_DB:g}dB:d={CONTENT_DROPOUT_MIN}", "-f", "null", "-"],
                         check=False, record=True)
     if proc.returncode != 0:
-        die(f"dropout detection failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
+        die(f"dropout detection failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
     gaps: "List[Tuple[float, float]]" = []
     start = None
     for kind, val in SIL_RE.findall(proc.stderr):

package/scripts/_common/runner.py

@@ -1048,7 +1048,7 @@ _CODEC_OPTION_RE = re.compile(r"^-(?:c|codec)(?::([va])(?::\d+)?)?$|^-(v|a)codec
 
 
 def _an_input_has(cmd: Sequence[str], kind: str) -> bool:
-    """False only when every input of `cmd` is a file that was read and holds no `kind` ("v"/"a")
+    """False only when every input of `cmd` is a file that was read and holds no `kind` ("v"/"a"/"s")
     stream, and no filter graph could make one. An encoder option for a stream the output will
     not have selects nothing (FFmpeg applies -c:a after stream selection), so it is not a reason
     to refuse: cut.py names -c:a aac for a silent source too. Anything not known counts as present."""
@@ -1110,6 +1110,120 @@ def _check_container_codecs(cmd: Sequence[str]) -> None:
                output=output, container="webm", encoders=refused)
 
 
+# the options whose value is a filter graph this module can read the filter names out of
+_GRAPH_OPTIONS = frozenset({"-vf", "-af", "-filter:v", "-filter:a", "-filter_complex", "-lavfi"})
+_ENCODER_OPTION_RE = re.compile(r"^-(?:c|codec):([vas])(?::\d+)?$|^-([vas])codec$")
+# the output option that drops every stream of a kind: an encoder named for that kind selects nothing
+_NO_STREAM_OPTION = {"v": "-vn", "a": "-an", "s": "-sn"}
+# one row of `ffmpeg -encoders` / `ffmpeg -filters` (the filter row by its io-spec token, so the
+# flag-column width of FFmpeg 6/7 and 8+ does not matter): ffmpeg_encoders(), ffmpeg_filters()
+_ENCODER_ROW = r"^\s*[VAS][.\w]{5}\s+(\S+)"
+_FILTER_ROW = r"^\s*(?:[A-Z.|]{1,6}\s+)?([A-Za-z0-9_]+)\s+\S*->\S*"
+# quiet reads of a list the tool itself never asked for: {"-encoders": names, "-filters": names}
+_PREFLIGHT_LISTS: Dict[str, set] = {}
+
+
+def graph_filter_names(graph: str) -> List[str]:
+    """The filter names of one filter graph string, in order, without duplicates. A `,` or `;`
+    separates filters only outside '...' quotes and when no backslash escapes it; `[labels]` before
+    a filter and its `=options` / `@instance` are dropped. A graph-level `sws_flags=` is not a
+    filter and is left out, as is anything that is not a plain identifier."""
+    parts: List[str] = []
+    cur: List[str] = []
+    quoted = False
+    i = 0
+    while i < len(graph):
+        ch = graph[i]
+        if ch == "\\" and i + 1 < len(graph):
+            cur.append(graph[i:i + 2])
+            i += 2
+            continue
+        if ch == "'":
+            quoted = not quoted
+        elif ch in ",;" and not quoted:
+            parts.append("".join(cur))
+            cur = []
+            i += 1
+            continue
+        cur.append(ch)
+        i += 1
+    parts.append("".join(cur))
+    names: List[str] = []
+    for part in parts:
+        part = part.strip()
+        while part.startswith("["):
+            end = part.find("]")
+            if end < 0:
+                break
+            part = part[end + 1:].lstrip()
+        m = re.match(r"[A-Za-z0-9_]+", part)
+        if not m or m.end() < len(part) and part[m.end()] not in "=@[ \t":
+            continue
+        if m.group(0) != "sws_flags" and m.group(0) not in names:
+            names.append(m.group(0))
+    return names
+
+
+def _build_list(flag: str) -> set:
+    """This build's encoder or filter names for the check below: the list a tool already read, else
+    one quiet read. A list that cannot be read is empty here and refuses nothing; the
+    `ffmpeg_list_unreadable` warning stays with the tools that decide something on the list."""
+    cached = _ENCODERS if flag == "-encoders" else _FILTERS
+    if cached is not None:
+        return cached
+    if flag not in _PREFLIGHT_LISTS:
+        _PREFLIGHT_LISTS[flag] = _read_ff_list(flag, _ENCODER_ROW if flag == "-encoders" else _FILTER_ROW, quiet=True)
+    return _PREFLIGHT_LISTS[flag]
+
+
+def _check_build_components(cmd: Sequence[str]) -> None:
+    """An encoder or a filter the command names and this ffmpeg build does not have is refused
+    before anything runs, dry runs included, with the kind, reason and hint the run got from
+    ffmpeg's "Unknown encoder" / "No such filter" (#402): the dry run said completed, and a real
+    run found out after its earlier commands had run. Read from the command as built, so every tool
+    and every route to an encoder (an HDR source kept as HEVC, --codec, a preset) is covered.
+    Only output options are read (a -c:v before an -i picks a decoder), and an encoder only for a
+    stream kind the output keeps: not one -an/-vn/-sn drops or no input file carries. A VideoToolbox encoder is
+    left to --hw's own checks and its CPU retry, a -filter_complex_script and a lavfi input are not
+    parsed, and a list that could not be read refuses nothing."""
+    last_input = max((i for i, tok in enumerate(cmd[:-1]) if tok == "-i"), default=-1)
+    encoders: List[str] = []
+    streams: Dict[str, set] = {}  # encoder -> the stream kinds ("v", "a", "s") it is named for
+    filters: List[str] = []
+    output_opts = {str(tok) for tok in cmd[last_input + 2:-1]}
+    for i in range(1, len(cmd) - 1):
+        tok, value = str(cmd[i]), str(cmd[i + 1])
+        m = _ENCODER_OPTION_RE.match(tok)
+        if tok in _GRAPH_OPTIONS:
+            filters += [n for n in graph_filter_names(value) if n not in filters]
+        elif i > last_input and m and value != "copy" and not value.endswith("_videotoolbox"):
+            if value not in encoders:
+                encoders.append(value)
+            streams.setdefault(value, set()).add(m.group(1) or m.group(2))
+
+    def selected(name: str) -> bool:
+        # ffmpeg picks an encoder per output stream, after stream selection: one named for a kind
+        # the output drops (-an/-vn/-sn) or that no input carries (cut.py names -c:a aac for a
+        # silent source too) is never opened. What the command cannot tell (a -filter_complex graph, a
+        # lavfi or unreadable input) counts as selected; explicit -map lists are not read.
+        return any(_NO_STREAM_OPTION[k] not in output_opts and _an_input_has(cmd, k) for k in streams.get(name, ()))
+
+    for flag, wanted, what, reason in (("-encoders", encoders, "encoder", "encoder_missing"),
+                                       ("-filters", filters, "filter", "filter_missing")):
+        have = _build_list(flag) if wanted else set()
+        missing = [n for n in wanted if n not in have] if have else []
+        if what == "encoder":
+            missing = [n for n in missing if selected(n)]  # asked last: only an encoder that would be refused is probed for
+        if missing:
+            name = missing[0]
+            hint = filter_missing_hint(name) if what == "filter" else filter_missing_hint(name).replace(
+                f"no {name} filter", f"no {name} encoder", 1)
+            die(f"this ffmpeg build has no {name} {what}, which the command this run builds needs"
+                + (f" (also missing: {', '.join(missing[1:])})" if missing[1:] else ""),
+                code=1, kind="ffmpeg", hint=hint,
+                error_extra={"reason": reason, "details": {"name": name}})
+
+
 EVEN_SCALE = "scale=trunc(iw/2)*2:trunc(ih/2)*2"
 
 
@@ -1904,6 +2018,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
         _check_container_codecs(cmd)
+        _check_build_components(cmd)
         _check_existing_output(cmd)
         ctx.commands.append(_cmdline(cmd))
     if not quiet:
@@ -2128,6 +2243,16 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+def ffmpeg_failure_extra(stderr: str) -> Dict[str, Any]:
+    """The die() keywords that carry the cause ffmpeg named in `stderr` -- a missing encoder or
+    filter, a full disk, an unreadable input -- as `hint` and the error's `reason`/`details`, or {}
+    when it named none (#402): a tool that composes its own failure message (cut.py's re-encode, a
+    measurement pass) reports the cause as run()'s own failures do. Used as
+    `die(msg, kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))`, through the caller's own die."""
+    cls = classify_ffmpeg_failure(stderr or "")
+    return {"hint": cls[1], "error_extra": {"reason": cls[0], "details": cls[2]}} if cls else {}
+
+
 def fail_if_classified(proc: subprocess.CompletedProcess) -> None:
     """Stop with a failed attempt's own error when ffmpeg named a cause a second encode would hit
     the same way (a full disk, a missing encoder or filter, an unreadable input): the rule
@@ -2543,7 +2668,7 @@ def ffmpeg_encoders() -> set:
     refusal or a CPU note built on the empty set names the read failure, not a missing encoder."""
     global _ENCODERS
     if _ENCODERS is None:
-        _ENCODERS = _read_ff_list("-encoders", r"^\s*[VAS][.\w]{5}\s+(\S+)")
+        _ENCODERS = _read_ff_list("-encoders", _ENCODER_ROW)
     return _ENCODERS
 
 
@@ -2565,7 +2690,7 @@ def ffmpeg_filters() -> set:
     flag-column width of FFmpeg 6/7 (three) and 8+ (two) does not matter."""
     global _FILTERS
     if _FILTERS is None:
-        _FILTERS = _read_ff_list("-filters", r"^\s*(?:[A-Z.|]{1,6}\s+)?([A-Za-z0-9_]+)\s+\S*->\S*")
+        _FILTERS = _read_ff_list("-filters", _FILTER_ROW)
     return _FILTERS
 
 
@@ -2605,12 +2730,13 @@ def ffmpeg_list_error(flag: str) -> Optional[str]:
     return None if cache else _LIST_ERRORS.get(flag)
 
 
-def _read_ff_list(flag: str, pattern: str) -> set:
+def _read_ff_list(flag: str, pattern: str, quiet: bool = False) -> set:
     tool = "ffprobe" if STATE.dry_run else "ffmpeg"
     # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
     # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
     limit = _probe_limit()
-    _LIST_ERRORS.pop(flag, None)
+    if not quiet:
+        _LIST_ERRORS.pop(flag, None)
     names: set = set()
     why = None
     try:
@@ -2625,6 +2751,8 @@ def _read_ff_list(flag: str, pattern: str) -> set:
         why = f"{tool} {flag} did not answer within {limit:g} s"
     except (OSError, subprocess.SubprocessError) as exc:
         why = f"{tool} {flag} could not run: {exc}"
+    if why and quiet:
+        return set()
     if why:
         _LIST_ERRORS[flag] = why
         what = {"-encoders": "encoder", "-decoders": "decoder", "-bsfs": "bitstream filter"}.get(flag, "filter")