ffmpeg-skill 2.8.5 → 2.8.6

package/README.md

@@ -356,7 +356,7 @@ npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unkn
 
 `doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor` also reports fonts: the default drawtext family, and `fonts.scripts` — one `available`/`missing`/`unknown` per writing system (ja, zh, ko, ar, he, hi, th, ru, el) with the file it would use — so "can this machine render Korean captions" is answered before the job, not after. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.
 
-`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). It never affects `ok` or any tool's `usable`. The one GPU path a tool uses is Apple VideoToolbox, opt-in: `--hw` on every re-encoding tool (h264/hevc/prores on the GPU, AV1 stays on SVT-AV1), `FFMPEG_SKILL_HW=1` to make it this machine's default for everything except `export.py`'s delivery presets (those take `--hw` explicitly, or `render.py --hw` for a whole project). It runs only on Apple Silicon and never by default; it falls back to the CPU encoder — reported in the result's `hw.fallback`/`hw.notes` — only when VideoToolbox itself refuses a job (any other ffmpeg failure is reported as it happened, not retried); every result names the `encoder` that actually ran (`batch.py`, which encodes nothing itself: each `results` row), and a GPU encode adds a `notes` line that its quality is not CRF-equivalent. Measured on an M4 Max, 2–7× faster than x264/x265 `medium`; at matched SSIM (`tests/bench_vt.py`) 1.1–2.9× the bytes on SDR and 1.9–3.5× on HDR, which is why it is a flag and not the default (`docs/design-decisions.md`). `doctor --json`'s `hw` says whether this machine can run it (`platform_ok`) and whether it is the default here (`default_on`).
+`doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). It never affects `ok` or any tool's `usable`. The one GPU path a tool uses is Apple VideoToolbox, opt-in: `--hw` on every re-encoding tool (h264/hevc/prores on the GPU, AV1 stays on SVT-AV1), `FFMPEG_SKILL_HW=1` to make it this machine's default for everything except `export.py`'s delivery presets (those take `--hw` explicitly, or `render.py --hw` for a whole project). It runs only on Apple Silicon and never by default, except on a build with no `libx264`/`libx265` (an LGPL ffmpeg that has only `h264_videotoolbox`/`hevc_videotoolbox`): there it is the only encoder, so every re-encoding tool and `export.py`'s presets use it without `--hw`, the result says `hw.source: "auto"`, and `doctor` lists the missing x264/x265 under `covered_by` instead of calling the tools unusable (`--no-hw` still asks for the CPU). It falls back to the CPU encoder — reported in the result's `hw.fallback`/`hw.notes` — only when VideoToolbox itself refuses a job (any other ffmpeg failure is reported as it happened, not retried); every result names the `encoder` that actually ran (`batch.py`, which encodes nothing itself: each `results` row), and a GPU encode adds a `notes` line that its quality is not CRF-equivalent. Measured on an M4 Max, 2–7× faster than x264/x265 `medium`; at matched SSIM (`tests/bench_vt.py`) 1.1–2.9× the bytes on SDR and 1.9–3.5× on HDR, which is why it is a flag and not the default (`docs/design-decisions.md`). `doctor --json`'s `hw` says whether this machine can run it (`platform_ok`) and whether it is the default here (`default_on`).
 
 ## Gotchas and best practices
 

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.5`) | any release |
+| `skill.version` | the npm / package.json version (`2.8.6`) | 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.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.8.6", "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"},
@@ -228,8 +228,12 @@ input schema (`hw`, `no_hw`; MCP sends `--hw` for `hw: true` and `--no-hw` for `
 mutually exclusive. `--hw` moves an h264/hevc/prores encode to Apple VideoToolbox (Apple Silicon
 only; AV1 stays on the CPU); `--no-hw` keeps it on the CPU even when `FFMPEG_SKILL_HW=1` makes the
 GPU this machine's default. Neither changes anything for a caller that passes neither on a
-machine without the variable. What ran is in the result's `encoder` and `hw` (see the keys added
-after 2.2.2, and `doctor`'s `gpu_encoders` below).
+machine without the variable, with one exception: on a build whose `ffmpeg -encoders` has no
+`libx264` (or no `libx265`) but has the matching VideoToolbox encoder, on Apple Silicon, an H.264
+(or HEVC) encode takes VideoToolbox without `--hw` -- `export.py`'s presets too, which
+`FFMPEG_SKILL_HW` never moves -- because there is no CPU encoder to choose instead; `--no-hw` still
+asks for the CPU and gets what ffmpeg says about it. What ran is in the result's `encoder` and `hw`
+(see the keys added after 2.2.2, and `doctor`'s `gpu_encoders` and `covered_by` below).
 
 `--plan FILE` (1.6) is a dry run that also writes a plan document: `{"plan_version": 1,
 "tool", "argv", "cwd", "inputs": [{"path", "size", "sha256_head_tail"}], "commands",
@@ -410,11 +414,22 @@ acompressor A->A`) by the io-spec token, so the flag width does not matter; fixt
 both live in `tests/fixtures/`.
 
 `ffmpeg-skill doctor` exits 0 when every required capability is available, 1 when one is
-missing, 2 when none is missing but a required one is unknown. `ok` is true only for 0.
-The keys of 0.9.0 (`available`, `missing`, `missing_optional`, `ok`) are unchanged.
+missing, 2 when none is missing but a required one is unknown. `ok` is true only for 0. The
+keys of 0.9.0 (`available`, `missing`, `missing_optional`, `ok`) are unchanged.
+
+One capability can be neither: `encoder:libx264` (`encoder:libx265`) absent from the build while
+`h264_videotoolbox` (`hevc_videotoolbox`) is in it, on a machine that can run VideoToolbox (the
+check `--hw` uses: macOS on Apple Silicon). The tools encode with VideoToolbox there without
+`--hw`, so the capability is left out of `available`, `missing` and `missing_optional` -- it is not
+in the build, and it blocks nothing -- and is named in the additive `covered_by`:
+`{"encoder:libx264": "encoder:h264_videotoolbox"}` (`{}` for every other build, which reports what
+it always did). `ok` and the per-tool `usable` follow what will run, a tool that needs the covered
+capability lists it in its own `covered_by`, and `notes` says its output is not CRF-equivalent.
+The contract's `capabilities.required`/`optional` lists still name `encoder:libx264`: they say what
+the tool needs from a build, not which encoder satisfies it on a given machine.
 
 `doctor`'s `tools` field folds that same per-capability `state` into a per-tool answer:
-`{"<tool>": {"usable": "yes"|"no"|"unknown", "missing": [...], "fix": "...", "unknown": [...]}}`.
+`{"<tool>": {"usable": "yes"|"no"|"unknown", "missing": [...], "fix": "...", "unknown": [...], "covered_by": {...}}}`.
 `missing`/`unknown` list only that tool's own required capabilities that are in that state
 (`missing` is absent when there is none, same for `unknown`); `fix` is a one-line, plain-language
 remedy for each missing capability, joined with "; " when there is more than one. This exists so
@@ -437,9 +452,10 @@ additive.
 "parsed"|"unparsed"|"failed"|"missing", "present": [...]}`. It proves the build shipped the
 capability, not that the GPU/driver on this machine will accept a job (that needs a real
 encode, which this introspection never runs). No tool declares or requires a GPU encoder, so
-`gpu_encoders` never affects `ok` or any tool's `usable`. `--hw` (and
+`gpu_encoders` never affects `ok` or any tool's `usable` (`covered_by`, above, is the one place a
+VideoToolbox encoder counts, and only for a libx264/libx265 the build lacks). `--hw` (and
 `FFMPEG_SKILL_HW=1`, which `export.py`'s delivery presets ignore) puts h264/hevc/prores encodes on
-VideoToolbox on Apple Silicon only, never by default. A job VideoToolbox refuses (the encoder could
+VideoToolbox on Apple Silicon only, never by default (a build without libx264/libx265 excepted). A job VideoToolbox refuses (the encoder could
 not open, or its compression session failed) is re-encoded on the CPU and said so in the result's
 `hw.fallback`/`hw.notes`; any other failure is not retried. When `FFMPEG_SKILL_HW=1` rather than `--hw` chose the GPU and the GPU ran,
 `hw.notes` also says so, with the file-size cost and `--no-hw` as the remedy for a final
@@ -587,7 +603,7 @@ Per-tool keys added after 2.2.2, all additive:
 | `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 |
+| `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), on `export.py` when `FFMPEG_SKILL_HW=1` is set but its delivery preset does not take it, and when an encode ran on VideoToolbox because the build has no `libx264`/`libx265`: `{requested, source: flag\|env\|auto, used, fallback, notes}`. `requested` says whether this run's encodes were asked onto VideoToolbox (`false` for that export, and for `source: "auto"`, where nobody asked: `notes` names the missing CPU encoder and the one that ran, and `--no-hw` is not offered as a remedy since there is no CPU encoder to go back to; a job VideoToolbox refuses there is a plain `kind: ffmpeg` failure, not retried), `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, 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.8.5",
+  "version": "2.8.6",
   "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/gotchas.md

@@ -293,7 +293,9 @@ intermediates and keep the default for the final export. On Apple Silicon,
 `--hw` (or `FFMPEG_SKILL_HW=1` for the machine) moves h264/hevc/prores encodes to
 VideoToolbox: 2–7× faster, 1.1–2.9× the bytes at the same quality (1.9–3.5× on HDR). The variable
 leaves `export.py`'s delivery presets on the CPU, which is the usual split (GPU
-intermediates, CPU delivery); `render.py --hw` puts the export on the GPU too.
+intermediates, CPU delivery); `render.py --hw` puts the export on the GPU too. A build with no
+libx264/libx265 (an LGPL ffmpeg) has no CPU delivery to keep: its tools and presets use
+VideoToolbox by themselves, `hw.source` says `auto`.
 Check `encoder`/`hw` in the result: a job the GPU refuses (H.264 wider than 4096)
 was re-encoded on the CPU.
 

package/scripts/_common/decision.py

@@ -337,14 +337,49 @@ def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: b
         (_vt_bt709("hevc") if keep_bt709 else [])
 
 
+# An LGPL ffmpeg (the kind a desktop app ships) has VideoToolbox but neither libx264 nor libx265.
+# There the CPU line cannot run at all, so VideoToolbox is the only encoder there is and takes the
+# job without --hw (#314). Only when the encoder list was read and lacks the CPU encoder, and only
+# where --hw would run; a build that has libx264 never gets here (docs/design-decisions.md).
+_VT_FOR_CPU = {"libx264": "h264_videotoolbox", "libx265": "hevc_videotoolbox"}
+
+
+def _vt_in_place_of(cpu_encoder: Optional[str]) -> Optional[str]:
+    """The VideoToolbox encoder that takes over from `cpu_encoder` because this ffmpeg build lacks
+    it, else None: not when --hw already decided, nor under an explicit --no-hw (the caller asked
+    for the CPU), nor on a machine VideoToolbox cannot run on. The platform is asked before the
+    encoder list, so Linux and Windows never read it for this. An empty list (ffmpeg's could not
+    be read) proves nothing is missing."""
+    vt = _VT_FOR_CPU.get(cpu_encoder or "")
+    if vt is None or STATE.hw or STATE.hw_source == "flag" or hw_platform_reason() is not None:
+        return None
+    have = ffmpeg_encoders()
+    return vt if have and cpu_encoder not in have and vt in have else None
+
+
+def _note_vt_in_place_of(cpu_encoder: str, vt: str) -> None:
+    if cpu_encoder not in STATE.hw_auto:
+        STATE.hw_auto.append(cpu_encoder)
+    note = f"{cpu_encoder} is not in this ffmpeg build, so this encode ran on {vt} (VideoToolbox) instead"
+    if note not in STATE.hw_notes:
+        STATE.hw_notes.append(note)
+
+
 def _maybe_hw(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: bool, cpu: List[str]) -> List[str]:
-    """`cpu` unchanged unless --hw / $FFMPEG_SKILL_HW is on and VideoToolbox can take `codec`; the
-    swap is remembered so run() can put the CPU line back if the GPU refuses the job."""
-    if not STATE.hw:
+    """`cpu` unchanged unless --hw / $FFMPEG_SKILL_HW is on and VideoToolbox can take `codec`, or
+    unless the build has no CPU encoder for it (_vt_in_place_of); the --hw swap is remembered so
+    run() can put the CPU line back if the GPU refuses the job. A build without the CPU encoder
+    has no line to put back, so nothing is remembered for it."""
+    cpu_encoder = cpu[cpu.index("-c:v") + 1] if "-c:v" in cpu else None
+    vt_name = _vt_in_place_of(cpu_encoder)
+    if not STATE.hw and vt_name is None:
         return cpu
     vt = _vt_args(codec, crf, meta, keep_bt709)
     if vt is None:
         return cpu
+    if vt_name:
+        _note_vt_in_place_of(cpu_encoder or "", vt_name)
+        return vt
     # a copy: a caller that edits the returned line in place (export.py strips -movflags) must
     # not edit the recorded slice with it, or restate_last_swap() never sees the line as built
     STATE.hw_swaps.append((list(vt), cpu))
@@ -357,6 +392,8 @@ _CPU_TO_CODEC = {"libx264": "h264", "libx265": "hevc", "prores_ks": "prores"}
 def hw_preset_video(video: List[str], meta: Optional[Dict[str, Any]], *, bt709: bool) -> List[str]:
     """export.py's fixed-preset encoder line moved to VideoToolbox (same codec, the preset's -crf
     mapped to -q:v, its -r kept); unchanged -- with the reason noted -- when that cannot apply.
+    Called under --hw, and for a preset whose libx264/libx265 this build lacks (_vt_in_place_of),
+    where it is the only encoder there is; otherwise it returns `video` untouched.
 
     `bt709`: whether export.py tags this preset's CPU line BT.709 (every fixed preset but prores,
     whose master keeps the source's tags). The VideoToolbox line writes the format the CPU preset
@@ -367,6 +404,9 @@ def hw_preset_video(video: List[str], meta: Optional[Dict[str, Any]], *, bt709:
     codec = _CPU_TO_CODEC.get(enc or "")
     if codec is None:
         return video
+    vt_name = _vt_in_place_of(enc)
+    if not STATE.hw and vt_name is None:
+        return video
     crf = int(video[video.index("-crf") + 1]) if "-crf" in video else 18
     vt = _vt_args(codec, crf, meta if codec == "prores" else None, bt709)
     if vt is None:
@@ -374,6 +414,9 @@ def hw_preset_video(video: List[str], meta: Optional[Dict[str, Any]], *, bt709:
     vt = strip_movflags(vt)  # export adds it
     if "-r" in video:
         vt += ["-r", video[video.index("-r") + 1]]
+    if vt_name:
+        _note_vt_in_place_of(enc or "", vt_name)
+        return vt
     # the CPU line export would have written: the preset's own options plus the BT.709 tags export
     # adds to it (only to the CPU line), so a GPU->CPU fallback is tagged exactly like a CPU run
     STATE.hw_swaps.append((list(vt), list(video) + (bt709_tag_args(enc) if bt709 else [])))

package/scripts/_common/emit.py

@@ -28,7 +28,7 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
     ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
     STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
-    if kind == "ffmpeg" and "hw" not in extra and (ctx.hw or ctx.hw_stages or ctx.hw_env_ignored):
+    if kind == "ffmpeg" and "hw" not in extra and (ctx.hw or ctx.hw_stages or ctx.hw_env_ignored or ctx.hw_auto):
         # a tool's own ffmpeg failure (cut.py runs run(check=False) and dies itself; render.py
         # re-raises a stage's) carries `encoder` and `hw` as run()'s _fail() does: under --hw /
         # $FFMPEG_SKILL_HW two encoders may have run, and a caller must know whose failure it is
@@ -116,6 +116,8 @@ def hw_report(ctx: "Context", enc: Optional[str]) -> Dict[str, Any]:
     source = ctx.hw_source if ctx.hw else next((st.get("source") for st in stages if st.get("requested")), None)
     if not requested and ctx.hw_env_ignored:
         source = "env"
+    if not requested and ctx.hw_auto:
+        source = "auto"  # nobody asked: this build has no libx264/libx265, so VideoToolbox was the only encoder
     # a stage that reported its source without asking (export.py under the variable: requested
     # false, source env) still names where the request came from
     source = source or next((st.get("source") for st in stages if st.get("source")), None)
@@ -128,14 +130,15 @@ def hw_report(ctx: "Context", enc: Optional[str]) -> Dict[str, Any]:
         # the machine default, not this call, chose the GPU: say what it costs and how to opt out
         # (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"):
+    if ctx.hw_env_ignored and enc not in (None, "copy") and not vt:
         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}
 
 
-def hw_quality_note(enc: Optional[str], line: Optional[str]) -> Optional[str]:
-    """The `notes` line every VideoToolbox encode carries: its quality is not the CRF encode's."""
+def hw_quality_note(enc: Optional[str], line: Optional[str], no_cpu_encoder: bool = False) -> Optional[str]:
+    """The `notes` line every VideoToolbox encode carries: its quality is not the CRF encode's.
+    `no_cpu_encoder`: the build has no libx264/libx265, so `--no-hw` is no remedy and is not offered."""
     import re as _re
     if not enc or not enc.endswith("_videotoolbox"):
         return None
@@ -147,7 +150,7 @@ def hw_quality_note(enc: Optional[str], line: Optional[str]) -> Optional[str]:
     return (f"{enc}{' -q:v ' + m.group(1) if m else ''} is not CRF-equivalent: --quality (or the preset's CRF) is mapped "
             "to -q:v by an approximate SSIM fit (docs/design-decisions.md), so size and detail differ from the x264/x265 "
             "encode (~1.1-3.5x the bytes at matched SSIM); `verified` covers the output's measured properties, not quality "
-            "parity with the CPU encode; --no-hw for the CRF encode")
+            "parity with the CPU encode" + ("" if no_cpu_encoder else "; --no-hw for the CRF encode"))
 
 
 def _encoder_report(ctx: "Context") -> Dict[str, Any]:
@@ -157,7 +160,7 @@ def _encoder_report(ctx: "Context") -> Dict[str, Any]:
     $FFMPEG_SKILL_HW, a stage's, or the variable a delivery preset does not take)."""
     enc, _line = _video_encoders(ctx.commands)
     out: Dict[str, Any] = {"encoder": enc} if enc else {}
-    if ctx.hw or ctx.hw_stages or ctx.hw_env_ignored:
+    if ctx.hw or ctx.hw_stages or ctx.hw_env_ignored or ctx.hw_auto:
         out["hw"] = hw_report(ctx, enc)
     return out
 
@@ -167,7 +170,8 @@ def _hw_notes_for(ctx: "Context") -> List[str]:
     and (render.py) every stage that ran on VideoToolbox."""
     enc, line = _video_encoders(ctx.commands)
     out: List[str] = []
-    for note in [hw_quality_note(enc, line)] + [st.get("quality_note") for st in ctx.hw_stages]:
+    cpu = {"h264_videotoolbox": "libx264", "hevc_videotoolbox": "libx265"}.get(enc or "")
+    for note in [hw_quality_note(enc, line, cpu in ctx.hw_auto)] + [st.get("quality_note") for st in ctx.hw_stages]:
         if note and note not in out:
             out.append(note)
     return out
@@ -186,7 +190,7 @@ def absorb_stage_hw(stage: str, doc: Any, ctx: "Optional[Context]" = None) -> No
         if n not in ctx.hw_notes and not any(existing.endswith(": " + n) for existing in ctx.hw_notes):
             ctx.hw_notes.append(f"{stage}: {n}")
     enc, line = _video_encoders([str(c) for c in (doc.get("commands") or [])])
-    quality = hw_quality_note(enc, line) if hw.get("used") else None
+    quality = hw_quality_note(enc, line, hw.get("source") == "auto") if hw.get("used") else None
     ctx.hw_stages.append({"stage": stage, "requested": bool(hw.get("requested")), "source": hw.get("source"),
                           "used": hw.get("used"), "fallback": bool(hw.get("fallback")), "quality_note": quality})
 

package/scripts/_common/runner.py

@@ -192,7 +192,7 @@ class Context:
     """
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
-                 "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages")
+                 "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto")
 
     def __init__(self) -> None:
         self.reset()
@@ -220,6 +220,7 @@ class Context:
         self.hw_fallback = False                     # run() re-encoded a job VideoToolbox refused on the CPU (or a stage reported one)
         self.hw_env_ignored = False                  # $FFMPEG_SKILL_HW=1 was set but this tool's delivery preset does not take it (export.py)
         self.hw_stages: List[Dict[str, Any]] = []    # render.py: the `hw` facts each stage (a child process) reported
+        self.hw_auto: List[str] = []                 # CPU encoders (libx264/libx265) this ffmpeg build lacks, whose encodes ran on VideoToolbox without --hw
 
 
 STATE = Context()
@@ -297,7 +298,7 @@ def apply_common(args: "argparse.Namespace") -> None:
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
     STATE.codec = getattr(args, "codec", None) or None
-    STATE.hw_notes, STATE.hw_swaps, STATE.hw_fallback, STATE.hw_env_ignored, STATE.hw_stages = [], [], False, False, []
+    STATE.hw_notes, STATE.hw_swaps, STATE.hw_fallback, STATE.hw_env_ignored, STATE.hw_stages, STATE.hw_auto = [], [], False, False, [], []
     flag = hw_flag(args)
     if flag is not None:
         STATE.hw, STATE.hw_source = bool(flag), "flag"
@@ -457,7 +458,7 @@ def _fail(cmd: Sequence[str], returncode: int, stderr: str, ctx: "Optional[Conte
     ctx = ctx or STATE
     tail = "\n".join(stderr.strip().splitlines()[-15:])
     what, extra = str(cmd[0]), {}
-    enc = video_encoder_of(cmd) if ctx.hw else None
+    enc = video_encoder_of(cmd) if ctx.hw or ctx.hw_auto else None
     if enc:
         on_gpu = enc.endswith("_videotoolbox")
         why = videotoolbox_failure(stderr) if on_gpu else None
@@ -1330,9 +1331,12 @@ def ffmpeg_encoders() -> set:
     if _ENCODERS is None:
         _ENCODERS = set()
         tool = "ffprobe" if STATE.dry_run else "ffmpeg"
+        # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
+        # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
+        limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
         try:
             out = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
-                                 stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=PROBE_TIMEOUT).stdout
+                                 stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=limit).stdout
             _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
         except (OSError, subprocess.SubprocessError):
             pass

package/scripts/_contract.py

@@ -403,7 +403,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "every ffmpeg command line planned or run"},
             "probe": {"type": "object", "description": "probe of the output when a file was written"},
             "encoder": {"type": "string", "description": "the video encoder the last ffmpeg command used (after any GPU->CPU fallback; under --dry-run the planned one; render.py and waveform.py: their stages' commands included), `copy` for a stream copy; absent when no command encoded video"},
-            "hw": {"type": "object", "description": "present when VideoToolbox was asked for (--hw, $FFMPEG_SKILL_HW, a render.py stage, a batch.py item) and on export.py when $FFMPEG_SKILL_HW=1 is set but its delivery preset does not take it: {requested: whether this run's encodes were asked onto VideoToolbox (false for that export), source: flag|env, used: true|false whether the encoder that ran last is VideoToolbox, null under --dry-run (nothing ran) and when this process ran no encode itself (batch.py: its stages are child processes; its top-level hw gathers the items' requested/source/fallback/notes and each results row carries its item's encoder and hw), fallback: a job VideoToolbox refused (encoder open or compression session failure; nothing else is retried) was re-encoded on the CPU, notes: why an encode stayed on or fell back to the CPU, and, when $FFMPEG_SKILL_HW chose the GPU and it ran, what that costs and that --no-hw opts out}. A VideoToolbox encode also adds a top-level notes line: its quality is not CRF-equivalent. A kind: ffmpeg failure under --hw / $FFMPEG_SKILL_HW carries encoder and hw too"},
+            "hw": {"type": "object", "description": "present when VideoToolbox was asked for (--hw, $FFMPEG_SKILL_HW, a render.py stage, a batch.py item), on export.py when $FFMPEG_SKILL_HW=1 is set but its delivery preset does not take it, and when this ffmpeg build has no libx264/libx265 and an encode ran on VideoToolbox instead: {requested: whether this run's encodes were asked onto VideoToolbox (false for that export, and for the build without libx264/libx265), source: flag|env|auto (auto: nobody asked, the build has no libx264/libx265 and this Apple Silicon machine ran VideoToolbox in its place), used: true|false whether the encoder that ran last is VideoToolbox, null under --dry-run (nothing ran) and when this process ran no encode itself (batch.py: its stages are child processes; its top-level hw gathers the items' requested/source/fallback/notes and each results row carries its item's encoder and hw), fallback: a job VideoToolbox refused (encoder open or compression session failure; nothing else is retried) was re-encoded on the CPU, notes: why an encode stayed on or fell back to the CPU, and, when $FFMPEG_SKILL_HW chose the GPU and it ran, what that costs and that --no-hw opts out}. A VideoToolbox encode also adds a top-level notes line: its quality is not CRF-equivalent. A kind: ffmpeg failure under --hw / $FFMPEG_SKILL_HW carries encoder and hw too"},
             "plan": {"type": "string", "description": "with --plan FILE: the plan document written (the run itself is a dry run)"},
             "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
             "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets) or check (render)"}}
@@ -690,6 +690,24 @@ def _gpu_encoders(encoders_listing: Dict[str, Any]) -> Dict[str, Any]:
     return {"status": "parsed", "present": present}
 
 
+# What the tools do about a build without libx264 / libx265 (_common.decision._vt_in_place_of)
+_VIDEOTOOLBOX_FOR = {"encoder:libx264": "encoder:h264_videotoolbox", "encoder:libx265": "encoder:hevc_videotoolbox"}
+
+
+def _covered_by_videotoolbox(encoders_listing: Dict[str, Any]) -> Dict[str, str]:
+    """`{"encoder:libx264": "encoder:h264_videotoolbox", ...}` for each CPU encoder the (read) listing
+    lacks while the matching VideoToolbox encoder is listed and this machine can run it: the tools
+    encode with the latter there without --hw, so the former does not block anything. Empty
+    otherwise -- an unread listing proves nothing, and a build that has the CPU encoder needs no cover."""
+    if encoders_listing["status"] != "parsed":
+        return {}
+    from _common.runner import hw_platform_reason
+    if hw_platform_reason() is not None:
+        return {}
+    have = set(encoders_listing["names"])
+    return {cap: alt for cap, alt in _VIDEOTOOLBOX_FOR.items() if cap[8:] not in have and alt[8:] in have}
+
+
 def _version_line(binary: str) -> Optional[str]:
     exe = _exe(binary)
     if not exe:
@@ -863,11 +881,19 @@ def doctor() -> Dict[str, Any]:
     `missing` (a filter that exists is not reported absent) nor into `available` (a failed detection
     is not a pass). `ok` is true only when nothing required is missing or unknown.
 
+    One exception to "missing blocks": `encoder:libx264` / `encoder:libx265` absent from the build
+    while the matching VideoToolbox encoder is present and this machine can run it (Apple Silicon).
+    The tools use VideoToolbox there without --hw (#314), so the capability is neither `available`
+    (it is not in the build) nor `missing` (nothing is blocked): it is left out of both lists, named
+    in `covered_by`, and a tool that needs it stays usable. A build that has libx264 reports exactly
+    what it did before.
+
     `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 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
+    `gpu_encoders` never affects `ok` or any tool's `usable` (`covered_by` is the one place a
+    VideoToolbox encoder counts: for a libx264/libx265 the build lacks, see above). 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).
 
@@ -886,6 +912,7 @@ def doctor() -> Dict[str, Any]:
     sets = {k: set(v["names"]) for k, v in listings.items()}
     state: Dict[str, str] = {}  # capability -> available | missing | unknown
     wanted = required_capabilities()
+    covered = _covered_by_videotoolbox(listings["encoders"])
     drawtext_probe: Optional[Dict[str, Any]] = None
     drawtext_crashed = False  # listed but crashed (#100), as opposed to absent from the build
 
@@ -935,14 +962,16 @@ def doctor() -> Dict[str, Any]:
         else:
             state[cap] = "missing"
     available = sorted(c for c, st in state.items() if st == "available")
-    missing_required = sorted(c for c in wanted["required"] if state[c] == "missing")
-    missing_optional = sorted(c for c in wanted["optional"] if state[c] == "missing")
+    missing_required = sorted(c for c in wanted["required"] if state[c] == "missing" and c not in covered)
+    missing_optional = sorted(c for c in wanted["optional"] if state[c] == "missing" and c not in covered)
     unknown = sorted(c for c, st in state.items() if st == "unknown")
     unknown_required = [c for c in unknown if c in wanted["required"]]
     errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]
     if drawtext_probe is not None and drawtext_probe["status"] != "available":
         errors.append(f"filter:drawtext: {drawtext_probe['detail']}")
     notes = [f"filter:drawtext: {drawtext_probe['note']}"] if drawtext_probe and drawtext_probe.get("note") else []
+    notes += [f"{cap}: not in this ffmpeg build; the tools that need it encode with {alt[8:]} (VideoToolbox) instead, so their output is "
+              "not CRF-equivalent (the result's `encoder`/`hw` say so)" for cap, alt in sorted(covered.items())]
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
@@ -957,7 +986,8 @@ def doctor() -> Dict[str, Any]:
         "errors": errors,
         **({"notes": notes} if notes else {}),
         "ok": not missing_required and not unknown_required,
-        "tools": _tool_usability(state, drawtext_crashed),
+        "tools": _tool_usability(state, drawtext_crashed, covered),
+        "covered_by": covered,
         "gpu_encoders": _gpu_encoders(listings["encoders"]),
         "hw": _hw_default(),
         "fonts": _fonts_capability(probe=True),
@@ -1079,15 +1109,17 @@ def _capability_fix_hint(cap: str, drawtext_crashed: bool = False) -> str:
     return f"'{cap}' is not available; see docs/contract.md"
 
 
-def _tool_usability(state: Dict[str, str], drawtext_crashed: bool = False) -> Dict[str, Dict[str, Any]]:
+def _tool_usability(state: Dict[str, str], drawtext_crashed: bool = False, covered: Optional[Dict[str, str]] = None) -> Dict[str, Dict[str, Any]]:
     """Per-tool usable/missing/unknown, folded from the same capability `state` doctor already
     computed. Answers "can I run this tool on this machine today", not just "what capabilities
     exist" -- a caller reading only `available`/`missing` still has to cross-reference each tool's
-    own required-capability list by hand to answer that."""
+    own required-capability list by hand to answer that. A required capability in `covered`
+    (libx264 replaced by VideoToolbox on this machine) blocks nothing; the tool lists it in `covered_by`."""
+    covered = covered or {}
     tools: Dict[str, Dict[str, Any]] = {}
     for name, meta in TOOL_META.items():
         required = list(meta["required"])
-        missing = [c for c in required if state.get(c) == "missing"]
+        missing = [c for c in required if state.get(c) == "missing" and c not in covered]
         unknown = [c for c in required if state.get(c) == "unknown"]
         entry: Dict[str, Any] = {"usable": "no" if missing else ("unknown" if unknown else "yes")}
         if missing:
@@ -1095,6 +1127,9 @@ def _tool_usability(state: Dict[str, str], drawtext_crashed: bool = False) -> Di
             entry["fix"] = "; ".join(dict.fromkeys(_capability_fix_hint(c, drawtext_crashed) for c in missing))
         if unknown:
             entry["unknown"] = unknown
+        via = {c: covered[c] for c in required if c in covered}
+        if via:
+            entry["covered_by"] = via
         tools[name] = entry
     return tools
 
@@ -1547,6 +1582,8 @@ def main() -> int:
             print(f"missing optional: {', '.join(d['missing_optional']) or 'none'}")
             if d["unknown"]:
                 print(f"unknown (detection failed, not proven missing): {', '.join(d['unknown'])}")
+            for cap, alt in sorted(d["covered_by"].items()):
+                print(f"{cap} is not in this build; VideoToolbox ({alt[8:]}) encodes in its place (not CRF-equivalent)")
             not_usable = sorted(name for name, t in d["tools"].items() if t["usable"] != "yes")
             if not_usable and d["ok"]:
                 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)")

package/scripts/export.py

@@ -202,9 +202,11 @@ def main() -> int:
         video[video.index("-preset") + 1] = "veryfast"
     # a fixed preset's line is tagged BT.709 (prores, an editing master, keeps the source's tags)
     tag_bt709 = args.preset not in ("prores",) and not p.get("codec")
-    if STATE.hw and not p.get("codec") and video:
+    if not p.get("codec") and video:
         # --hw (never $FFMPEG_SKILL_HW here) puts a fixed preset on VideoToolbox: the same codec,
-        # its CRF mapped to -q:v, the preset's frame rate kept; tags come with the VT line itself
+        # its CRF mapped to -q:v, the preset's frame rate kept; tags come with the VT line itself.
+        # A build without libx264/libx265 has no other encoder, so it goes there without --hw too
+        # (hw_preset_video returns the line untouched in every other case)
         video = hw_preset_video(video, meta, bt709=tag_bt709)
     cmd += video
     if args.preset != "copy":