ffmpeg-skill 3.8.8 → 3.8.10

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 the emoji are left out of the text: with an `emoji_not_drawn` warning when that happened because nothing here draws the glyph, and with only an info line when `--emoji none` asked for it (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.10`) | 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.10", "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.10",
   "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

@@ -193,7 +193,8 @@ libass and drawtext draw an empty box per character they have no glyph for, and
 ffmpeg still exits 0 — a video full of tofu is the classic "it worked" failure.
 Since 1.12 `caption.py`, `graphics.py` and `overlay.py --text` detect the script
 of the text they are about to draw (Japanese, Chinese, Korean, Arabic, Hebrew,
-Devanagari, Bengali, Tamil, Thai, Lao, Cyrillic, Greek) and resolve a font file that covers it,
+Devanagari, Bengali, Tamil, Thai, Lao, Cyrillic, Greek; after 3.8.7 also Gurmukhi, Gujarati,
+Telugu, Kannada, Malayalam, Sinhala, Khmer and Myanmar) and resolve a font file that covers it,
 printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.
 **No font for the script is a failed job** (`kind: input`), not a warning.
 
@@ -271,9 +272,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);
@@ -1735,7 +1740,9 @@ paraphrase a caption to make it fit. Below the floor the cue is split exactly as
 before and `fit_exhausted: true` says so, with `--min-size` named as the flag
 that would go smaller and `|` as the manual break. `--min-size` above `--size`
 is a `kind: input` refusal. `--mode mux` is unaffected: soft subtitles carry no
-size, so the SRT is the one 1.16 wrote.
+size, so a muxed track is neither fitted, wrapped nor split (a player wraps it at
+the size it draws it; through 3.8.7 it was wrapped at the burn-in size), and
+`--max-lines` or `--wrap measured` with `--mode mux` is refused.
 
 Results, alongside the existing caption stats:
 `fit_size`, `size_requested`, `size_used`, `size_floor`, `size_pct_height`,
@@ -1795,8 +1802,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).
@@ -1841,10 +1848,14 @@ never changes: **R1** never inside a word, and a hyphenated token may break only
 after its hyphen (never after a non-breaking `‑`, nor a leading/trailing
 one); **R2** no line that is a lone digit, one or two punctuation characters, or
 a single kana, checked at every boundary rather than only the last; **R3** for
-Japanese and Chinese, a break is preferred after `。、！？」』）` and (Japanese
+Japanese and Chinese, a break is preferred after `。、！？」』），；：` and (Japanese
 only) after a particle — a particle attaches to the word before it, so kinsoku
 forbids opening a line with one — discouraged between a kanji stem and its
-okurigana, and forbidden before a small kana, `ー` or a closing bracket; **R4**
+okurigana, and forbidden before a small kana, `ー`, a closing bracket or the
+fullwidth `，；：．` (and after an opening bracket); in `phrase` mode the first
+fill does not take such a break either while a permitted one fits, so a cue of three or more lines, and each
+piece of a cue split past `--max-lines`, keeps the punctuation on the line it
+ends; **R4**
 for en/es/pt/fr/de/it, an article or preposition is kept with the phrase it
 governs: the break before it is preferred and the break after it penalised (a
 frozen table, matched case-folded; `--lang`, else the script detector, picks the
@@ -1863,9 +1874,10 @@ toggleable streams and copies the video and audio bit for bit. The suffix splits
 on the last colon, and only when the tail is a BCP-47-shaped code *and* the whole
 token is not itself a file on disk, so `C:\subs\en.srt` and a file named
 `a:b.srt` are never mangled; a single `--srt` with no suffix still takes
-`--language`. `--offset` shifts every added track (each later one as a
-`<output>_trackN.srt` copy); `--max-lines` and `--min-duration` lay out the first
-`--srt` only, and a note says so when they changed it. `--track-title` names a track (repeated in `--srt` order;
+`--language` (in a mux only: a burn reads `--language` as the script and wrap
+hint, not as a track tag). `--offset` shifts every added track (each later one as a
+`<output>_trackN.srt` copy); `--min-duration` lengthens the first `--srt`'s cues
+only, and a note says so when it changed them. `--track-title` names a track (repeated in `--srt` order;
 otherwise a frozen display-name table, and a code the table does not know gets
 the code itself — never a guessed or translated name), `--default-track LANG`
 marks one for auto-selection. Every other new track is explicitly marked *not*
@@ -1888,7 +1900,9 @@ language.
 
 Fonts by script (1.12): with no `--font` and no font named in your brand file, the
 script of the cue text (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari,
-Thai, Cyrillic, Greek) picks a font file that covers it, logged as `font: <file>
+Bengali, Gurmukhi, Gujarati, Tamil, Telugu, Kannada, Malayalam, Sinhala, Thai,
+Lao, Khmer, Myanmar, Cyrillic, Greek) picks a font file
+that covers it, logged as `font: <file>
 (covers ko)`. Han-only text is read as Chinese unless `--lang ja|ko` (or
 brand.json `"lang"`) says otherwise; `--language` is the same flag, and still
 tags the subtitle stream under `--mode mux` and sets `--transcribe`'s language.
@@ -1902,7 +1916,14 @@ does not cover the script gets one line and a font resolved by script anyway. `d
 
 `--karaoke` uses real per-word timings when the transcript has them (a whisper
 `<stem>.json` or `<stem>.words.json` next to the SRT, `{"segments": [{"words":
-[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides.
+[{"word", "start", "end"}]}]}`); otherwise `--karaoke-timing` decides. The
+highlight waits for the first word (the silence before it is an empty `\k` in
+`sweep`, an event with no active word in `word`), and `--offset` moves the word
+timings with the cues. With `--karaoke-style word` each word is its own event, and
+`--animate` is spread over them as the cue's one envelope: it fades in at the
+first event and out at the last, and a slide or a pop carries on across them.
+`--animate slide` ends on the line's own anchor (`--position`, a cue's `{\anN}`,
+the side margins).
 
 `--mode burn` (default) renders subtitles into the picture and always
 re-encodes both streams. `--mode mux` copies video and audio untouched and

package/scripts/_ass_overlay.py

@@ -29,7 +29,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 EMOJI_SENTINEL = "\ue000"
 
 
-def emoji_placeholder(box_px: float) -> str:
+def emoji_placeholder(box_px: float, back_alpha: int = 0) -> str:
     r"""The ASS override that reserves exactly `box_px` of advance and draws nothing.
 
     Measured, not assumed (1.15 spec, open question 2). U+2588 FULL BLOCK is NOT 1.0 em: its
@@ -40,9 +40,12 @@ def emoji_placeholder(box_px: float) -> str:
     whitespace carried by `\fsp` (letter spacing, in script pixels) on a zero-width space: the
     next glyph starts exactly `box_px` later, with no font dependence at all (verified by render,
     including inside a karaoke run, where the placeholder is its own zero-duration \kf segment).
-    `\r` restores the style for the rest of the line.
+    The text after it gets back exactly what this override changed -- the four alphas (the box
+    colour's is `back_alpha`, the Style's own) and a letter spacing of 0, which every Style here
+    has. A `\r` did the same and also reset everything before it on the line: the pop's
+    \fscx/\t, a per-cue \fs, a cue's <i>/<b> and colour (A69, #457).
     """
-    return "{\\alpha&HFF&\\fsp%.1f}\u200b{\\r}" % box_px
+    return "{\\alpha&HFF&\\fsp%.1f}\u200b{\\alpha&H00&\\4a&H%02X&\\fsp0}" % (box_px, int(back_alpha) & 0xFF)
 
 
 def ass_time(sec: float) -> str:
@@ -381,7 +384,7 @@ def text_overlay_ass(elements: Sequence[Dict[str, Any]], *, play_w: int, play_h:
         events.append(
             f"Dialogue: 0,{ass_time(el['start'])},{ass_time(el['end'])},{name},,0,0,0,,"
             "{" + "".join(tags) + "}" + ass_text(el["text"]).replace(
-                EMOJI_SENTINEL, emoji_placeholder(el.get("box_px") or el["size"])))
+                EMOJI_SENTINEL, emoji_placeholder(el.get("box_px") or el["size"], int(el.get("box_alpha", 0)))))
     body = "\n".join(header + ["", "[Events]",
                                "Format: Layer, Start, End, Style, Name, MarginL, MarginR, "
                                "MarginV, Effect, Text"] + events) + "\n"

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) "
@@ -360,7 +383,9 @@ def emoji_support(assets: "Optional[str]" = None, probe: bool = True, fonts_dir:
         mode = "png"
     elif family and libass_glyph is False:
         mode = "none"
-    elif family:
+    elif family or libass_glyph:
+        # a face libass draws the emoji from, colour family listed or not (A64, #457: a glyph from
+        # a monochrome face was answered `none`, against this docstring and libass_glyph: true)
         mode = "mono"
     elif not fc_answered:
         # No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
@@ -381,6 +406,8 @@ def emoji_support(assets: "Optional[str]" = None, probe: bool = True, fonts_dir:
         detail = f"{family} installed; the colour render probe was not run"
     elif assets_dir:
         detail = "no colour emoji family installed; using the PNG assets directory"
+    elif libass_glyph:
+        detail = "no colour emoji family installed; libass draws the emoji monochrome from an installed face"
     else:
         detail = "no colour emoji family installed and no --emoji-assets directory"
     result = {"mode": mode, "color_font": family, "color_font_file": file,

package/scripts/_common/fonts.py

@@ -109,21 +109,32 @@ def resolve_font(font_name: str) -> "Dict[str, object]":
 
 
 def font_choice(asked: "Optional[str]", *, font_file: "Optional[str]" = None, script_file: "Optional[str]" = None,
-                script_family: "Optional[str]" = None, renderer: str = "drawtext") -> "Dict[str, object]":
+                script_family: "Optional[str]" = None, renderer: str = "drawtext",
+                bold: bool = False) -> "Dict[str, object]":
     """The font a text-drawing tool draws with, as its result's `font_used`: {asked, file, family,
     how, substituted}. `how`: font_file (the caller's own file), script (a font picked to cover the
     text's script, 1.12), resolved (the asked family resolved to a file: fc-match, or the Windows
     Fonts folder), by_name (no file resolved; ffmpeg/libass look the family up themselves, so the
     file is not known here). For libass (`renderer="libass"`) a resolved file is the one fontconfig
     picks for the family, which is what libass loads through fontconfig; on Windows libass is
-    given the family by name, so nothing is resolved for it."""
+    given the family by name, so nothing is resolved for it.
+
+    `bold` (libass drawing a Bold style): libass asks fontconfig for the family at bold weight, so
+    the file reported is the one `fc-match FAMILY:bold` names -- the family's bold face where it
+    has one, its regular face (emboldened by libass) where it has none. The regular face was
+    reported whatever was drawn (A70, #457). Not on Windows, where nothing is resolved for libass."""
+    weight = ":bold" if bold and renderer == "libass" and platform.system() != "Windows" else ""
     if font_file:
         return {"asked": font_file, "file": font_file, "family": None, "how": "font_file", "substituted": False}
     if script_file:
+        if weight and script_family:
+            face = resolve_font(script_family + weight)
+            if face["file"] and not face["substituted"]:
+                script_file = face["file"]
         return {"asked": asked, "file": script_file, "family": script_family, "how": "script", "substituted": False}
     if renderer == "libass" and platform.system() == "Windows":
         return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
-    found = resolve_font(asked or "")
+    found = resolve_font((asked or "") + weight)
     if not found["file"]:
         return {"asked": asked, "file": None, "family": asked, "how": "by_name", "substituted": False}
     return {"asked": asked, "file": found["file"], "family": found["family"], "how": "resolved",
@@ -147,13 +158,18 @@ def record_font_choice(choice: "Dict[str, object]") -> "Dict[str, object]":
 # request and ffmpeg exits 0 either way. The tools now detect the script of the text they are about
 # to draw and resolve a font file that actually covers it; nothing found is a failed job, not a
 # warning (a video full of boxes is not a delivery).
-SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "ta", "th", "lo", "ru", "el", "latin")
+# A65 (#457): gu, pa, te, kn, ml, si, km and my were in SHAPING_SCRIPTS but had no range
+# below, so their text was detected as Latin, drawn in the Latin font and reported verified.
+SCRIPTS = ("ja", "zh", "ko", "ar", "he", "hi", "bn", "pa", "gu", "ta", "te", "kn", "ml", "si", "th", "lo",
+           "km", "my", "ru", "el", "latin")
 
 
 LANGUAGE_NAMES = {
     "ja": "Japanese", "zh": "Chinese", "ko": "Korean", "ar": "Arabic", "he": "Hebrew",
     "hi": "Devanagari (Hindi/Marathi/Nepali)", "th": "Thai", "ru": "Cyrillic (Russian and others)",
     "el": "Greek", "latin": "Latin", "bn": "Bengali", "ta": "Tamil", "lo": "Lao",
+    "pa": "Gurmukhi (Punjabi)", "gu": "Gujarati", "te": "Telugu", "kn": "Kannada", "ml": "Malayalam",
+    "si": "Sinhala", "km": "Khmer", "my": "Myanmar (Burmese)",
     "zh-hant": "Traditional Chinese",
 }
 
@@ -161,7 +177,8 @@ LANGUAGE_NAMES = {
 # fontconfig's own :lang= codes for each script we detect (zh uses zh-cn, the Simplified subset
 # every CJK font that claims zh carries; the rest are the plain two-letter codes).
 FC_LANG = {"ja": "ja", "zh": "zh-cn", "ko": "ko", "ar": "ar", "he": "he", "hi": "hi", "th": "th", "ru": "ru", "el": "el",
-           "bn": "bn", "ta": "ta", "lo": "lo", "zh-hant": "zh-tw"}
+           "bn": "bn", "ta": "ta", "lo": "lo", "zh-hant": "zh-tw",
+           "pa": "pa", "gu": "gu", "te": "te", "kn": "kn", "ml": "ml", "si": "si", "km": "km", "my": "my"}
 
 
 # Families tried in order, best first. The names are matched case-insensitively against the start
@@ -180,6 +197,14 @@ PREFERRED_FAMILIES = {
     "bn": ["Noto Sans Bengali", "Noto Serif Bengali", "Lohit Bengali", "Mukti Narrow", "Vrinda", "Nirmala UI", "FreeSerif"],
     "ta": ["Noto Sans Tamil", "Noto Serif Tamil", "Lohit Tamil", "Latha", "Nirmala UI", "FreeSerif"],
     "lo": ["Noto Sans Lao", "Noto Serif Lao", "Phetsarath OT", "Souliyo Unicode", "Saysettha OT", "DokChampa", "Leelawadee UI"],
+    "pa": ["Noto Sans Gurmukhi", "Noto Serif Gurmukhi", "Lohit Gurmukhi", "Raavi", "Nirmala UI", "FreeSerif"],
+    "gu": ["Noto Sans Gujarati", "Noto Serif Gujarati", "Lohit Gujarati", "Shruti", "Nirmala UI", "FreeSerif"],
+    "te": ["Noto Sans Telugu", "Noto Serif Telugu", "Lohit Telugu", "Gautami", "Nirmala UI"],
+    "kn": ["Noto Sans Kannada", "Noto Serif Kannada", "Lohit Kannada", "Tunga", "Nirmala UI"],
+    "ml": ["Noto Sans Malayalam", "Noto Serif Malayalam", "Lohit Malayalam", "Kartika", "Nirmala UI"],
+    "si": ["Noto Sans Sinhala", "Noto Serif Sinhala", "LKLUG", "Iskoola Pota", "Nirmala UI"],
+    "km": ["Noto Sans Khmer", "Noto Serif Khmer", "Khmer OS", "Leelawadee UI", "Khmer UI"],
+    "my": ["Noto Sans Myanmar", "Noto Serif Myanmar", "Padauk", "Myanmar Text"],
     "ru": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
     "el": ["Noto Sans", "DejaVu Sans", "Liberation Sans", "FreeSans", "FreeSerif"],
 }
@@ -201,6 +226,10 @@ WINDOWS_FONTS = {
     "bn": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
     "ta": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("latha.ttf", "Latha")],
     "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
+    # Nirmala UI carries every Indic script Windows supports, Sinhala included
+    **{k: [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI")] for k in ("pa", "gu", "te", "kn", "ml", "si")},
+    "km": [("leelawui.ttf", "Leelawadee UI"), ("KhmerUI.ttf", "Khmer UI")],
+    "my": [("mmrtext.ttf", "Myanmar Text")],
     "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
     "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
 }
@@ -233,9 +262,17 @@ _SCRIPT_RANGES = (
     ("he", ((0x0590, 0x05FF), (0xFB1D, 0xFB4F))),
     ("hi", ((0x0900, 0x097F), (0xA8E0, 0xA8FF))),
     ("bn", ((0x0980, 0x09FF),)),
+    ("pa", ((0x0A00, 0x0A7F),)),
+    ("gu", ((0x0A80, 0x0AFF),)),
     ("ta", ((0x0B80, 0x0BFF),)),
+    ("te", ((0x0C00, 0x0C7F),)),
+    ("kn", ((0x0C80, 0x0CFF),)),
+    ("ml", ((0x0D00, 0x0D7F),)),
+    ("si", ((0x0D80, 0x0DFF), (0x111E0, 0x111FF))),
     ("th", ((0x0E00, 0x0E7F),)),
     ("lo", ((0x0E80, 0x0EFF),)),
+    ("km", ((0x1780, 0x17FF), (0x19E0, 0x19FF))),
+    ("my", ((0x1000, 0x109F), (0xA9E0, 0xA9FF), (0xAA60, 0xAA7F))),
     ("ru", ((0x0400, 0x04FF), (0x0500, 0x052F), (0x2DE0, 0x2DFF))),
     ("el", ((0x0370, 0x03FF), (0x1F00, 0x1FFF))),
 )

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):