Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
fix: use VideoToolbox when the ffmpeg build has no libx264/libx265 (#324)
Shogo Kajiyamaecd87c20bcab
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e02aa8f..0f1f512 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,10 @@## Unreleased-(nothing yet)+### Added++- **A build without libx264/libx265 encodes on VideoToolbox by itself (#314).** An LGPL ffmpeg such as the one a desktop app ships has `h264_videotoolbox`/`hevc_videotoolbox` and no x264/x265, so every H.264/HEVC line (`fit`, `cut --accurate`, the other re-encoding tools, and `export.py`'s `youtube`/`reels`/`h265`/... presets) failed with "Unknown encoder". When `ffmpeg -encoders` lacks the CPU encoder, has the matching VideoToolbox one, and the machine is Apple Silicon (the check `--hw` uses), the tool now uses VideoToolbox without `--hw`, built as under `--hw`. The result's `hw` is `{requested: false, source: "auto", used, ...}` with a note naming the missing and the used encoder, plus the usual not-CRF-equivalent `notes` line (without the `--no-hw` advice). A build that has libx264/libx265 is unchanged, and so are `--no-hw` (still the CPU), `FFMPEG_SKILL_HW` (still does not move `export.py`'s presets) and AV1/ProRes.+- **`doctor` agrees.** A missing `encoder:libx264`/`encoder:libx265` whose VideoToolbox encoder is in the build, on a machine that can run it, is left out of `available`/`missing`/`missing_optional` and named in the new `covered_by` (`{}` otherwise), so `ok` and each tool's `usable` describe what will run; a tool that needs it also carries `covered_by`, and `notes` says the output is not CRF-equivalent. The contract's capability lists are unchanged.## 2.8.5diff --git a/README.md b/README.mdindex 6ef6097..609fc6e 100644--- a/README.md+++ b/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 practicesdiff --git a/docs/contract.md b/docs/contract.mdindex 24ca841..e59552a 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -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 Silicononly; AV1 stays on the CPU); `--no-hw` keeps it on the CPU even when `FFMPEG_SKILL_HW=1` makes theGPU 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; fixtboth 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-languageremedy 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 thecapability, not that the GPU/driver on this machine will accept a job (that needs a realencode, 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 couldnot 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 |diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 1a8038c..deea470 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -856,12 +856,43 @@ not a new file format this tool would have to maintain.intermediate is the place for speed; a file that is uploaded is the place for bytes. So`FFMPEG_SKILL_HW=1` changes every re-encoding tool's default but not `export.py`'s deliverypresets, and `render.py --hw` is the one switch that puts a whole project, export included, on- the GPU. It is never switched on by anything else (not `--fast`, not a detected GPU). An+ the GPU. It is never switched on by anything else (not `--fast`, not a detected GPU), with one+ exception: a build that has no libx264/libx265 to choose instead (next entry). An`export.py` run under the variable says in `hw` (`requested: false`, `source: env`, a note) thatthe preset stayed on the CPU and that `--hw` moves it. Code: `_common.runner.apply_common`,`add_hw_orchestrator_args`. Tests: `HwResolutionTests`, `test_export_preset_needs_an_explicit_hw`(a dry run with VideoToolbox stood in, so it runs on every CI runner),`test_the_env_default_reaches_the_other_re_encoding_tools`.+- **A build without libx264 or libx265 encodes on VideoToolbox without `--hw`, delivery presets+ included (#314).** The reasons above are about a choice: speed against bytes. An LGPL ffmpeg (a+ desktop app ships one) has `h264_videotoolbox`/`hevc_videotoolbox` and neither x264 nor x265, so+ the CPU line is not a slower option, it fails ("Unknown encoder 'libx264'"), and "a file that is+ uploaded is the place for bytes" and "never switched on by anything else" have nothing to protect.+ So when the encoder list (`ffmpeg -encoders`) was read and lacks the CPU encoder the line would+ name (libx264 for H.264, libx265 for HEVC, each on its own), the matching VideoToolbox encoder is+ in it, and this machine passes `hw_platform_reason()` (Apple Silicon, the check `--hw` uses), every+ re-encoding tool and every fixed `export.py` preset (`reels`, `youtube`, `h265`, ...) takes the+ VideoToolbox line, built exactly as under `--hw`. The result says `hw: {requested: false, source:+ "auto", used, ...}` with a note naming the encoder that was missing and the one that ran, and the+ usual `notes` line that the quality is not CRF-equivalent (without the `--no-hw` advice: it has no+ CPU encoder to go back to). What does not change: a build that has the CPU encoder takes exactly+ the line it did (the platform is asked before the encoder list, so Linux and Windows read no list+ for this, and the Mac reads it once per process); `FFMPEG_SKILL_HW=1` still does not move the+ presets (the request to make it cover them was declined: with libx264 in the build the preset+ stays where the first entry puts it, and without it the build decides, so the variable has nothing+ left to add); an explicit `--no-hw` (or `render.py`/`batch.py --no-hw`) is the caller's choice of+ the CPU and is not overridden, ffmpeg then refuses it as before; `FFMPEG_SKILL_HW=0` is no flag+ and does not stop it; AV1 and ProRes are out of scope (their own missing-encoder refusals stand).+ An unreadable encoder list (empty) proves nothing is missing and changes nothing. No CPU line is+ recorded for it, so a job VideoToolbox refuses is a plain `kind: ffmpeg` failure naming+ `h264_videotoolbox`, not a retry that could not run. `doctor` agrees: a missing+ `encoder:libx264`/`libx265` whose VideoToolbox encoder is in the build, on a machine that passes the+ same check, is listed under the additive `covered_by` and in neither `available` nor `missing`, so+ `ok` and each tool's `usable` stand for what will run; the contract's `required`/`optional`+ capability lists are unchanged. Code: `_common.decision._vt_in_place_of`, `_maybe_hw`,+ `hw_preset_video`; `_contract._covered_by_videotoolbox`. Tests: `NoCpuEncoderTests`,+ `test_a_build_without_libx264_is_usable_where_videotoolbox_takes_its_place`,+ `test_libx264_stays_required_without_videotoolbox_or_off_apple_silicon`.- **CRF maps to VideoToolbox `-q:v` on the safe side, with a separate HDR curve.**`vt_quality` takes, at each CRF, the highest `-q:v` whose SSIM matched the CPU encode across`tests/bench_vt.py`'s clips (synthetic CG, fractal and grain, iPhone 17 Pro SDR and HLG at 30diff --git a/references/gotchas.md b/references/gotchas.mdindex a23c0a1..4515354 100644--- a/references/gotchas.md+++ b/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 toVideoToolbox: 2–7× faster, 1.1–2.9× the bytes at the same quality (1.9–3.5× on HDR). The variableleaves `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.diff --git a/scripts/_common/decision.py b/scripts/_common/decision.pyindex 69e4dae..7f2e963 100644--- a/scripts/_common/decision.py+++ b/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 cpuvt = _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 builtSTATE.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 -crfmapped 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 videocrf = int(video[video.index("-crf") + 1]) if "-crf" in video else 18vt = _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 itif "-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 runSTATE.hw_swaps.append((list(vt), list(video) + (bt709_tag_args(enc) if bt709 else [])))diff --git a/scripts/_common/emit.py b/scripts/_common/emit.pyindex 81baa9e..e67abe7 100644--- a/scripts/_common/emit.py+++ b/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 eithersys.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 fromsource = 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 _reif 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) -> Noif 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 Nonectx.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})diff --git a/scripts/_common/runner.py b/scripts/_common/runner.pyindex f4b99d5..0170482 100644--- a/scripts/_common/runner.py+++ b/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 --hwSTATE = 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[Contectx = ctx or STATEtail = "\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 Noneif 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_TIMEOUTtry: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):passdiff --git a/scripts/_contract.py b/scripts/_contract.pyindex d6da5d6..25180c7 100644--- a/scripts/_contract.py+++ b/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 detectionis 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/optionalcapabilities above ask: which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) thisffmpeg BUILD carries, from `-encoders` alone. No tool requires one -- every tool runs on CPUx264/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). Itonly proves the build shipped the capability, never that the GPU/driver on this machine willactually 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 | unknownwanted = required_capabilities()+ covered = _covered_by_videotoolbox(listings["encoders"])drawtext_probe: Optional[Dict[str, Any]] = Nonedrawtext_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 alreadycomputed. Answers "can I run this tool on this machine today", not just "what capabilitiesexist" -- 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) -> Dientry["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"] = viatools[name] = entryreturn 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)")diff --git a/scripts/export.py b/scripts/export.pyindex e8f996a..364fc6d 100755--- a/scripts/export.py+++ b/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 += videoif args.preset != "copy":diff --git a/tests/test_accel.py b/tests/test_accel.pyindex 7a10763..a94c865 100644--- a/tests/test_accel.py+++ b/tests/test_accel.py@@ -121,7 +121,8 @@ class FakeFfmpeg:runs a Python script with this interpreter, so the same fake works on every CI runner. Eachcall is logged; a command naming a *_videotoolbox encoder gets the `vt` behaviour, any otherthe `cpu` one: {"rc", "stderr"}, or {"real": "<ffmpeg path>"} to hand the command to a real- ffmpeg (the CPU encode then writes a real, probe-able file)."""+ ffmpeg (the CPU encode then writes a real, probe-able file); with "as_cpu" the VideoToolbox+ line is first rewritten to libx264 at CRF 23, so a "VideoToolbox" encode writes a real file."""def __init__(self, directory: Path, behaviour):self.dir = Path(directory)@@ -136,6 +137,12 @@ class FakeFfmpeg:f"with open({str(self.log)!r}, 'a', encoding='utf-8') as fh:\n"" fh.write(json.dumps(args) + '\\n')\n""do = conf['vt' if any(a.endswith('_videotoolbox') for a in args) else 'cpu']\n"+ "if do.get('as_cpu'):\n" # a VideoToolbox line the real (CPU) ffmpeg can run: libx264 at its CRF+ " args = [a.replace('h264_videotoolbox', 'libx264') for a in args]\n"+ " for i, a in enumerate(args):\n"+ " if a == '-q:v':\n"+ " args[i:i + 2] = ['-crf', '23']\n"+ " break\n""if 'real' in do:\n"" sys.exit(subprocess.run([do['real']] + args).returncode)\n""sys.stderr.write(do.get('stderr', ''))\n"@@ -539,6 +546,17 @@ class EncoderListTests(unittest.TestCase):tool, _names = self._read(dry_run=True)self.assertEqual(tool, "ffprobe")+ def test_the_read_ends_with_the_run_s_own_timeout(self):+ """On Apple Silicon every CPU re-encode asks for this list (#314): a deadlocked ffmpeg has to+ end at --timeout there, not at the 120 s probe ceiling (macOS CI: a silent shim, --timeout 1)."""+ for timeout, expected in ((1.0, 1.0), (0, runner.PROBE_TIMEOUT), (9999.0, runner.PROBE_TIMEOUT)):+ runner._ENCODERS = None+ STATE.timeout = timeout+ with mock.patch.object(runner.shutil, "which", side_effect=lambda name: os.path.join("bin", name)), \+ mock.patch.object(runner.subprocess, "run", return_value=subprocess.CompletedProcess([], 0, "", "")) as call:+ runner.ffmpeg_encoders()+ self.assertEqual(call.call_args[1]["timeout"], expected, f"--timeout {timeout}")+class _RealFfmpegCase(unittest.TestCase):"""A 1 s source made with the real ffmpeg, a work directory, and no GPU variables leaking in."""@@ -702,6 +720,182 @@ class HwEverywhereTests(_RealFfmpegCase):self.assertTrue(any(n.endswith("the CPU retry failed too") for n in doc["hw"]["notes"]), doc["hw"])+class NoCpuEncoderTests(_RealFfmpegCase):+ """#314: an ffmpeg build without libx264/libx265 (an LGPL build in a desktop app) encodes on+ VideoToolbox without --hw, where VideoToolbox can run; a build that has them is untouched. The+ platform check and the encoder list are stood in for, as in HwEverywhereTests."""++ VT_ONLY = {"h264_videotoolbox", "hevc_videotoolbox", "prores_videotoolbox", "aac", "prores_ks"}+ FULL = VT_ONLY | {"libx264", "libx265"}++ def _plan(self, module_name, *argv, encoders=None, reason=None, env=None):+ """A tool's --dry-run --json document with the build's encoder list and the platform check+ stood in; returns (document, the mock the encoder list was read through)."""+ import importlib+ module = importlib.import_module(module_name)+ out, err = io.StringIO(), io.StringIO()+ with mock.patch.object(decision, "hw_platform_reason", return_value=reason), \+ mock.patch.object(decision, "ffmpeg_encoders", return_value=set(self.VT_ONLY if encoders is None else encoders)) as listed, \+ mock.patch.dict(os.environ, env or {}), \+ mock.patch.object(sys, "argv", [module_name + ".py"] + [str(x) for x in argv] + ["--dry-run", "--json"]), \+ contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):+ STATE.reset()+ try:+ module.main()+ except SystemExit as e:+ self.assertEqual(e.code, 0, err.getvalue())+ return json.loads(out.getvalue()), listed++ def _fit(self, *extra, **kw):+ return self._plan("fit", self.src, "--height", "120", "-o", self.work / "f.mp4", *extra, **kw)++ def test_a_re_encoding_tool_uses_videotoolbox_when_the_build_has_no_libx264(self):+ doc, _ = self._fit()+ self.assertEqual(doc["encoder"], "h264_videotoolbox")+ self.assertNotIn("libx264", " ".join(doc["commands"]))+ self.assertIn("-q:v", doc["commands"][-1])+ self.assertEqual({k: doc["hw"][k] for k in ("requested", "source", "used", "fallback")},+ {"requested": False, "source": "auto", "used": None, "fallback": False}, "nobody asked; a dry run ran nothing")+ self.assertTrue(any("libx264 is not in this ffmpeg build" in n and "h264_videotoolbox" in n for n in doc["hw"]["notes"]), doc["hw"])+ quality = [n for n in doc["notes"] if "not CRF-equivalent" in n]+ self.assertEqual(len(quality), 1, doc.get("notes"))+ self.assertNotIn("--no-hw", quality[0], "the build has no CPU encoder, so --no-hw is no remedy")++ def test_libx265_is_replaced_by_hevc_videotoolbox_in_the_same_way(self):+ doc, _ = self._fit("--codec", "hevc")+ self.assertEqual(doc["encoder"], "hevc_videotoolbox")+ self.assertEqual(doc["hw"]["source"], "auto")+ self.assertTrue(any("libx265 is not in this ffmpeg build" in n for n in doc["hw"]["notes"]), doc["hw"])+ # x264 present, x265 absent: only the encoder the build lacks is replaced+ doc, _ = self._fit("--codec", "hevc", encoders=self.VT_ONLY | {"libx264"})+ self.assertEqual(doc["encoder"], "hevc_videotoolbox")+ doc, _ = self._fit(encoders=self.VT_ONLY | {"libx264"})+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)++ def test_a_build_with_libx264_is_untouched(self):+ doc, _ = self._fit(encoders=self.FULL)+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)+ self.assertFalse(any("videotoolbox" in c for c in doc["commands"]))+ self.assertFalse(any("CRF-equivalent" in n for n in doc.get("notes") or []))++ def test_export_presets_follow_the_build_without_libx264_or_libx265(self):+ """The delivery presets have no CPU alternative either: reels is x264, h265 is x265. The+ variable that keeps them on the CPU where there is one does not claim to have done so."""+ out = self.work / "x.mp4"+ for preset, encoder, cpu in (("reels", "h264_videotoolbox", "libx264"), ("youtube", "h264_videotoolbox", "libx264"),+ ("h265", "hevc_videotoolbox", "libx265")):+ with self.subTest(preset=preset):+ doc, _ = self._plan("export", self.src, "--preset", preset, "-o", out)+ self.assertEqual(doc["encoder"], encoder)+ self.assertNotIn(cpu, " ".join(doc["commands"]))+ self.assertIn("-q:v", doc["commands"][-1])+ self.assertNotIn(" -preset ", doc["commands"][-1], "x264's speed preset has no VideoToolbox meaning")+ self.assertEqual((doc["hw"]["requested"], doc["hw"]["source"]), (False, "auto"))+ self.assertTrue(any(f"{cpu} is not in this ffmpeg build" in n for n in doc["hw"]["notes"]), doc["hw"])+ with self.subTest(env=True):+ doc, _ = self._plan("export", self.src, "--preset", "reels", "-o", out, env={runner.HW_ENV: "1"})+ self.assertEqual(doc["encoder"], "h264_videotoolbox")+ self.assertEqual(doc["hw"]["source"], "auto")+ self.assertFalse(any("not applied" in n or "stays on the CPU" in n for n in doc["hw"]["notes"]), doc["hw"])+ with self.subTest(with_libx264=True):+ doc, _ = self._plan("export", self.src, "--preset", "reels", "-o", out, encoders=self.FULL)+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)++ def test_the_prores_and_copy_presets_are_not_touched(self):+ for preset, encoder in (("prores", "prores_ks"), ("copy", "copy")):+ with self.subTest(preset=preset):+ doc, _ = self._plan("export", self.src, "--preset", preset, "-o", self.work / f"{preset}.mov")+ self.assertEqual(doc["encoder"], encoder)+ self.assertNotIn("hw", doc)++ def test_an_explicit_no_hw_keeps_the_cpu_line(self):+ """--no-hw is the caller's choice of the CPU: honoured even where it cannot run (ffmpeg then+ says so), not overridden."""+ doc, _ = self._fit("--no-hw")+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)++ def test_an_explicit_hw_is_unchanged(self):+ doc, _ = self._fit("--hw")+ self.assertEqual((doc["encoder"], doc["hw"]["requested"], doc["hw"]["source"]), ("h264_videotoolbox", True, "flag"))+ self.assertFalse(any("is not in this ffmpeg build" in n for n in doc["hw"]["notes"]), "asked for, not chosen for lack of libx264")++ def test_without_videotoolbox_or_off_apple_silicon_nothing_changes(self):+ doc, _ = self._fit(encoders={"aac"})+ self.assertEqual(doc["encoder"], "libx264", "no VideoToolbox in the build either: the CPU line, which ffmpeg then refuses as today")+ self.assertNotIn("hw", doc)+ doc, listed = self._fit(reason="VideoToolbox is macOS-only")+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)+ listed.assert_not_called() # Linux and Windows never read the encoder list for this+ doc, _ = self._fit(reason="VideoToolbox constant-quality encoding needs Apple Silicon")+ self.assertEqual(doc["encoder"], "libx264")++ def test_an_unreadable_encoder_list_proves_nothing_is_missing(self):+ doc, _ = self._fit(encoders=set())+ self.assertEqual(doc["encoder"], "libx264")+ self.assertNotIn("hw", doc)++ def test_the_encode_runs_on_videotoolbox_and_is_reported_as_one(self):+ """The real run, with a fake ffmpeg that stands in for VideoToolbox by writing the file with+ libx264: `used` is true, nothing is retried (there is no CPU line to retry with)."""+ fake = FakeFfmpeg(self.work, {"vt": {"real": self.real_ffmpeg, "as_cpu": True}, "cpu": {"real": self.real_ffmpeg}})+ code, doc, _err = self._run_auto(fake)+ self.assertEqual(code, 0, doc)+ self.assertEqual(len(fake.calls()), 1)+ self.assertTrue(doc["verified"])+ self.assertEqual(doc["encoder"], "h264_videotoolbox")+ self.assertEqual({k: doc["hw"][k] for k in ("requested", "source", "used", "fallback")},+ {"requested": False, "source": "auto", "used": True, "fallback": False})+ self.assertTrue(any("not CRF-equivalent" in n and "--no-hw" not in n for n in doc["notes"]), doc.get("notes"))++ def test_a_refused_encode_is_not_retried_on_a_cpu_encoder_the_build_lacks(self):+ fake = FakeFfmpeg(self.work, {"vt": {"rc": 187, "stderr": VT_OPEN_FAILED["6.1"]}, "cpu": {"real": self.real_ffmpeg}})+ code, doc, _err = self._run_auto(fake)+ self.assertEqual(code, 1)+ self.assertEqual(len(fake.calls()), 1, "libx264 is not in the build: a CPU retry could not run")+ self.assertEqual(doc["error"]["kind"], "ffmpeg")+ self.assertEqual(doc["encoder"], "h264_videotoolbox")+ self.assertEqual((doc["hw"]["used"], doc["hw"]["fallback"], doc["hw"]["source"]), (True, False, "auto"))+ self.assertFalse(any("re-encoded on the CPU" in n for n in doc["hw"]["notes"]), doc["hw"])++ def _run_auto(self, fake):+ """What a re-encoding tool does on a build without libx264: video_args() picks the encoder+ (no --hw anywhere), one ffmpeg command, run(), emit()."""+ STATE.json = True+ with mock.patch.object(decision, "hw_platform_reason", return_value=None), \+ mock.patch.object(decision, "ffmpeg_encoders", return_value=set(self.VT_ONLY)):+ video = decision.video_args(_common.probe(str(self.src)), 23, "ultrafast")+ self.assertEqual(video[video.index("-c:v") + 1], "h264_videotoolbox")+ self.assertEqual(STATE.hw_swaps, [], "no CPU line was replaced, so none is remembered")+ out = self.work / "o.mp4"+ cmd = [str(fake.path), "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", str(self.src), "-t", "0.5"] + video + ["-an", str(out)]+ stdout, stderr = io.StringIO(), io.StringIO()+ with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):+ try:+ runner.run(cmd)+ emit_module.emit(str(out))+ code = 0+ except SystemExit as e:+ code = e.code+ return code, json.loads(stdout.getvalue()), stderr.getvalue()++ def test_a_stage_that_ran_on_videotoolbox_for_lack_of_libx264_does_not_offer_no_hw(self):+ """render.py/batch.py carry a stage's quality note: its source is auto, so --no-hw is not named."""+ stage = {"hw": {"requested": False, "source": "auto", "used": True, "fallback": False, "notes": []},+ "commands": ["ffmpeg -i a.mp4 -c:v h264_videotoolbox -q:v 75 b.mp4"]}+ STATE.reset()+ emit_module.absorb_stage_hw("fit", stage)+ self.assertEqual(STATE.hw_stages[0]["source"], "auto")+ self.assertIn("not CRF-equivalent", STATE.hw_stages[0]["quality_note"])+ self.assertNotIn("--no-hw", STATE.hw_stages[0]["quality_note"])+ report = emit_module.hw_report(STATE, "h264_videotoolbox")+ self.assertEqual((report["requested"], report["source"]), (False, "auto"))++class HwResultTests(unittest.TestCase):"""What a result says about a GPU encode (review of #304: two encoders, one quality scale)."""diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 4f2793a..e4a14ec 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -3114,6 +3114,58 @@ class DoctorDetectionTests(unittest.TestCase):for key in ("available", "missing", "missing_optional", "unknown", "detection", "detected_by"):self.assertIn(key, contract["capabilities"])+ def _doctor_listing(self, drop=(), platform_reason=None):+ """doctor() in this process over the real macOS encoder capture minus the `drop` names (the+ other listings are this machine's own), with the platform check stood in for."""+ from unittest import mock+ import _common.runner as runner+ names = [n for n in _contract._parse_ff_list("-encoders", (self.FIX / "ffmpeg_encoders_8.1.2_macos.txt").read_text()) if n not in drop]+ real = _contract._ff_listing++ def listing(binary, flag):+ if flag == "-encoders":+ return {"names": names, "status": "parsed", "detail": f"{len(names)} entries"}+ return real(binary, flag)+ with mock.patch.object(_contract, "_ff_listing", side_effect=listing), \+ mock.patch.object(runner, "hw_platform_reason", return_value=platform_reason):+ return _contract.doctor()++ def test_a_build_without_libx264_is_usable_where_videotoolbox_takes_its_place(self):+ """#314: libx264/libx265 absent but h264/hevc_videotoolbox present on Apple Silicon: the tools+ encode with VideoToolbox without --hw, so doctor does not call them unusable."""+ full = self._doctor_listing()+ self.assertEqual(full["covered_by"], {})+ self.assertIn("encoder:libx264", full["available"])+ self.assertFalse(any("encoder:libx264" in n for n in full.get("notes") or []))+ lean = self._doctor_listing(drop=("libx264", "libx265"))+ self.assertEqual(lean["covered_by"], {"encoder:libx264": "encoder:h264_videotoolbox", "encoder:libx265": "encoder:hevc_videotoolbox"})+ for cap in lean["covered_by"]:+ self.assertNotIn(cap, lean["available"], "it is not in the build")+ self.assertNotIn(cap, lean["missing"] + lean["missing_optional"], "and it blocks nothing")+ self.assertEqual(lean["ok"], full["ok"])+ self.assertEqual(lean["missing"], full["missing"])+ for tool in ("insert", "fit"):+ self.assertEqual(lean["tools"][tool]["usable"], "yes", tool)+ self.assertNotIn("missing", lean["tools"][tool])+ self.assertEqual(lean["tools"]["insert"]["covered_by"], {"encoder:libx264": "encoder:h264_videotoolbox"})+ self.assertNotIn("covered_by", lean["tools"]["probe"])+ self.assertTrue(any("encoder:libx264" in n and "h264_videotoolbox" in n for n in lean["notes"]), lean.get("notes"))+ # only the encoder the build lacks is covered+ self.assertEqual(self._doctor_listing(drop=("libx265",))["covered_by"], {"encoder:libx265": "encoder:hevc_videotoolbox"})++ def test_libx264_stays_required_without_videotoolbox_or_off_apple_silicon(self):+ for label, drop, reason in (("no VideoToolbox in the build", ("libx264", "libx265", "h264_videotoolbox", "hevc_videotoolbox"), None),+ ("not Apple Silicon", ("libx264", "libx265"), "VideoToolbox constant-quality encoding needs Apple Silicon"),+ ("not macOS", ("libx264", "libx265"), "VideoToolbox is macOS-only")):+ with self.subTest(label):+ d = self._doctor_listing(drop=drop, platform_reason=reason)+ self.assertEqual(d["covered_by"], {})+ self.assertIn("encoder:libx264", d["missing"])+ self.assertEqual(d["tools"]["insert"]["usable"], "no")+ self.assertIn("encoder:libx264", d["tools"]["insert"]["missing"])+ self.assertIn("libx264", d["tools"]["insert"]["fix"])+ self.assertFalse(d["ok"])+def test_gpu_encoders_are_reported_from_the_build_alone(self):"""gpu_encoders answers only "did this ffmpeg build ship the capability" -- never affects ok/usable."""# the real macOS capture carries VideoToolbox (h264/hevc), the Windows capture carries nvenc/qsv/amf/vaapi