ffmpeg-skill 2.8.0 → 2.8.2

package/README.md

@@ -401,7 +401,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 **What is tested where.** The contract and the test suite (`tests/test_contract.py`,
 `tests/test_all.py`, which aggregates one module per tool group — `test_analysis.py`,
 `test_editing.py`, `test_audio.py`, `test_picture.py`, `test_delivery.py`,
-`test_orchestration.py` — over the shared footage in `tests/_fixtures.py`) run on Linux, macOS
+`test_orchestration.py`, `test_accel.py`, `test_asr.py`, `test_cut_copy.py` — over the shared footage in `tests/_fixtures.py`) run on Linux, macOS
 and Windows on every pull request, minus the handful of POSIX-shim tests listed under
 [Development](#development). The real-device media corpus
 (`tests/corpus.py`) has been run on Linux and macOS; the full corpus has **not** been run on
@@ -480,10 +480,15 @@ FFmpeg itself:
 
 | OS | Command |
 |----|---------|
-| macOS | `brew install ffmpeg-full` (the plain `ffmpeg` formula lacks the subtitles, drawtext and zscale filters) |
+| macOS | `brew install ffmpeg-full`, then put it on `PATH` (below). The plain `ffmpeg` formula lacks the subtitles, drawtext and zscale filters |
 | Ubuntu / Debian | `sudo apt install ffmpeg` |
 | Windows | `winget install Gyan.FFmpeg` |
 
+**On macOS, `ffmpeg-full` is keg-only:** Homebrew installs it without linking it, so after `brew install ffmpeg-full` the `ffmpeg` on `PATH` is still the lean `ffmpeg` formula (often present as a dependency of another formula), or no `ffmpeg` at all, so `doctor` keeps reporting `ffmpeg`, or the `subtitles` and `drawtext` filters, as missing. Make it the one the tools find, in one of two ways:
+
+- **Put it first on `PATH`.** Add `export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"` to your shell profile. `brew --prefix ffmpeg-full` is the stable `opt/` path, so this survives upgrades, but it only reaches processes started from a shell that read the profile.
+- **Link it over the lean formula:** `brew unlink ffmpeg 2>/dev/null; brew link --overwrite --force ffmpeg-full`. Every process finds this one, but `brew doctor` warns about a linked keg-only formula, and an upgrade of the lean `ffmpeg` has been seen to link the lean build back on top without a message. After upgrading, check that `command -v ffmpeg` still resolves into `ffmpeg-full`, and re-run the link if it doesn't.
+
 ## Requirements
 
 - FFmpeg 5.0+. Always required: `libx264`, `aac`, and the `drawtext`, `subtitles` (libass), `loudnorm`, `xfade`, `acrossfade`, `scdet`, `silencedetect` and `tile` filters. Needed only by the flags that use them: `libx265`, `prores_ks`, `libzimg` / `zscale`, `libmp3lame`, `libopus`, `libvorbis`, the `ass` filter. `doctor` tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack `libass` / `libfreetype` / `libzimg`, which `doctor` reports as missing.

package/bin/install.js

@@ -94,7 +94,9 @@ function checkFfmpeg() {
   const r = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8' });
   if (r.error || r.status !== 0) {
     console.warn('\n  warning: ffmpeg was not found on PATH. The skill needs FFmpeg to run:');
-    console.warn('    macOS:   brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)');
+    console.warn('    macOS:   brew install ffmpeg-full; export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"');
+    console.warn('             # keg-only, so installing it does not put it on PATH: keep the export in your shell profile;');
+    console.warn('             # the plain ffmpeg formula lacks subtitles/drawtext/zscale');
     console.warn('    Ubuntu:  sudo apt install ffmpeg');
     console.warn('    Windows: winget install Gyan.FFmpeg\n');
     return false;

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 (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.8.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.8.2`) | 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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.8.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.8.2", "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.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -247,7 +247,7 @@ runs the tool with the planned `argv`, then the verify steps (a `check` step may
 ### Repeatability
 
 No tool keeps state or uses randomness. `deterministic_inputs` is `false` only for
-`verify`, whose output includes timings. `idempotency_hint` says what "same inputs"
+`verify` and `cropdetect`, whose output includes timings or machine state. `idempotency_hint` says what "same inputs"
 gives you:
 
 | Hint | Tools |
@@ -255,7 +255,7 @@ gives you:
 | `bit_exact` | probe, check, scenes, look, metadata, background |
 | `content_equivalent` (same media, bytes may differ between encoder builds) | every encoding tool, cut, sync, report |
 | `cached` | batch (content-hash cache, re-runs skip unchanged inputs); render **when `--cache DIR` is given** — the hint stays `content_equivalent` because that is what render is without the flag, and the cache is opt-in |
-| `environment_dependent` | verify |
+| `environment_dependent` | verify, cropdetect |
 
 The hints describe the CPU encoders. Under `--hw`, or `FFMPEG_SKILL_HW=1` on the machine, a tool
 that encodes video runs VideoToolbox, whose bytes are not promised identical from run to run:
@@ -568,12 +568,13 @@ Per-tool keys added after 2.2.2, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
+| `boomerang`, `notes` | `loop.py` | `boomerang` is `true` for `--boomerang` (frames 0..N-1 then N-2..1, repeated, so neither turnaround frame is shown twice); `notes` says the audio was dropped when the source had any (a boomerang is silent) |
 | `sdr_path`, `notes` | `color.py --to-sdr` | `sdr_path` is `"tonemap"` for PQ / HLG / Dolby Vision input (and `--force` on an untagged file) or `"gamut"` for BT.2020 primaries on an SDR transfer, which is converted to BT.709 without a tone map (`--tonemap`/`--peak`/`--desat` do not apply); `notes` says which path was taken and why |
 | `silent` | `join.py` (every run) | `[{index, path, peak_db, at, end}]`: inputs whose whole-file audio peak (volumedetect) is at or below `--silence-threshold` (default -50 dBFS) and that `--on-silent warn` (default) joined anyway, with a `notes` line; `at`/`end` are where the input sits in the output, in seconds (a transition overlaps its neighbours). An input named by `--allow-silent N[,N]` (1-based) is a planned pause: always joined, listed with `intended: true`, no warning or note, whatever `--on-silent` says. `[]` otherwise. `--on-silent fail` names them in the `kind: input` refusal's `problems` (reason `silent (peak -91.0 dBFS)`), `skip` lists them under `skipped`. An input with no audio stream is never silent; `verified` is unaffected |
 | `short_segments`, `duplicates` | `join.py` (every run) | warnings, never refusals, and the join command is unchanged: `short_segments: [{index, path, duration}]` names each measured input shorter than 2 frames at the join's fps (an audio-only join: shorter than 0.05 s); `duplicates: [{path, indices}]` names a path (compared resolved) listed more than once — repeating a clip can be intended. `[]` when none; each non-empty one adds a `notes` line |
 | `silent` | `waveform.py` (every run) | `true` when the input audio's whole-file peak is at or below `--silence-threshold` (default -50 dBFS), which draws a flat line; `--on-silent warn` (default) renders it anyway with a `notes` line, `fail` refuses (`kind: input`) before ffmpeg runs. `false` when audible, `null` under `--dry-run` (nothing measured). `verified` is unaffected |
 | `encoder`, `hw`, `notes` | every re-encoding tool, `export.py`, `render.py`, `batch.py` (and its rows), `waveform.py` | `encoder`: the video encoder the last command ran (after any GPU→CPU fallback; under `--dry-run`, the planned one), `copy` for a stream copy; absent when no command encoded video. A tool that runs other tools reports its stages': `render.py` its stages and an executed plan's tool, `waveform.py` the title/caption stage that writes its file (its `commands` include that stage's). `hw` is present when VideoToolbox was asked for (`--hw`, `FFMPEG_SKILL_HW=1`, or a stage or `batch.py` item that reported it) and on `export.py` when `FFMPEG_SKILL_HW=1` is set but its delivery preset does not take it: `{requested, source: flag\|env, used, fallback, notes}`. `requested` says whether this run's encodes were asked onto VideoToolbox (`false` for that export), `used` whether the encoder that ran last is VideoToolbox (`null` under `--dry-run`, which ran nothing, and when the tool encoded nothing itself: `batch.py`, whose top-level `hw` gathers its items' `requested`/`source`/`fallback`/`notes` while each `results` row carries the item's own `encoder`, and `hw`/`notes` when VideoToolbox was asked for), `fallback` whether a job VideoToolbox refused was re-encoded on the CPU, and `notes` why. Only a VideoToolbox failure (the encoder could not open, or its compression session failed) is retried on the CPU; any other failure is reported as it happened, once. Every VideoToolbox encode adds a top-level `notes` line: its quality is not CRF-equivalent (`--quality` / a preset's CRF maps to `-q:v` approximately), and `verified` stays what it is for every tool, the measured properties of the output. A `kind: ffmpeg` failure under `--hw` / `FFMPEG_SKILL_HW` carries `encoder` and `hw` for the command that ran last (a stage's, when `render.py`/`waveform.py` re-raise it); when the command itself failed inside the run (not a tool's own check afterwards, such as `cut.py`'s), its message also names that encoder |
-| `transcription` | `caption.py --transcribe` (every `--mode`); inside `filler` for `silence.py --filler --transcribe` | `{routing, detected_language?, engine, model, language}`: the engine and model that made the transcript; `language` is the language the engine was told -- the one named (`--language`, `--filler-lang`), else the one auto's detector named -- and `null` when the engine identified it itself; `detected_language` is present when auto's whisper.cpp detector named one; `routing` says why `--engine auto` chose the engine (`"requested"` for a named engine), ending `, no Parakeet engine transcribed it` when auto chose Parakeet and a Whisper engine made the transcript after every Parakeet engine failed |
+| `transcription` | `caption.py --transcribe` (every `--mode`); inside `filler` for `silence.py --filler --transcribe` | `{routing, detected_language?, engine, model, language}`: the engine and model that made the transcript; `language` is the language the engine was told -- the one named (`--language`, `--filler-lang`), else the one auto's detector named -- and, when nothing was named, the language the engine decoded where it reports one (whisper.cpp's word-timing JSON, faster-whisper, openai-whisper's word-timing JSON), else `null`; `detected_language` is present when auto's whisper.cpp detector named one; `routing` says why `--engine auto` chose the engine (`"requested"` for a named engine), ending `, no Parakeet engine transcribed it` when auto chose Parakeet and a Whisper engine made the transcript after every Parakeet engine failed |
 | `notes` | `silence.py --filler --transcribe` (new for `silence.py`; `caption.py` already had it) | present when `--engine auto` ran the English-only Parakeet model on English *assumed* (no language given or detectable, and no Whisper engine installed or none that succeeded): the transcript is wrong if the speech is not English. `caption.py --transcribe` puts the same line in its `notes` |
 | `reencode_reason`, `segment_precision`, `least_exact_precision`, `start_snapped` | `cut.py` (every run) | `reencode_reason`: why anything was re-encoded, distinct values in first-seen order, `[]` for a clean copy: `requested` (`--accurate`), `codec` (`--codec`), `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback` (a `--segments` join that could not stay a stream copy, which now also sets `reencoded: true` and `mode: hybrid`; it reported `copy` before). `segment_precision`: each `--segments` segment's precision (`null` for one segment); `least_exact_precision`: the least exact of them, on every run. `precision` and `keyframe_snapped` keep their meaning (`keyframe_snapped` is `precision == "packet"`, a stream copy end to end); `least_exact_precision` differs from `precision` only for an audio-only join of copied and re-encoded parts. `start_snapped`: measured, `true` when a copied segment's picture starts more than one frame from its requested start (or its start could not be measured: an unknown start is never claimed exact), `false` when every start is where asked or everything re-encoded, `null` under `--dry-run`. `requested_segments`/`requested_duration` keep their meaning, the request clamped to the media's duration: a segment ended with the video (less than a frame of sound trimmed) shows in `duration_delta_seconds` and a `notes` line |
 | `edit_list`, `stored_preroll_seconds`, `av_start_skew_seconds`, `notes` | `cut.py` (every run) | `edit_list`: `true` only for a single-segment `.mp4`/`.m4v`/`.mov` stream copy run with `--edit-list`, which keeps the MP4 edit list the copy writes instead of `-avoid_negative_ts make_zero` (the default, unchanged): the keyframe's pre-roll is stored but hidden, so the picture starts at `--start`. `stored_preroll_seconds`: with `edit_list`, the seconds decoded from the keyframe the copy's seek lands on (measured with the seek ffmpeg makes) up to the first presented frame; `null` otherwise. Under `--edit-list` a copy is judged by its video's length (a `notes` line says so when the container is longer), and one that starts where asked but ends past `--tolerance` re-encodes (`tolerance`) without a `lossless_alternative`. `av_start_skew_seconds`: the output's audio start minus its video start (`null` when either is missing or under `--dry-run`); on a stream copy, when it is more than max(2 frames, 0.1 s) away from the source's own audio/video offset where the copy's picture starts (the keyframe it began from; `--start` under `--edit-list`), a `notes` line names `--accurate`, and `--edit-list` for a single `.mp4`/`.mov` copy whose start snapped. A re-encode carries no such note. The skew is reported, never repaired. `notes`: what the run did that a caller should know, in plain sentences (`[]` when nothing) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "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": [
     "ffmpeg",

package/references/scripts.md

@@ -617,7 +617,7 @@ Three refusals, all `kind: input`, all before any encode:
 
 Results: `filler.removed_count`, `filler.removed_seconds`, `filler.removed`
 (one entry per span), `filler.lang`, `filler.list`, `filler.word_timings` and
-`filler.warnings`. With `--transcribe`, `filler.source` is `whisper:ENGINE` or
+`filler.warnings`; `--filler-lang auto` refuses (`kind: input`) a transcript in a language with no built-in list, so pass `--filler-words FILE` for it. With `--transcribe`, `filler.source` is `whisper:ENGINE` or
 `parakeet:ENGINE` and `filler.transcription` says which engine, model, language
 and routing made the words; a top-level `notes` line says when `--engine auto`
 ran the English-only Parakeet model on English assumed (no `--filler-lang`, and

package/scripts/_common/asr.py

@@ -301,6 +301,7 @@ def _skipped_parakeet(route: "Route", language: Optional[str], language_flag: st
 def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int,
                    ffmpeg: str, shutil, subprocess, wanted: str = "auto") -> Transcription:
     from _common import run_analysis, STATE
+    language = engine_language(language)
     wav = os.path.join(tmpdir, "audio.wav")
     # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
     # is not a run() call (no --dry-run gate, not recorded), but it keeps the time limit and
@@ -360,12 +361,14 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
         import threading
         result: list = []
         crashed: list = []
+        heard: list = []  # the language faster-whisper decoded, when it names one
 
         def work() -> None:
             try:
                 m = WhisperModel(model, device="cpu", compute_type="int8")
-                segments, _ = m.transcribe(wav, language=lang, word_timestamps=False)
+                segments, decoded = m.transcribe(wav, language=lang, word_timestamps=False)
                 result.extend((seg.start, seg.end, seg.text.strip()) for seg in segments if seg.text.strip())
+                heard.append(getattr(decoded, "language", None))
             except Exception as exc:  # noqa: BLE001 -- a model that would not load or run: a failed engine
                 crashed.append(exc)
 
@@ -388,7 +391,8 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
             info("transcribed with faster-whisper")
             write_srt(cues, out_srt)
             return Transcription(cues=cues, engine="faster-whisper",
-                                 facts=dict(facts, engine="faster-whisper", model=model, language=lang))
+                                 facts=dict(facts, engine="faster-whisper", model=model,
+                                            language=lang or _heard_language(heard)))
     except ImportError:
         pass
     # 3. openai-whisper CLI
@@ -508,6 +512,23 @@ def _words_from_whisper_cpp_json(path: str) -> "List[Dict[str, Any]]":
     return [w for w in out if w["word"].strip()]
 
 
+def _whisper_json_language(path: str) -> Optional[str]:
+    """The language a Whisper engine's JSON says it decoded: whisper.cpp's `result.language`, or
+    openai-whisper's top-level `language`. None when the file has neither."""
+    try:
+        doc = json.loads(Path(path).read_text(encoding="utf-8")) or {}
+        lang = str(((doc.get("result") or {}).get("language")) or doc.get("language") or "").strip().lower()
+    except (OSError, ValueError, AttributeError):
+        return None
+    return lang or None
+
+
+def _heard_language(heard: list) -> Optional[str]:
+    """The language an in-process engine decoded (faster-whisper's info.language), lower-cased, or None."""
+    lang = next((str(h).strip().lower() for h in heard if h), "")
+    return lang or None
+
+
 def _words_from_openai_whisper_json(path: str) -> "List[Dict[str, Any]]":
     """openai-whisper --word_timestamps True --output_format json: segments[].words[]."""
     try:
@@ -644,6 +665,22 @@ def _is_english(language: Optional[str]) -> bool:
     return (language or "").lower().split("-")[0].split("_")[0] in ("en", "eng", "english")
 
 
+def engine_language(language: Optional[str]) -> Optional[str]:
+    """`--language` as the engines take it. "auto" (caption.py's documented default, spelled out)
+    is no language: None, the undetected route. Every spelling of English (en-US, eng, English)
+    is "en", which Parakeet accepts as English and Whisper accepts as a language code; any other
+    value is its two-letter primary language (ja-JP -> ja)."""
+    named = (language or "").strip()
+    if not named or named.lower() == "auto":
+        return None
+    if _is_english(named):
+        return "en"
+    # Whisper takes the two-letter code: a regional or script subtag (ja-JP, pt-BR, zh-Hant) names the
+    # same language to it, and an ISO 639-2 code (jpn) is passed as given
+    primary = named.replace("_", "-").split("-")[0].lower()
+    return primary if len(primary) == 2 else named
+
+
 def _whisper_cpp_cli(shutil) -> Optional[str]:
     cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp")
     if not cli:
@@ -675,7 +712,7 @@ def detect_language(wav: str, shutil, subprocess) -> Optional[str]:
     if not cli:
         return None
     model = next((p for p in (_whisper_cpp_model(m) for m in ("tiny", "base", "small", "tiny.en"))
-                  if os.path.exists(p) and not p.endswith(".en.bin")), None)
+                  if os.path.exists(p) and not _english_only_whisper_model(p)), None)
     if not model:
         return None
     proc = _asr_run([cli, "-m", model, "-f", wav, "-dl", "-l", "auto"], subprocess, "whisper.cpp language detection")
@@ -756,9 +793,10 @@ def _names_parakeet_model(name: str) -> bool:
 
 
 def _english_only_whisper_model(name: str) -> bool:
-    """An English-only Whisper model: tiny.en, base.en, ... or a ggml-*.en.bin file."""
+    """An English-only Whisper model: tiny.en, base.en, ... or a ggml-*.en.bin file, in any
+    quantisation (ggml-base.en-q5_1.bin, tiny.en-q8_0) or variant (ggml-small.en-tdrz.bin)."""
     base = os.path.basename(name).lower()
-    return (base[:-4] if base.endswith(".bin") else base).endswith(".en")
+    return re.search(r"\.en(-[a-z0-9_]+)*$", base[:-4] if base.endswith(".bin") else base) is not None
 
 
 def _whisper_ready(shutil, model: Optional[str]) -> bool:
@@ -913,6 +951,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     from _common import require_tool, run_analysis, STATE
     ffmpeg = require_tool("ffmpeg")
     wanted = requested_engine(engine)
+    language = engine_language(language)
     parakeet_model = None if model == "base" else model
     tmpdir = _tempfile.mkdtemp(prefix="ffskill_asrw_")
     try:
@@ -962,7 +1001,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
                 words = _words_from_whisper_cpp_json(base + ".json")
                 info(f"word timings from whisper.cpp ({len(words)} words)")
                 return Transcription(words=words, engine="whisper.cpp",
-                                     facts=dict(facts, engine="whisper.cpp", model=model_path, language=lang))
+                                     facts=dict(facts, engine="whisper.cpp", model=model_path,
+                                                language=lang or _whisper_json_language(base + ".json")))
             line = _failure_line(proc)
             info("whisper.cpp found but produced no word-timing JSON: " + line)
             tried.append(_failed("whisper.cpp", "found but produced no word-timing JSON: " + line))
@@ -976,11 +1016,13 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             import threading
             collected: list = []
             crashed: list = []
+            heard: list = []
 
             def work() -> None:
                 try:
                     m = WhisperModel(model, device="cpu", compute_type="int8")
-                    segments, _ = m.transcribe(wav, language=lang, word_timestamps=True)
+                    segments, decoded = m.transcribe(wav, language=lang, word_timestamps=True)
+                    heard.append(getattr(decoded, "language", None))
                     for seg in segments:
                         for w in (getattr(seg, "words", None) or []):
                             collected.append({"word": str(w.word).strip(),
@@ -1002,7 +1044,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             else:
                 info(f"word timings from faster-whisper ({len(collected)} words)")
                 return Transcription(words=[w for w in collected if w["word"]], engine="faster-whisper",
-                                     facts=dict(facts, engine="faster-whisper", model=model, language=lang))
+                                     facts=dict(facts, engine="faster-whisper", model=model,
+                                                language=lang or _heard_language(heard)))
         except ImportError:
             pass
 
@@ -1018,7 +1061,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
                 words = _words_from_openai_whisper_json(doc)
                 info(f"word timings from openai-whisper ({len(words)} words)")
                 return Transcription(words=words, engine="openai-whisper",
-                                     facts=dict(facts, engine="openai-whisper", model=model, language=lang))
+                                     facts=dict(facts, engine="openai-whisper", model=model,
+                                                language=lang or _whisper_json_language(doc)))
             line = _failure_line(proc)
             info("openai-whisper found but produced no word-timing JSON: " + line)
             tried.append(_failed("openai-whisper", "found but produced no word-timing JSON: " + line))

package/scripts/_common/drawtext.py

@@ -115,7 +115,7 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
     done"` losing both characters. A newline is kept (`\r\n` and `\r` become `\n`): drawtext
     draws it as a line break, and graphics.py's wrap puts them there on purpose (stripping them
-    ran a wrapped title off both edges of the frame). A tab, vertical tab or form
+    ran a wrapped title off both edges of the frame); trailing newlines are dropped. A tab, vertical tab or form
     feed becomes a space, as the wrap measures it; other control characters are stripped (that
     dates from the inline-escape route, where they broke the graph parser).
 
@@ -127,6 +127,9 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     """
     cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
     cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
+    # drawtext ignores one trailing newline and draws a second as a blank line, which would
+    # centre the block half a line too high; a label that is only newlines stays as it is
+    cleaned = cleaned.rstrip("\n") or cleaned
     import hashlib
     name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
     if tmpdir is None:

package/scripts/_common/emit.py

@@ -73,8 +73,17 @@ def _set_current_ctx(ctx: "Context") -> None:
 
 ENV_HW_NOTE = ("VideoToolbox chosen by FFMPEG_SKILL_HW=1 (machine default; ~1.1-3.5x the bytes of x264/x265 "
                "at matched quality); rerun with --no-hw for a final deliverable")
-ENV_NOT_FOR_DELIVERY_NOTE = ("FFMPEG_SKILL_HW=1 is not applied to export.py's delivery presets (a delivered file is where "
-                             "VideoToolbox's larger files cost most); pass --hw to put this export on the GPU")
+ENV_NOT_FOR_DELIVERY_BASE = ("FFMPEG_SKILL_HW=1 is not applied to export.py's delivery presets (a delivered file is where "
+                             "VideoToolbox's larger files cost most)")
+ENV_NOT_FOR_DELIVERY_NOTE = ENV_NOT_FOR_DELIVERY_BASE + "; pass --hw to put this export on the GPU"
+
+
+def env_not_for_delivery_note() -> str:
+    """The note for an export the variable left on the CPU: the advice to pass --hw only on a
+    machine that can take it (the same advice on a Linux box would send the caller to a flag that
+    then reports the CPU encode)."""
+    from _common import decision  # the same name the --hw decisions (and their tests) stand the platform in on
+    return ENV_NOT_FOR_DELIVERY_NOTE if decision.hw_platform_reason() is None else ENV_NOT_FOR_DELIVERY_BASE
 
 
 def _video_encoders(commands: Sequence[str]) -> "Tuple[Optional[str], Optional[str]]":
@@ -120,7 +129,7 @@ def hw_report(ctx: "Context", enc: Optional[str]) -> Dict[str, Any]:
         # (once: a stage that ran on it already said so)
         notes.append(ENV_HW_NOTE)
     if ctx.hw_env_ignored and enc not in (None, "copy"):
-        notes.append(ENV_NOT_FOR_DELIVERY_NOTE)
+        notes.append(env_not_for_delivery_note())
     return {"requested": requested, "source": source, "used": used,
             "fallback": bool(ctx.hw_fallback) or any(st.get("fallback") for st in stages), "notes": notes}
 

package/scripts/_common/runner.py

@@ -18,7 +18,9 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 
 INSTALL_HINTS = {
-    "Darwin": "  brew install ffmpeg-full   (the plain ffmpeg formula lacks subtitles/drawtext/zscale)",
+    "Darwin": ("  brew install ffmpeg-full; export PATH=\"$(brew --prefix ffmpeg-full)/bin:$PATH\""
+               "   # keg-only, so installing it does not put it on PATH: keep the export in your shell profile;"
+               " the plain ffmpeg formula lacks subtitles/drawtext/zscale"),
     "Linux": (
         "  Debian/Ubuntu: sudo apt install ffmpeg\n"
         "  Fedora:        sudo dnf install ffmpeg\n"
@@ -885,9 +887,10 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
                 why = videotoolbox_failure(proc.stderr or "")
                 if why is not None:
                     reason = f"VideoToolbox refused the encode: {why}"
+                    # said before the retry, without a claim about its outcome: a retry that never
+                    # returns (a timeout exits from inside _execute) leaves this line, which is true
+                    _set_refusal_note(ctx, reason, "; retrying on the CPU encoder")
                     info(reason + "; retrying on the CPU encoder")
-                    ctx.hw_notes.append(reason + "; re-encoded on the CPU")
-                    ctx.hw_fallback = True
                     ctx.commands[-1] = _cmdline(cpu_cmd[:-1] + [cmd[-1]])
                     if not quiet:
                         # echoed like the first attempt, so a caller that reads the "$ " lines
@@ -895,6 +898,11 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
                         info("$ " + ctx.commands[-1], ctx=ctx)
                     proc, tried = even_retry(_execute(cpu_cmd), cpu_cmd)
                     retried = True
+                    # the outcome replaces the line above: a failure document must not claim a
+                    # re-encode that did not happen, and hw.fallback is the same claim as a flag
+                    ok = proc.returncode == 0
+                    _set_refusal_note(ctx, reason, "; re-encoded on the CPU" if ok else "; the CPU retry failed too")
+                    ctx.hw_fallback = ctx.hw_fallback or ok
         if proc.returncode != 0 and check:
             _fail(tried, proc.returncode, proc.stderr or "", ctx=ctx, retried=retried)
         if final and tmp:
@@ -910,6 +918,14 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
     return proc
 
 
+def _set_refusal_note(ctx: "Context", reason: str, outcome: str) -> None:
+    """One note per refusal: the latest outcome for `reason` replaces any earlier line for it, so a
+    job of many encodes names it once, and a process that ran an earlier job with the same refusal
+    does not keep that job's outcome beside this one."""
+    ctx.hw_notes[:] = [n for n in ctx.hw_notes if not n.startswith(reason)]
+    ctx.hw_notes.append(reason + outcome)
+
+
 def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
     """One attempt, never exiting on failure (run() decides after its retries)."""
     if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
@@ -1257,7 +1273,9 @@ def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
         # symlink guard is belt and braces there and unavailable on Windows
         flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
         fd = os.open(path, flags, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        # newline="\n": text mode would write each kept line break as CRLF on Windows, and
+        # drawtext from FFmpeg 6.1 draws that as a blank line plus a line break
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
             fh.write(body)
         written.append(path)
     return written

package/scripts/_contract.py

@@ -235,7 +235,7 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
-    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written. --filler --transcribe also runs the speech engine (its word timings are what the filler spans are planned on), which may download a model on first use",
     "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
     "check": "read-only tool; the loudness measurement (or, when it is skipped, the audio row's volumedetect) and the --content decode run under --dry-run too, so every row is present",
     "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
@@ -518,10 +518,15 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     props = dict(base)
     props.update(extra)
     notes = props.get("notes")
-    if hw and isinstance(notes, dict) and notes.get("description"):
-        # a tool-specific condition is not the only one: emit() adds the GPU line to any tool
-        props["notes"] = dict(notes, description=notes["description"] + "; also, on a VideoToolbox encode (--hw / "
-                              "$FFMPEG_SKILL_HW), a line that its quality is not CRF-equivalent (see hw)")
+    if hw:
+        # emit() adds the VideoToolbox quality line to `notes` on every tool that takes --hw, so every
+        # such tool publishes `notes`, and a tool-specific condition (loop's "--boomerang ... the audio
+        # was dropped", export's own lines) is not the only one it can carry
+        gpu = "a line that its quality is not CRF-equivalent (on a VideoToolbox encode: --hw / $FFMPEG_SKILL_HW; see hw)"
+        if isinstance(notes, dict) and notes.get("description"):
+            props["notes"] = dict(notes, description=notes["description"] + "; also " + gpu)
+        else:
+            props["notes"] = dict(notes or {"type": "array", "items": {"type": "string"}}, description=gpu[0].upper() + gpu[1:])
     required = ["status", "output", "dry_run", "commands"]
     return {"type": "object", "properties": props, "required": required, "additionalProperties": True}
 
@@ -840,8 +845,9 @@ def doctor() -> Dict[str, Any]:
 
     `gpu_encoders` is a separate, honest answer to a question none of the required/optional
     capabilities above ask: which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) this
-    ffmpeg BUILD carries, from `-encoders` alone. No tool here requires or uses one -- every tool
-    still assumes CPU x264/x265 -- so `gpu_encoders` never affects `ok` or any tool's `usable`. It
+    ffmpeg BUILD carries, from `-encoders` alone. No tool requires one -- every tool runs on CPU
+    x264/x265 unless `--hw` / FFMPEG_SKILL_HW=1 puts it on VideoToolbox (Apple Silicon only) -- so
+    `gpu_encoders` never affects `ok` or any tool's `usable`. It
     only proves the build shipped the capability, never that the GPU/driver on this machine will
     actually accept a job (that needs a real encode, which this introspection never runs).
 
@@ -1005,10 +1011,15 @@ def _capability_fix_hint(cap: str) -> str:
     if cap in ("ffmpeg", "ffprobe"):
         from _common import INSTALL_HINTS
         hint = INSTALL_HINTS.get(platform.system(), "see https://ffmpeg.org/download.html").strip().splitlines()[0].strip()
-        return f"install ffmpeg: {hint}"
+        # a hint's "# why" is a shell comment so the printed line pastes; joined into a fix string
+        # with "; " it would swallow what follows, so show it in parentheses here instead
+        cmd, _, why = hint.partition("#")
+        return f"install ffmpeg: {cmd.strip()} ({why.strip()})" if why else f"install ffmpeg: {hint}"
     system = platform.system()
     if system == "Darwin":
-        full_hint = "on macOS, brew install ffmpeg-full (the plain formula lacks subtitles/drawtext/zscale)"
+        full_hint = ("on macOS, brew install ffmpeg-full; export PATH=\"$(brew --prefix ffmpeg-full)/bin:$PATH\" "
+                     "(ffmpeg-full is keg-only, so installing it does not replace the ffmpeg already found: keep the "
+                     "export in your shell profile; the plain formula lacks subtitles/drawtext/zscale)")
     elif system == "Windows":
         full_hint = "on Windows, winget install Gyan.FFmpeg (the gyan.dev full build carries subtitles/drawtext/zscale; a plain choco ffmpeg package can lack them)"
     else:
@@ -1439,7 +1450,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             # first time it runs; faster-whisper is a library, so its fetch is made from the skill's own
             # process. A caller that sandboxes the network must know that before a first --transcribe.
             "model_downloads": {
-                "when": "first use of a speech engine (--transcribe) whose model is not cached yet; media is never uploaded",
+                "when": "first use of a speech engine (--transcribe; silence.py --filler --transcribe runs it under --dry-run too, caption.py --transcribe does not) whose model is not cached yet; media is never uploaded",
                 "in_process": {"faster-whisper": "Hugging Face (Systran/faster-whisper-<model>)"},
                 "child_process": {"parakeet-mlx": "Hugging Face (mlx-community/parakeet-*)",
                                   "openai-whisper": "OpenAI (its model checkpoint)"},
@@ -1513,7 +1524,7 @@ def main() -> int:
                 print(f"note: overall 'ok' means nothing REQUIRED BY EVERY TOOL is missing -- {len(not_usable)} tool(s) still can't run today: {', '.join(not_usable)} (see doctor --json .tools for why)")
             gpu = d["gpu_encoders"]
             if gpu["status"] == "parsed":
-                print(f"GPU-backed encoders in this build: {len(gpu['present'])} (no tool here uses one; names in doctor --json)")
+                print(f"GPU-backed encoders in this build: {len(gpu['present'])} (only --hw / FFMPEG_SKILL_HW=1 use one, VideoToolbox on Apple Silicon; names in doctor --json)")
             print(_fonts_summary_line(d["fonts"]))
             print("full detail: doctor --json (capability lists, per-tool `usable`, fix hints)")
             for err in d["errors"]:

package/scripts/graphics.py

@@ -125,6 +125,10 @@ def main() -> int:
     for _attr in ("name", "title", "subtitle", "text", "top", "bottom"):
         _v = getattr(args, _attr, None)
         if isinstance(_v, str):
+            # one line-break form for every route: libass draws a bare CR as nothing, drawtext
+            # ignores one trailing newline, and lines_of() counts the rest -- so the layout and the
+            # drawn lines agree only if the text is normalised here, once
+            _v = _v.replace("\r\n", "\n").replace("\r", "\n").rstrip("\n")
             setattr(args, _attr, _v if _v.strip() else None)
 
     args.platform = resolve_platform(args.platform)
@@ -295,6 +299,15 @@ def main() -> int:
                                   slice_overlong=True, sliced=sliced_atoms) if para.strip() else [para])
         return "\n".join(out)
 
+    def lines_of(text):
+        """How many lines drawtext and libass draw for `text` (a trailing newline is not one)."""
+        return max(1, len(str(text or "").replace("\r\n", "\n").replace("\r", "\n").rstrip("\n").split("\n")))
+
+    def block_h(text, size_px):
+        """The height the layouts below give a label: `size_px` for the first line, as they always
+        have, and a line pitch of 1.2 x the size for each further one."""
+        return size_px + (lines_of(text) - 1) * int(size_px * 1.2)
+
     def add_text(text, drawtext, *, target=None, **el):
         """One line of template text: a drawtext filter on the old route, an ASS element on the
         new one. The geometry is computed identically either way."""
@@ -314,7 +327,8 @@ def main() -> int:
         h1 = int(base * 0.055)
         h2 = int(base * 0.038)
         pad = int(base * 0.02)
-        bar_h = h1 + (h2 + pad if args.title else 0) + pad * 2
+        name_h = block_h(args.name, h1)
+        bar_h = name_h + (block_h(args.title, h2) + pad if args.title else 0) + pad * 2
         bar_w = int(base * 0.62)
         y0 = H - m_bottom - bar_h
         # slide in from the left over 0.4 s, slide out over 0.3 s (overlay evaluates x per frame)
@@ -328,7 +342,7 @@ def main() -> int:
         x_rest, x_off = m_left + tx_pad, -bar_w + tx_pad
         draws = []
         for text, fs, colour, ty in ((args.name, h1, text_c, y0 + pad),
-                                     (args.title, h2, primary, y0 + pad + h1 + pad // 2)):
+                                     (args.title, h2, primary, y0 + pad + name_h + pad // 2)):
             if not text:
                 continue
             draws.append(f"drawtext={drawtext_text_opts(text)}:{fo}:fontsize={fs}:"
@@ -355,17 +369,23 @@ def main() -> int:
         h1 = int(base * 0.11)
         h2 = int(base * 0.045)
         filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
+        # the title is centred as a block, so the bar and the subtitle sit below its last line:
+        # `title_h` is the block's height, as the one-line layout has always taken h1; a further
+        # subtitle line hangs below the first, whose position the one-line layout fixes
+        title_h = block_h(args.title, h1)
+        sub_y = title_h // 2 + int(base * 0.03)
+        sub_extra = block_h(args.subtitle, h2) - h2 if args.subtitle else 0
         add_text(args.title,
                  f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
                  y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
                  outline_color="000000", start=s, end=e, fade=(300, 300))
-        filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{h1 // 2 + (0 if args.subtitle else 0)}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
+        filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{title_h // 2}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
         if args.subtitle:
             add_text(args.subtitle,
-                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
+                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{sub_y + sub_extra // 2}:alpha='{fade_a}':{en}",
                      size=h2, color=primary, font=ass_font_family(), align=5, x=W / 2,
-                     y=H / 2 + h1 // 2 + int(base * 0.03), outline=max(1.0, h2 / 20.0),
+                     y=H / 2 + sub_y + sub_extra // 2, outline=max(1.0, h2 / 20.0),
                      outline_color="000000", start=s, end=e, fade=(300, 300))
 
     elif args.template in ("chapter", "bug"):
@@ -439,10 +459,13 @@ def main() -> int:
         hen = f"enable='between(t,{s:.3f},{he:.3f})'"
         h1 = int(base * 0.085)
         bar_h = max(3, int(base * 0.01))
-        band_h = int(base * 0.30)
+        hook_title = wrapped(args.title, h1)
+        # the base band (30% of the short side) holds two lines; a longer wrapped title (a 9:16
+        # hook is four or five) grows the band to the text plus 0.7 of a line of margin, instead of
+        # drawing white text on the bare video. The band is clipped at the frame edges.
+        band_h = min(H, max(int(base * 0.30), block_h(hook_title, h1) + int(h1 * 0.7)))
         y0 = (H - band_h) // 2
         filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
-        hook_title = wrapped(args.title, h1)
         add_text(hook_title,
                  f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}"
                  f"{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2:{hen}",

package/scripts/silence.py

@@ -141,9 +141,38 @@ def resolve_filler(args, meta):
                 "pass the result with --words.", kind="input")
 
     lang = args.filler_lang
+    reported_lang = lang
     if lang == "auto":
-        lang = str((raw or {}).get("language") or "").lower()[:2] if isinstance(raw, dict) else ""
-        lang = lang if lang in FILLER_WORDS else "en"
+        # the language the transcript says it is in: a --words document's own field, else what the
+        # engine was told or detected for this run (`--transcribe`). A language that is known and has
+        # no built-in list is refused, as --filler-lang names it: the English list would cut real
+        # words of that language (Norwegian "er" is "is"), and a transcript with no language at all
+        # (or one that says "auto", which is no language either) keeps the English list it always had
+        # the ISO 639-2 spellings of the languages that have a built-in list (the mux tag uses them)
+        iso3 = {"eng": "en", "spa": "es", "deu": "de", "ger": "de", "fra": "fr", "fre": "fr",
+                "ita": "it", "jpn": "ja", "por": "pt"}
+
+        def _code(value) -> str:
+            value = str(value or "").strip().lower().replace("_", "-")
+            if value in ("", "auto"):
+                return ""
+            # a regional tag names its primary language (ja-JP is ja); a three-letter code that is not
+            # in the table stays as it is (est is Estonian, not the Spanish "es"); a word such as
+            # "english" is cut to its two-letter code
+            primary = value.split("-")[0]
+            if primary in iso3:
+                return iso3[primary]
+            return primary[:2] if len(primary) > 3 else primary
+        spoken = _code((raw or {}).get("language")) if isinstance(raw, dict) else ""
+        spoken = spoken or _code(transcription.get("language") or transcription.get("detected_language"))
+        if spoken and spoken not in FILLER_WORDS and not args.filler_words:
+            die(f"the transcript is in {spoken}, which has no built-in filler list. The languages with one are "
+                f"{', '.join(sorted(FILLER_WORDS))}; pass --filler-words FILE with your own list for {spoken}, or "
+                "--filler-lang for a language that has one.", kind="input")
+        lang = spoken if spoken in FILLER_WORDS else "en"
+        # with a custom list the run goes ahead, and the result names the language it heard, not the
+        # English list it did not use
+        reported_lang = spoken or lang
     listname = "builtin"
     if args.filler_words:
         wordlist = set(_word_list(read_text_or_die(args.filler_words, "--filler-words")))
@@ -174,7 +203,7 @@ def resolve_filler(args, meta):
             warnings.append(f"--filler-extra {', '.join(extra_markers)}: a discourse marker, not a "
                             "disfluency -- this will cut real sentences.")
     block = {
-        "lang": lang, "source": source, "engine": engine,
+        "lang": reported_lang, "source": source, "engine": engine,
         **({"transcription": transcription} if engine and transcription else {}),
         "words": sorted(wordlist), "removed": [dict(s) for s in spans],
         "removed_count": len(spans),