ffmpeg-skill 2.5.1 → 2.7.0

package/scripts/_common/runner.py

@@ -155,7 +155,8 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
+    __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")
 
     def __init__(self) -> None:
         self.reset()
@@ -176,6 +177,13 @@ class Context:
         self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
         self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
         self.codec: Optional[str] = None             # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
+        self.hw = False                              # --hw / $FFMPEG_SKILL_HW: VideoToolbox encoders where they apply
+        self.hw_source: Optional[str] = None         # "flag" (--hw/--no-hw given) or "env" (FFMPEG_SKILL_HW), None = off by default
+        self.hw_notes: List[str] = []                # why an encode stayed on (or fell back to) the CPU, for the result document
+        self.hw_swaps: List[Tuple[List[str], List[str]]] = []  # (VideoToolbox args, the CPU args they replaced) for run()'s fallback
+        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
 
 
 STATE = Context()
@@ -206,6 +214,31 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
                        help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
         g.add_argument("--quality", type=int, default=ap._defaults["crf"], metavar="N",
                        help="encoder quality on the CRF scale (default %(default)s; lower = better; 18 visually lossless for x264/x265, up to 63 for av1); ignored by prores")
+    if (codec and "crf" in ap._defaults) or not codec:
+        _add_hw_flags(g, "encode on the GPU with Apple VideoToolbox (h264/hevc/prores; Apple Silicon only): several times faster, "
+                         "larger files at the same quality; falls back to the CPU encoder, reported, where it cannot apply"
+                         + ("" if codec else ". The only way to put a delivery preset on the GPU: $FFMPEG_SKILL_HW does not apply here"),
+                      "encode on the CPU (x264/x265/SVT-AV1/prores_ks) even when $FFMPEG_SKILL_HW=1")
+        ap.set_defaults(_hw_env=bool(codec))
+
+
+def _add_hw_flags(g: Any, hw_help: str, no_hw_help: str) -> None:
+    """--hw and --no-hw, each its own boolean (dests `hw` and `no_hw`). They are not one dest
+    with store_true/store_false: the contract's input_schema keeps one property per dest and the
+    MCP transport turns `true` into the flag, so a shared dest published --no-hw under the name
+    `hw` and an MCP `hw: true` ran on the CPU. hw_flag() reads the pair back as True/False/None."""
+    hw = g.add_mutually_exclusive_group()
+    hw.add_argument("--hw", action="store_true", help=hw_help)
+    hw.add_argument("--no-hw", action="store_true", help=no_hw_help)
+
+
+def hw_flag(args: "argparse.Namespace") -> Optional[bool]:
+    """--hw -> True, --no-hw -> False, neither (or a tool without the flags) -> None."""
+    if getattr(args, "hw", False):
+        return True
+    if getattr(args, "no_hw", False):
+        return False
+    return None
 
 
 def apply_common(args: "argparse.Namespace") -> None:
@@ -228,6 +261,25 @@ 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, []
+    flag = hw_flag(args)
+    if flag is not None:
+        STATE.hw, STATE.hw_source = bool(flag), "flag"
+        if getattr(args, "_hw_orchestrator", False):
+            # render.py / batch.py --hw|--no-hw: every stage they run inherits it as an explicit
+            # choice -- export.py's delivery presets included, which $FFMPEG_SKILL_HW never reaches
+            os.environ[HW_ENV] = "1" if flag else "0"
+            os.environ[HW_FORCED_ENV] = "1"
+    elif hasattr(args, "hw") and os.environ.get(HW_FORCED_ENV) == "1":
+        STATE.hw, STATE.hw_source = env_hw(), "flag"
+    elif hasattr(args, "hw") and getattr(args, "_hw_env", False) and env_hw():
+        STATE.hw, STATE.hw_source = True, "env"
+    else:
+        STATE.hw, STATE.hw_source = False, None
+        # export.py (a delivery preset decides the encoder): the machine default is not applied,
+        # and the result says so rather than leaving a caller to wonder why the GPU was not used
+        STATE.hw_env_ignored = (hasattr(args, "hw") and env_hw() and not getattr(args, "_hw_env", False)
+                                and not getattr(args, "_hw_orchestrator", False))
     quality = getattr(args, "quality", None)
     if quality is not None:
         top = 63 if STATE.codec == "av1" else 51
@@ -354,15 +406,48 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:
         pass
 
 
-def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
+def _fail(cmd: Sequence[str], returncode: int, stderr: str, ctx: "Optional[Context]" = None, retried: bool = False) -> None:
     # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
     # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
     # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
     # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
     # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
     # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
+    #
+    # `cmd` is the command that ran last: after run()'s GPU->CPU retry (`retried`), the CPU one.
+    # Under --hw / $FFMPEG_SKILL_HW the message names its video encoder and the document carries
+    # `encoder` and `hw`, because two encoders may have run and a caller must know whose stderr
+    # this is.
+    ctx = ctx or STATE
     tail = "\n".join(stderr.strip().splitlines()[-15:])
-    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
+    what, extra = str(cmd[0]), {}
+    enc = video_encoder_of(cmd) if ctx.hw else None
+    if enc:
+        on_gpu = enc.endswith("_videotoolbox")
+        why = videotoolbox_failure(stderr) if on_gpu else None
+        if not on_gpu and retried:
+            what += f" (video encoder {enc}, the CPU retry after VideoToolbox refused the job)"
+        elif on_gpu and why is None:
+            what += f" (video encoder {enc}; not retried on the CPU: ffmpeg reported no VideoToolbox error)"
+        else:
+            what += f" (video encoder {enc})"
+        report = hw_report(ctx, enc)
+        if on_gpu:
+            report["notes"].append(
+                "the VideoToolbox encode failed and was not retried on the CPU: " +
+                ("ffmpeg reported no encoder-open or compression-session error, so the cause is not the GPU (see the message)"
+                 if why is None else f"VideoToolbox refused it ({why}) and no CPU encoder line was recorded to retry with"))
+        extra = {"encoder": enc, "hw": report}
+    die(f"command failed ({returncode}): {what}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode, **extra)
+
+
+def video_encoder_of(cmd: Sequence[str]) -> Optional[str]:
+    """The video encoder an ffmpeg argv names last (-c:v / -vcodec / -codec:v), or None."""
+    enc = None
+    for i, a in enumerate(cmd[:-1]):
+        if a in ("-c:v", "-vcodec", "-codec:v"):
+            enc = str(cmd[i + 1])
+    return enc
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
@@ -621,6 +706,126 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
+HW_ENV = "FFMPEG_SKILL_HW"
+# set only by render.py/batch.py --hw/--no-hw for the stages they run: "the outer command chose
+# explicitly", so a child resolves $FFMPEG_SKILL_HW as a flag (export.py included), not a default
+HW_FORCED_ENV = "_FFMPEG_SKILL_HW_EXPLICIT"
+
+
+def add_hw_orchestrator_args(ap: "argparse.ArgumentParser") -> None:
+    """--hw / --no-hw on a tool that runs other tools (render.py, batch.py) and encodes nothing itself."""
+    _add_hw_flags(ap, "run every stage's encode on Apple VideoToolbox, the final delivery export included (Apple Silicon; "
+                      "falls back to the CPU, reported, where it cannot apply). Without it, $FFMPEG_SKILL_HW=1 still "
+                      "puts the intermediate stages on the GPU and leaves the delivery export on the CPU",
+                  "every stage on the CPU encoders, whatever $FFMPEG_SKILL_HW says")
+    ap.set_defaults(_hw_orchestrator=True)
+
+
+def env_hw() -> bool:
+    """$FFMPEG_SKILL_HW asks for VideoToolbox by default (1/true/yes/on); anything else is off."""
+    return os.environ.get(HW_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def hw_platform_reason() -> Optional[str]:
+    """None when this machine can take a VideoToolbox constant-quality encode, else why not.
+    `-q:v` on VideoToolbox is Apple-Silicon-only in FFmpeg: an Intel Mac lists the encoders but
+    rejects the quality setting, so the machine check is macOS AND Apple Silicon hardware."""
+    if platform.system() != "Darwin":
+        return "VideoToolbox is macOS-only"
+    if not apple_silicon():
+        return "VideoToolbox constant-quality encoding needs Apple Silicon"
+    return None
+
+
+_APPLE_SILICON: Optional[bool] = None
+
+
+def apple_silicon() -> bool:
+    """Whether this Mac's hardware is Apple Silicon -- not this interpreter's architecture: an
+    x86_64 Python under Rosetta reports platform.machine() "x86_64" on an M-series Mac, where
+    `sysctl -n hw.optional.arm64` still reads 1 (an Intel Mac has no such key). What decides -q:v
+    is the ffmpeg binary's own build; an x86_64 ffmpeg there refuses it, and run() re-encodes that
+    job on the CPU with ffmpeg's line in the note. Read once."""
+    global _APPLE_SILICON
+    if _APPLE_SILICON is None:
+        _APPLE_SILICON = platform.machine() == "arm64"
+        if not _APPLE_SILICON and platform.system() == "Darwin":
+            try:
+                out = subprocess.run([shutil.which("sysctl") or "/usr/sbin/sysctl", "-n", "hw.optional.arm64"],
+                                     stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8",
+                                     errors="replace", timeout=10).stdout
+                _APPLE_SILICON = out.strip() == "1"
+            except (OSError, subprocess.SubprocessError):
+                _APPLE_SILICON = False
+    return _APPLE_SILICON
+
+
+# What FFmpeg prints when a VideoToolbox encoder cannot take a job, read from the sources of 5.1,
+# 6.0, 6.1, 7.0, 7.1, 8.0 and master (fftools/ffmpeg*.c, libavcodec/videotoolboxenc.c):
+#  - the CLI's encoder-open failure, "Error while opening encoder", on every version. From 6.0 the
+#    line carries the output stream's log context, which names the encoder ("[vost#0:0/
+#    h264_videotoolbox @ 0x...]", from 8.0 followed by "[enc:h264_videotoolbox @ 0x...]"). 5.1
+#    prints "Error initializing output stream 0:0 -- Error while opening encoder for output stream
+#    #0:0 ...", which names no encoder, so there it counts only beside an error line the
+#    VideoToolbox encoder logged in its own context;
+#  - the encoder's own session failures, logged in its codec context ("[h264_videotoolbox @
+#    0x...]"): "cannot create compression session", "cannot prepare encoder", "cannot encode
+#    frame", "Error encoding frame". Each of them fails the encode. Matched without case and
+#    without the "Error: " prefix, which master drops ("Cannot create compression session").
+# Deliberately not counted, so the job is not run twice and the GPU is not blamed:
+#  - "Could not open encoder before EOF" (7.0+). It names the encoder, but it follows a filter
+#    graph that failed before the first frame -- a missing font, a bad filter argument -- so the
+#    encoder never got as far as opening;
+#  - the encoder's ERROR-level lines that do not fail the encode ("Error setting profile/level
+#    property ... Output will be encoded using a supported profile/level combination", the
+#    frames_before/frames_after/entropy/realtime/pixel-aspect properties), which a job that fails
+#    for another reason (a full disk: "Error submitting a packet to the muxer") can still carry.
+_VT_ENCODER_RE = re.compile(r"(?:h264|hevc|prores)_videotoolbox")
+_VT_OWN_CONTEXT_RE = re.compile(r"\[(?:h264|hevc|prores)_videotoolbox @ [^\]]*\]")
+_VT_SESSION_RE = re.compile(r"create compression session|prepare encoder|encode frame|encoding frame", re.I)
+# the encoder's own ERROR-level lines that do not fail the encode (listed above)
+_VT_NONFATAL_RE = re.compile(r"profile/level|entropy|frames_before|frames_after|realtime|pixel aspect|aspect ratio", re.I)
+_STREAM_CONTEXT_RE = re.compile(r"\[[a-z]ost#\d+:\d+")
+_ENCODER_OPEN_FAILED = "Error while opening encoder"
+
+
+def videotoolbox_failure(stderr: str) -> Optional[str]:
+    """The stderr line that shows a VideoToolbox encoder refused the job (could not open, or its
+    compression session failed), with the log contexts' pointers dropped; None when the failure
+    is something else. Only such a failure is retried on the CPU (see the notes above)."""
+    lines = [ln.strip() for ln in (stderr or "").splitlines() if ln.strip()]
+    own = [ln for ln in lines if _VT_OWN_CONTEXT_RE.search(ln)]
+    # the lines that can explain a refusal: not the non-fatal property errors, which a job that
+    # failed elsewhere (5.1: an audio encoder that could not open) still carries
+    fatal = [ln for ln in own if not _VT_NONFATAL_RE.search(ln)]
+    found = next((ln for ln in own if _VT_SESSION_RE.search(ln)), None)
+    if found is None:
+        for ln in lines:
+            if _ENCODER_OPEN_FAILED not in ln:
+                continue
+            if _VT_ENCODER_RE.search(ln):            # 6.0+: the line names the encoder that failed to open
+                found = fatal[-1] if fatal else ln
+                break
+            if fatal and not _STREAM_CONTEXT_RE.search(ln):  # 5.1: no encoder named; the encoder's own error line is
+                found = fatal[-1]
+                break
+    return re.sub(r" @ 0x[0-9a-fA-F]+", "", found)[:200] if found else None
+
+
+def _hw_fallback(cmd: List[str], ctx: "Context") -> Optional[List[str]]:
+    """`cmd` with every VideoToolbox encoder line this process built swapped back to the CPU line
+    it replaced, or None when it has none -- for run() when the GPU refused an encode."""
+    out, changed = list(cmd), False
+    for vt, cpu in ctx.hw_swaps:
+        n = len(vt)
+        for i in range(len(out) - n + 1):
+            if out[i:i + n] == vt:
+                out[i:i + n] = cpu
+                changed = True
+                break
+    return out if changed else None
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Optional[Context]" = None) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
@@ -648,19 +853,50 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         flush_drawtext_textfiles(cmd)
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
-        proc = _execute(exec_cmd)
-        if proc.returncode != 0 and is_ffmpeg:
-            retry = _odd_dimension_retry(exec_cmd, proc.stderr or "")
+        def even_retry(proc: subprocess.CompletedProcess, ran: List[str]) -> "Tuple[subprocess.CompletedProcess, List[str]]":
+            """An attempt that failed on odd dimensions, run again with an even scale: after the
+            first attempt, and after a GPU->CPU retry (VideoToolbox may refuse an odd-sized job
+            for another reason before x264 ever reports the size)."""
+            if proc.returncode == 0 or not is_ffmpeg:
+                return proc, ran
+            retry = _odd_dimension_retry(ran, proc.stderr or "")
             if retry is not None:
                 info("source has odd dimensions; scaling to even before encoding (yuv420p needs it)")
                 ctx.commands[-1] = _cmdline(retry[:-1] + [cmd[-1]])
-                proc = _execute(retry)
-            elif "not divisible by 2" in (proc.stderr or ""):
+                return _execute(retry), retry
+            if "not divisible by 2" in (proc.stderr or ""):
                 die("the source has odd dimensions (width or height not divisible by 2) and this tool's filter graph "
                     "cannot pad them itself; make them even first, e.g. fit.py --width/--height, then retry",
                     kind="input")
+            return proc, ran
+
+        # `tried` is the last command run: the CPU fallback swaps its encoder line in
+        proc, tried = even_retry(_execute(exec_cmd), exec_cmd)
+        retried = False
+        if proc.returncode != 0 and is_ffmpeg and ctx.hw_swaps:
+            cpu_cmd = _hw_fallback(tried, ctx)
+            if cpu_cmd is not None:
+                # Only a failure VideoToolbox itself reported is retried on the CPU: a bad filter
+                # graph, a missing font or a full disk would fail the same way twice and be
+                # reported as the GPU's fault (videotoolbox_failure() has the strings and why).
+                # A failure that is not one stays a failure of this command: with check=True,
+                # _fail() names it; with check=False the caller's own retry decides (a success
+                # after that must not carry a note about it).
+                why = videotoolbox_failure(proc.stderr or "")
+                if why is not None:
+                    reason = f"VideoToolbox refused the encode: {why}"
+                    info(reason + "; retrying on the CPU encoder")
+                    ctx.hw_notes.append(reason + "; re-encoded on the CPU")
+                    ctx.hw_fallback = True
+                    ctx.commands[-1] = _cmdline(cpu_cmd[:-1] + [cmd[-1]])
+                    if not quiet:
+                        # echoed like the first attempt, so a caller that reads the "$ " lines
+                        # (render.py's stages) records the command that really ran
+                        info("$ " + ctx.commands[-1], ctx=ctx)
+                    proc, tried = even_retry(_execute(cpu_cmd), cpu_cmd)
+                    retried = True
         if proc.returncode != 0 and check:
-            _fail(exec_cmd, proc.returncode, proc.stderr or "")
+            _fail(tried, proc.returncode, proc.stderr or "", ctx=ctx, retried=retried)
         if final and tmp:
             if proc.returncode == 0:
                 try:
@@ -1005,13 +1241,22 @@ def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
 
 
 def ffmpeg_encoders() -> set:
-    """Names from `ffmpeg -encoders`, read once; empty when ffmpeg is missing. Used only to pick
-    an AV1 encoder and to refuse --codec av1 / prores before ffmpeg would."""
+    """Names from `ffmpeg -encoders` -- the build that will run the encode -- read once; empty when
+    it cannot be read. Used to pick an AV1 encoder, to refuse --codec av1 / prores before ffmpeg
+    would, and to see whether --hw's VideoToolbox encoders are built in.
+
+    Under --dry-run only, the list comes from `ffprobe -encoders` instead: a dry run promises
+    never to run ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, as in
+    ffmpeg_version(). That is the one case for ffprobe. On a mixed install (a Homebrew ffprobe next
+    to a static ffmpeg) its list is another build's, so a real run never uses it: the AV1/ProRes
+    refusals and the VideoToolbox check must describe the binary that encodes, and a plan that
+    read ffprobe's list is re-decided against ffmpeg's when it runs."""
     global _ENCODERS
     if _ENCODERS is None:
         _ENCODERS = set()
+        tool = "ffprobe" if STATE.dry_run else "ffmpeg"
         try:
-            out = subprocess.run([shutil.which("ffmpeg") or "ffmpeg", "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
+            out = subprocess.run([shutil.which(tool) or tool, "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
                                  stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=PROBE_TIMEOUT).stdout
             _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
         except (OSError, subprocess.SubprocessError):
@@ -1043,4 +1288,4 @@ def read_text_or_die(path: str, flag: str) -> str:
 # emit needs runner's Context/STATE/ERROR_CODE, so the two form a cycle that has to be cut
 # somewhere: by the time this line runs every name emit reads from runner above is defined, and
 # every name runner reads from emit is only ever read inside a function body, never at import.
-from _common.emit import _plan_at_exit, die, info  # noqa: E402
+from _common.emit import _plan_at_exit, die, hw_report, info  # noqa: E402

package/scripts/_contract.py

@@ -54,6 +54,8 @@ ROLES = {
 #   filter:<name>               `ffmpeg -filters`
 #   bsf:<name>                  `ffmpeg -bsfs`
 #   external:whisper            a local whisper engine (whisper.cpp / faster-whisper / openai-whisper)
+#   external:parakeet           a local Parakeet engine (parakeet-mlx, or parakeet-cli with a .gguf model);
+#                               English. Either external engine satisfies --transcribe.
 # "optional" entries name the flag or condition under which the capability is needed.
 FF = ["ffmpeg", "ffprobe"]
 X264 = "encoder:libx264"
@@ -145,7 +147,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                       required=FF + [X264], optional=[],
                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "caption": dict(role="execution", inputs=["video asset", "SRT/ASS file or timed text (--text)"], outputs=["video artifact with burnt-in captions (--mode burn)", "video artifact with one or several language-tagged soft subtitle streams (--mode mux, --srt file:lang repeated)", "generated .srt / .ass sidecar"],
-                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"},
+                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"}, {"capability": "external:parakeet", "when": "--transcribe (English; either engine family satisfies it)"},
                                             {"capability": "encoder:mov_text", "when": "--mode mux with a .mp4/.m4v/.mov output"}, {"capability": "encoder:webvtt", "when": "--mode mux with a .webm output"}, {"capability": "encoder:srt", "when": "--mode mux with a .mkv output"}],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "overlay": dict(role="execution", inputs=["video asset", "image (--image / --logo), text (--text), or a second video (--video) to composite"], outputs=["video artifact with the overlay composited"],
@@ -172,7 +174,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
                     required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"},
-                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"}] + AUDIO_OUT,
+                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"},
+                                                                    {"capability": "external:parakeet", "when": "--filler --transcribe (English; either engine family satisfies it)"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
                  required=FF + ["filter:xfade", "filter:acrossfade"],
@@ -295,7 +298,8 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
 }
 
 IDEMPOTENCY = {
-    "bit_exact": "same inputs and flags give byte-identical output",
+    "bit_exact": "same inputs and flags give byte-identical output (with the CPU encoders: under --hw / $FFMPEG_SKILL_HW a "
+                 "VideoToolbox encode is content_equivalent at best)",
     "content_equivalent": "same inputs and flags give the same media content; bytes may differ between encoder builds",
     "cached": "re-runs skip inputs whose content hash and recipe are unchanged",
     "environment_dependent": "output includes timings or machine state and differs between runs",
@@ -348,7 +352,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     props: Dict[str, Any] = {}
     required: List[str] = []
     positional: List[str] = []
-    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite", "plan", "codec", "quality"}
+    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite", "plan", "codec", "quality", "hw", "no_hw"}
     for action in parser._actions:
         if isinstance(action, argparse._HelpAction):
             continue
@@ -371,6 +375,13 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
                 required.append(action.dest)
         if action.dest in common:
             prop["common"] = True
+        if action.dest in props:
+            # one property per dest: a second action (a store_false --no-x beside a store_true --x)
+            # would replace the first, and the contract and MCP would publish only the second flag
+            # under the first one's name -- an MCP `x: true` would then send --no-x
+            first = props[action.dest]["cli"]
+            raise RuntimeError(f"{parser.prog}: {'/'.join(action.option_strings) or action.dest} shares dest {action.dest!r} "
+                               f"with {'/'.join(first) if isinstance(first, list) else 'a positional'}; give each flag its own dest")
         props[action.dest] = prop
     groups = [g for g in getattr(parser, "_mutually_exclusive_groups", []) if g._group_actions]
     schema: Dict[str, Any] = {"type": "object", "properties": props, "required": required, "positional": positional, "additionalProperties": False}
@@ -380,8 +391,9 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     return schema
 
 
-def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
-    """What the tool prints on stdout with --json (keys observed in the implementation)."""
+def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str, Any]:
+    """What the tool prints on stdout with --json (keys observed in the implementation). `hw`: the
+    tool takes --hw, so its `notes` can also carry a VideoToolbox encode's quality line."""
     if name == "probe":
         return {"type": "object", "description": "one probe document, or an array of them for several inputs",
                 "properties": {"file": {"type": "string"}, "format": {"type": "string"}, "duration": {"type": "number"}, "size_bytes": {"type": "integer"},
@@ -389,6 +401,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
             "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"},
             "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)"}}
@@ -398,7 +412,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named: youtube was assumed and judgement rows are WARN"},
                  "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; audio FAILs when the track is present but silent (peak <= -50 dBFS)"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
     elif name == "caption":
-        extra = {"caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input"},
+        extra = {"transcription": {"type": "object", "description": "with --transcribe: {engine, model, language, routing (why auto chose it), detected_language when auto detected it}; when auto ran the English-only Parakeet model on English assumed, notes says so"},
+                 "caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input"},
                  "tracks": {"type": "array", "description": "--mode mux: one entry per subtitle stream in the output ({index, file, language, title, codec, default, cues, kept_from_input}); a stream the input already carried has file null and kept_from_input true (1.16)"},
                  "subtitle_tracks": {"type": "integer", "description": "--mode mux: how many subtitle streams the output carries"},
                  "emoji": {"type": "object", "description": "how the emoji in the text were drawn (mode, overlays, missing)"},
@@ -419,7 +434,9 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"}}
     elif name == "silence":
         extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
-                 "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"}}
+                 "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"},
+                 "filler": {"type": "object", "description": "--filler: {lang, source (whisper-json:FILE | whisper:ENGINE | parakeet:ENGINE), engine, transcription (with --transcribe: {engine, model, language, routing}), removed, removed_count, ...}"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--filler --transcribe under --engine auto: present when the English-only Parakeet model ran on English assumed (no --filler-lang, no language detected, no Whisper engine installed or none that succeeded); the transcript is wrong if the speech is not English"}}
     elif name == "sync":
         extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"},
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given"}}
@@ -481,6 +498,11 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
                  "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
     props = dict(base)
     props.update(extra)
+    notes = props.get("notes")
+    if hw and isinstance(notes, dict) and notes.get("description"):
+        # a tool-specific condition is not the only one: emit() adds the GPU line to any tool
+        props["notes"] = dict(notes, description=notes["description"] + "; also, on a VideoToolbox encode (--hw / "
+                              "$FFMPEG_SKILL_HW), a line that its quality is not CRF-equivalent (see hw)")
     required = ["status", "output", "dry_run", "commands"]
     return {"type": "object", "properties": props, "required": required, "additionalProperties": True}
 
@@ -656,6 +678,21 @@ def _whisper_available() -> bool:
     return importlib.util.find_spec("faster_whisper") is not None or importlib.util.find_spec("whisper") is not None
 
 
+def _parakeet_available() -> bool:
+    """parakeet-mlx on PATH, or parakeet-cli with a model it can find (PARAKEET_CPP_MODEL or a
+    .gguf in ~/.cache/parakeet.cpp) -- the same test the speech bridge applies before running it."""
+    from _common.asr import _parakeet_available as runtime_check  # the bridge's own test, not a copy of it
+    return any(runtime_check(e, shutil) for e in ("parakeet-mlx", "parakeet.cpp"))
+
+
+def _hw_default() -> Dict[str, Any]:
+    """--hw's machine facts, normalised (never the raw environment value): whether VideoToolbox
+    constant-quality encoding can run here (the tools' own check: Apple Silicon hardware, also
+    under a Rosetta Python), and whether $FFMPEG_SKILL_HW makes it the default."""
+    from _common.runner import env_hw, hw_platform_reason
+    return {"platform_ok": hw_platform_reason() is None, "default_on": env_hw()}
+
+
 def _default_font() -> str:
     from _common import BRAND_DEFAULTS
     return str(BRAND_DEFAULTS["font"])
@@ -846,6 +883,8 @@ def doctor() -> Dict[str, Any]:
             state[cap] = _from("bsfs", cap[4:])
         elif cap == "external:whisper":
             state[cap] = "available" if _whisper_available() else "missing"
+        elif cap == "external:parakeet":
+            state[cap] = "available" if _parakeet_available() else "missing"
         else:
             state[cap] = "missing"
     available = sorted(c for c, st in state.items() if st == "available")
@@ -872,6 +911,7 @@ def doctor() -> Dict[str, Any]:
         "ok": not missing_required and not unknown_required,
         "tools": _tool_usability(state),
         "gpu_encoders": _gpu_encoders(listings["encoders"]),
+        "hw": _hw_default(),
         "fonts": _fonts_capability(probe=True),
     }
 
@@ -972,7 +1012,15 @@ def _capability_fix_hint(cap: str) -> str:
         return (f"no installed font covers {LANGUAGE_NAMES.get(script, script)} text on this machine; "
                 f"{FONT_INSTALL_HINT} (doctor --json .fonts.scripts lists every script)")
     if cap == "external:whisper":
-        return "install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe"
+        return ("install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe; "
+                "faster-whisper and openai-whisper download their model on first use, and every engine transcribes "
+                "on this machine (the audio is never uploaded)")
+    if cap == "external:parakeet":
+        from _common.asr import PARAKEET_MLX_DEFAULT_MODEL
+        return ("for English --transcribe, install parakeet-mlx (uv tool install parakeet-mlx; its first run downloads "
+                f"{PARAKEET_MLX_DEFAULT_MODEL} from Hugging Face, then it transcribes on this machine and the audio is "
+                "never uploaded) or parakeet-cli with a tdt-0.6b-v2 .gguf in ~/.cache/parakeet.cpp; a local whisper "
+                "covers every language")
     return f"'{cap}' is not available; see docs/contract.md"
 
 
@@ -1101,7 +1149,7 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
         "inputs": list(meta["inputs"]),
         "outputs": list(meta["outputs"]),
         "input_schema": schema,
-        "output_schema": output_schema(name, meta),
+        "output_schema": output_schema(name, meta, hw="hw" in schema["properties"]),
         "supports_dry_run": supports_dry_run,
         "dry_run": {"supported": supports_dry_run,
                     "ffmpeg_execution": "full" if not supports_dry_run else "analysis_only" if name in DRY_RUN_ANALYSIS else "none",
@@ -1337,7 +1385,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
     version = skill_version()
     tools = [tool_spec(n, version) for n in public_tools()]
     wanted = required_capabilities()
-    caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper"}
+    caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper | external:parakeet"}
     if detect:
         d = doctor()
         caps.update({"available": d["available"], "missing": d["missing"], "missing_optional": d["missing_optional"],
@@ -1364,8 +1412,21 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
-            "subprocess": "argv list only: [python3, scripts/<tool>.py, ...] and [ffmpeg|ffprobe, ...] resolved from PATH",
+            "subprocess": "argv list only: [python3, scripts/<tool>.py, ...] and [ffmpeg|ffprobe, ...] resolved from PATH; "
+                          "with --transcribe, a local speech engine's CLI (whisper.cpp's whisper-cli / whisper-cpp / main, "
+                          "openai-whisper's whisper, parakeet-mlx, parakeet-cli) resolved from PATH",
             "network": False,
+            # `network` is about the skill's own code. A speech engine may fetch its model weights the
+            # first time it runs; faster-whisper is a library, so its fetch is made from the skill's own
+            # process. A caller that sandboxes the network must know that before a first --transcribe.
+            "model_downloads": {
+                "when": "first use of a speech engine (--transcribe) whose model is not cached yet; media is never uploaded",
+                "in_process": {"faster-whisper": "Hugging Face (Systran/faster-whisper-<model>)"},
+                "child_process": {"parakeet-mlx": "Hugging Face (mlx-community/parakeet-*)",
+                                  "openai-whisper": "OpenAI (its model checkpoint)"},
+                "none": ["whisper.cpp", "parakeet.cpp"],
+                "offline": "HF_HUB_OFFLINE=1 keeps faster-whisper and parakeet-mlx on the cached copy",
+            },
             "input_mutation": False,
         },
         "invocation": {