ffmpeg-skill 2.5.1 → 2.7.0

package/scripts/batch.py

@@ -33,6 +33,8 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, read_text_or_die, MEDIA_EXT as _MEDIA_EXT
+from _common.runner import HW_FORCED_ENV, add_hw_orchestrator_args, env_hw
+from _common.emit import absorb_stage_hw, steps_encoder_report
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}  # one list (_common); a batch walks media, not stills
@@ -73,6 +75,18 @@ def recipe_key(recipe: Dict[str, Any]) -> str:
     return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode()).hexdigest()[:12]
 
 
+def gpu_key() -> str:
+    """The GPU setting the steps resolve, as a suffix for the item cache key: a VideoToolbox file is
+    not the CPU's bytes, so a --hw output is never served to a --no-hw run or the other way round
+    (render.py's cache_key folds the same two variables in). Read after apply_common(), which has
+    exported --hw/--no-hw to the steps. '' when every step encodes on the CPU -- no flag and no
+    $FFMPEG_SKILL_HW, or --no-hw -- so the keys of a cache written before --hw existed still hit."""
+    if not env_hw():
+        return ""
+    # the variable alone leaves export.py's delivery presets on the CPU; --hw puts them on the GPU
+    return ":hw" if os.environ.get(HW_FORCED_ENV) == "1" else ":hw-env"
+
+
 JOBS_CAP = 8   # beyond this, concurrent encodes contend for the same cores and memory
 
 _LOG = threading.local()
@@ -157,6 +171,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         pj = work / f"{src.stem}_project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
         ok, _doc = run_step(["render.py", str(pj)], budget())
+        step_docs = [("render", _doc)]
         cut_reencoded: List[bool] = []
     else:
         steps = recipe.get("steps") or []
@@ -165,11 +180,13 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         cur = str(src)
         ok = True
         cut_reencoded = []
+        step_docs = []
         for i, step in enumerate(steps):
             last = i == len(steps) - 1
             out = str(final) if last else str(work / f"{src.stem}_step{i}.{'mp4' if src.suffix.lower() not in ('.wav', '.mp3', '.m4a', '.flac') else src.suffix.lstrip('.')}")
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
             step_ok, doc = run_step(argv, budget())
+            step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
             # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut needed
             # the tolerance-triggered hybrid re-encode fallback (cut.py ORs its per-segment results
             # into one top-level field; it doesn't report which range, so this is per cut.py call,
@@ -183,6 +200,9 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
     result: Dict[str, Any] = {"file": str(src), "output": str(final), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if cut_reencoded:
         result["cut_reencoded"] = cut_reencoded
+    # the encoder each item really ran and its GPU facts (--hw / FFMPEG_SKILL_HW: on VideoToolbox,
+    # fell back and why): this process encodes nothing itself, so its top-level hw.used is null
+    result.update(steps_encoder_report(step_docs))
     return result
 
 
@@ -199,6 +219,7 @@ def main() -> int:
                          "Default 1, which is 1.16's behaviour exactly.")
     ap.add_argument("--work", help="work directory for intermediates (default: <output_dir>/.work)")
     add_common(ap)
+    add_hw_orchestrator_args(ap)
     args = ap.parse_args()
     apply_common(args)
 
@@ -240,7 +261,7 @@ def main() -> int:
             cache = json.loads(cache_path.read_text(encoding="utf-8"))
         except ValueError:
             cache = {}
-    rkey = recipe_key(recipe)
+    rkey = recipe_key(recipe) + gpu_key()
     glob = recipe.get("glob") or "*"
 
     # --jobs: every item is itself an ffmpeg that already threads across cores, so beyond a few
@@ -303,6 +324,10 @@ def main() -> int:
             # write is already atomic: two finishers could otherwise serialise from two different
             # snapshots and lose an entry.
             with cache_lock:
+                # this run just rewrote r["output"]: an entry under another key (another recipe,
+                # the other GPU setting) that names the same file now describes bytes that are gone
+                for stale in [k for k, v in cache.items() if k != key and isinstance(v, dict) and v.get("output") == r["output"]]:
+                    del cache[stale]
                 cache[key] = r
                 # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
                 # a concurrent manual run) could leave a truncated file that json.loads() above
@@ -507,6 +532,10 @@ def main() -> int:
                 results = one_pass()
         except KeyboardInterrupt:
             info("watch stopped")
+    # the items' GPU facts (asked for, fell back and why) reach the top-level `hw`, as render.py's
+    # stages' do; `used` stays null there, because this process encoded nothing itself
+    for r in results:
+        absorb_stage_hw(Path(r["file"]).name, r)
     done = sum(1 for r in results if r["ok"])
     info(f"{done}/{len(results)} processed, {sum(1 for r in results if r.get('cached'))} from cache")
     if not args.json:

package/scripts/caption.py

@@ -49,6 +49,8 @@ from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
 # caption.parse_srt / caption.transcribe / caption.whisper_word_timings before 1.17 still does.
+from _common import asr as _asr
+from _common.asr import ENGINE_CHOICES
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
@@ -901,7 +903,7 @@ def main() -> int:
                           "them; .mkv is the honest multi-track container and stores the code you give verbatim")
     src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
     src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
-    src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (whisper-cli / whisper / faster-whisper); never required")
+    src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (parakeet-mlx / parakeet.cpp / whisper-cli / whisper / faster-whisper); never required")
     src.add_argument("--language", "--lang", help="language code (e.g. en, ja, zh, ko): the language for --transcribe (default auto), "
                                                   "the tag on the subtitle stream with --mode mux, and the hint that says whether Han-only "
                                                   "text is Chinese, Japanese or Korean when a font is picked by script")
@@ -914,7 +916,12 @@ def main() -> int:
                           "(default: none, so no player burns in a language the viewer did not ask for)")
     src.add_argument("--offset", default="0", help="shift every cue by TIME (seconds, mm:ss, hh:mm:ss.ms or "
                                                     "hh:mm:ss:ff; a leading - shifts earlier); works for --text, --srt and --ass")
-    src.add_argument("--model", default="base", help="whisper model name/path for --transcribe (default base)")
+    src.add_argument("--model", default="base",
+                     help="speech model for --transcribe: a whisper model name/path (default base), or a Parakeet "
+                          "model (an mlx-community/parakeet-* repo or a .gguf) for the Parakeet engines")
+    src.add_argument("--engine", choices=ENGINE_CHOICES, default=None,
+                     help="speech engine for --transcribe (default: $FFMPEG_SKILL_ASR_ENGINE, else auto = Parakeet "
+                          "for English speech when installed, else whisper.cpp / faster-whisper / openai-whisper)")
     src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
     src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
     src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
@@ -1241,8 +1248,13 @@ def main() -> int:
             cues = []
             info(f"[dry-run] would transcribe {args.input} and write {srt_path}")
         else:
-            cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
-            args._word_timings = whisper_word_timings(srt_path)
+            # the call's own result, not module state: engine, routing and words belong to this run
+            asr_run = _asr.transcribe_result(args.input, srt_path, args.language, args.model, args.audio_stream,
+                                             engine=args.engine)
+            cues = asr_run.cues
+            args._asr = dict(asr_run.facts)
+            args._asr_notes = list(asr_run.notes)
+            args._word_timings = whisper_word_timings(srt_path) or sorted((w["start"], w["end"], w["word"]) for w in asr_run.words)
             cues, changed = lay_out(cues)
             if changed:
                 write_srt(cues, srt_path)
@@ -1279,7 +1291,8 @@ def main() -> int:
     # WRITING waits for a real run (the rule every side file in this tool follows), which is why
     # the cues are kept in hand below for the font sample and the ASS generator.
     planned_cues: Optional[List[Tuple[float, float, str]]] = None
-    side_notes: List[str] = []
+    # an English-only transcript made on an assumption says so first (asr.assumed_english_note)
+    side_notes: List[str] = list(getattr(args, "_asr_notes", None) or [])
     ass_sample_path = args.ass
     if args.srt and not (args.text or args.transcribe) and os.path.exists(srt_path or ""):
         adjusted, changed = lay_out(parse_srt(srt_path))
@@ -1416,7 +1429,8 @@ def main() -> int:
         result = probe(output, role="output")
         info(f"wrote {output} ({fmt_secs(result.get('duration'))}, mux, {len(added)} "
              f"subtitle track(s) added, codec {codec})")
-        emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}))
+        emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}),
+             **({"transcription": args._asr} if getattr(args, "_asr", None) else {}))
         return 0
 
     # A font that covers the text, before anything is rendered: non-Latin cues in a Latin-only
@@ -1582,6 +1596,8 @@ def main() -> int:
         info("caption text unchanged: the cues were burned exactly as given (line breaks, timing "
              "and type size only)")
     extra["caption"] = dict(caption_stats)
+    if getattr(args, "_asr", None):
+        extra["transcription"] = args._asr
     if emoji_plan:
         notes = list(extra.get("notes") or [])
         if emoji_plan["mode"] == "mono":

package/scripts/export.py

@@ -37,6 +37,7 @@ from pathlib import Path
 from typing import Dict, List
 
 from _common import STATE, add_common, apply_common, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common.decision import hw_preset_video, restate_last_swap
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
@@ -190,20 +191,28 @@ def main() -> int:
                              "veryfast" if STATE.fast else "medium", meta)
         # encoder_args() already applied --fast (its own preset scale per encoder: SVT-AV1 counts
         # 1..12, not x264's names) and appends +faststart, which this tool adds again for mp4
+        as_built = list(video)
         while "-movflags" in video:
             i = video.index("-movflags")
             del video[i:i + 2]
+        restate_last_swap(as_built, video)
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
     if STATE.fast and "-preset" in video and not p.get("codec"):
         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:
+        # --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
+        video = hw_preset_video(video, meta, bt709=tag_bt709)
     cmd += video
     if args.preset != "copy":
         # a stream copy can't be frame-rate-conformed or retagged without decoding it — that would
         # no longer be a copy, and would silently mislabel colour the agent never actually looked at
         if "-r" not in video:
             cmd += cfr_args(meta)
-        if args.preset not in ("prores",) and not p.get("codec"):
+        if tag_bt709 and not video[video.index("-c:v") + 1].endswith("_videotoolbox"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]

package/scripts/render.py

@@ -65,6 +65,8 @@ from typing import Any, Dict, List, Optional, Sequence
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
 from _common import STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args
+from _common.emit import absorb_stage_hw
 import subprocess
 from _contract import CONTRACT_VERSION
 from batch import file_key
@@ -354,6 +356,7 @@ def render_pack(names: List[str], args) -> int:
             if line.startswith("$ ") or line.startswith("[dry-run]"):
                 STATE.commands.append(line[2:] if line.startswith("$ ") else line)
         STATE.commands.extend(str(c) for c in (doc.get("commands") or []))
+        absorb_stage_hw(name, doc)
         out = doc.get("output") or dest_out
         chk = doc.get("check") or {}
         ok = proc.returncode == 0 and doc.get("status") == "completed"
@@ -541,16 +544,29 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
         # needs (a timeout inside audio.py is a timeout, not an "input" error of render.py).
         err = doc.get("error") or {}
         extra_fields = {"hint": err["hint"]} if err.get("hint") else {}
+        extra_fields.update(_stage_failure_hw(Path(script).stem, doc))
         die(f"{script} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
             code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script, **extra_fields)
     _LAST_DOC.clear()
     _LAST_DOC.update(doc if isinstance(doc, dict) else {})
+    absorb_stage_hw(Path(script).stem, doc)  # a stage's GPU facts (ran on VideoToolbox, fell back and why) reach this result
     out_path = str(doc.get("output") or "")
     if key:
         cache_store(stage, key, out_path or (dest or ""), time.time() - started)
     return out_path
 
 
+def _stage_failure_hw(stage: str, doc: Any) -> Dict[str, Any]:
+    """A failed stage's GPU facts, for render's own failure document: the stage's `hw` joins the
+    earlier stages' (a fallback before the failure is not lost), and its `encoder` -- the command
+    that failed -- is forwarded. die() then adds `hw` for a kind: ffmpeg failure, as a tool's own
+    run() failure carries it."""
+    if not isinstance(doc, dict):
+        return {}
+    absorb_stage_hw(stage, doc)
+    return {"encoder": doc["encoder"]} if doc.get("encoder") else {}
+
+
 # ------------------------------------------------------------------ the stage cache (1.17)
 #
 # Opt-in only: --cache DIR. There is no default directory -- a cache that appears on someone's
@@ -623,6 +639,10 @@ def cache_key(stage: str, script: str, argv: "Sequence[Any]", inputs: "Sequence[
         "inputs": [{"hash": _content_hash(p)} for p in inputs],
         "child": [a for a in child_args() if a != "--dry-run"],
         "codec": STATE.codec, "ext": Path(dest).suffix if dest else None,
+        # what a stage's encoder resolves from: $FFMPEG_SKILL_HW (inherited) and whether the outer
+        # command made it explicit (--hw/--no-hw, which reaches export.py too). A GPU encode is not
+        # the CPU's bytes, so a --hw artifact is never served to a CPU run or the other way round.
+        "hw": [os.environ.get(HW_ENV, "").strip().lower() in ("1", "true", "yes", "on"), os.environ.get(HW_FORCED_ENV) == "1"],
         "ffmpeg": CACHE.get("ffmpeg"), "skill": SKILL_VERSION, "contract": CONTRACT_VERSION,
     }
     return hashlib.sha1(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
@@ -724,7 +744,8 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     if proc.returncode != 0 or doc.get("status") != "completed":
         err = doc.get("error") or {}
         die(f"{tool} failed while executing the plan: {err.get('message') or proc.stderr.strip()[-300:]}",
-            kind=err.get("kind", "ffmpeg"), plan=path, tool=tool)
+            kind=err.get("kind", "ffmpeg"), plan=path, tool=tool, **_stage_failure_hw(tool, doc))
+    absorb_stage_hw(tool, doc)  # the tool's GPU facts (fell back and why, ran on VideoToolbox) reach this result
     output = doc.get("output") or plan.get("output")
     check_result = None
     exit_code = 0
@@ -863,6 +884,7 @@ def main() -> int:
                                             "or 'all' its directory is where the pack is written")
     tpl.add_argument("--write-project", metavar="FILE", help="write the filled project.json for editing and stop (no render)")
     add_common(ap)
+    add_hw_orchestrator_args(ap)
     args = ap.parse_args()
     apply_common(args)
 

package/scripts/silence.py

@@ -20,7 +20,8 @@ from typing import List, Tuple
 # `detect` moved into _common/probe.py in 1.16.0 so metadata.py --auto-chapters can measure the
 # same silences without importing this tool; the body is unchanged and the name still lives here.
 from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS,
-                     FILLER_PAD, transcribe_words, read_text_or_die)
+                     FILLER_PAD, read_text_or_die)
+from _common import asr as _asr
 from _common import detect_silences as detect, STATE, video_args, add_common, apply_common, audio_codec_for, cfr_args, default_output, die, emit, ffmpeg_base, info, is_audio_output, print_json, probe, run, X264_PRESETS, measured_level_dbfs, fmt_secs
 
 
@@ -99,7 +100,7 @@ def resolve_filler(args, meta):
         die("--filler needs word timings: pass --words transcript.json (a whisper JSON with word "
             "timestamps) or --transcribe. There is no way to find a filler word without them -- "
             "cutting the short quiet blips instead would remove real speech.", kind="input")
-    source, engine, raw = None, None, None
+    source, engine, raw, transcription = None, None, None, {}
     if args.words:
         try:
             raw = json.loads(read_text_or_die(args.words, "--words"))
@@ -118,14 +119,20 @@ def resolve_filler(args, meta):
                 '{"words": [{"word": ..., "start": ..., "end": ...}]} (or the same inside '
                 '"segments").', kind="input")
     else:
-        # No pre-check for an installed engine here: transcribe_words() probes for one and
+        # No pre-check for an installed engine here: transcribe_words_result() probes for one and
         # raises the same die_no_engine() refusal when there is none. Two places deciding "is
         # whisper here" is two places to disagree.
         # The engine is driven with ITS word-timestamp option (whisper.cpp --output-json-full,
         # faster-whisper word_timestamps=True, openai-whisper --word_timestamps True). An SRT
         # cannot answer this question: a cue has a start and an end, a word does not.
-        words, engine = transcribe_words(args.input, args.filler_lang if args.filler_lang != "auto" else None)
-        source = f"whisper:{engine}" if engine else "whisper"
+        # The call's own result, not module state: engine, routing and notes belong to this run.
+        asr_run = _asr.transcribe_words_result(args.input, args.filler_lang if args.filler_lang != "auto" else None,
+                                               engine=args.engine)
+        words, engine = asr_run.words, asr_run.engine
+        transcription = dict(asr_run.facts)
+        args._asr_notes = list(asr_run.notes)
+        family = "parakeet" if engine in _asr.PARAKEET_ENGINES else "whisper"
+        source = f"{family}:{engine}" if engine else "whisper"
         if not words:
             die(f"{engine or 'the local engine'} ran but produced no word-level timings, so there "
                 "is nothing for --filler to cut on. Some builds do not support word timestamps. "
@@ -168,6 +175,7 @@ def resolve_filler(args, meta):
                             "disfluency -- this will cut real sentences.")
     block = {
         "lang": lang, "source": source, "engine": engine,
+        **({"transcription": transcription} if engine and transcription else {}),
         "words": sorted(wordlist), "removed": [dict(s) for s in spans],
         "removed_count": len(spans),
         "removed_seconds": round(sum(s["end"] - s["start"] for s in spans), 3),
@@ -235,8 +243,11 @@ def main() -> int:
     fil.add_argument("--words", metavar="FILE",
                      help="a whisper JSON with word-level timings, for --filler")
     fil.add_argument("--transcribe", action="store_true",
-                     help="produce the word timings with a local whisper (never required; the same "
+                     help="produce the word timings with a local speech engine, Parakeet or whisper (never required; the same "
                           "bridge caption.py uses)")
+    fil.add_argument("--engine", choices=_asr.ENGINE_CHOICES, default=None,
+                     help="speech engine for --transcribe (default: $FFMPEG_SKILL_ASR_ENGINE, else auto = Parakeet "
+                          "for English speech when installed, else whisper)")
     fil.add_argument("--filler-list", action="store_true",
                      help="report what --filler would remove and write nothing")
     fil.add_argument("--max-cuts", type=int, default=400,
@@ -311,6 +322,10 @@ def main() -> int:
              f"({filler_info['lang']}, list {filler_info['list']})")
         for warning in filler_info.get("warnings") or []:
             info("warning: " + warning)
+    if getattr(args, "_asr_notes", None):
+        # an English-only transcript made on an assumption (asr.assumed_english_note): the
+        # bridge already logged the warning; the result document carries it at the top level
+        summary["notes"] = list(args._asr_notes)
     if len(keeps) > args.max_cuts:
         die(f"{len(keeps)} keep ranges is above --max-cuts {args.max_cuts}: the filter graph grows "
             "with every range and a graph this size is slow and fragile. Raise --max-cuts if you "

package/scripts/waveform.py

@@ -38,6 +38,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import (add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs)
+from _common.emit import absorb_stage_hw
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -307,20 +308,30 @@ def _child(script_name: str, argv: "list") -> None:
     """Run one of this skill's own tools as a second process, so the code path it owns (the ASS
     generator, the drawtext template) stays the only one there is. The shared flags (--overwrite,
     --timeout, --fast, --dry-run) reach it through child_args(), as render.py's stages get them,
-    and a failure is re-raised with the child's own kind, exit code and hint."""
+    and a failure is re-raised with the child's own kind, exit code and hint.
+
+    The GPU choice reaches it too: an explicit --hw/--no-hw is passed on (the child would
+    otherwise resolve $FFMPEG_SKILL_HW for itself, and the last stage writes the deliverable),
+    and the child's commands and `hw` facts join this result, so `encoder`/`hw` describe the
+    file delivered rather than the intermediate render."""
     here = os.path.dirname(os.path.abspath(__file__))
-    cmd = [os.path.join(here, script_name)] + [str(a) for a in argv] + child_args() + ["--json"]
+    hw = (["--hw"] if STATE.hw else ["--no-hw"]) if STATE.hw_source == "flag" else []
+    cmd = [os.path.join(here, script_name)] + [str(a) for a in argv] + hw + child_args() + ["--json"]
     info("-> " + " ".join(os.path.basename(c) if c.endswith(".py") else str(c) for c in cmd[:-1]))
     proc = run_tool(cmd)
+    try:
+        doc = json.loads(proc.stdout.strip() or "{}")
+    except ValueError:
+        doc = {}
+    if not isinstance(doc, dict):
+        doc = {}
+    STATE.commands.extend(str(c) for c in (doc.get("commands") or []))
+    absorb_stage_hw(os.path.splitext(script_name)[0], doc)
     if proc.returncode != 0:
-        try:
-            doc = json.loads(proc.stdout.strip() or "{}")
-        except ValueError:
-            doc = {}
-        if not isinstance(doc, dict):
-            doc = {}
         err = doc.get("error") or {}
         extra = {"hint": err["hint"]} if err.get("hint") else {}
+        if doc.get("encoder"):
+            extra["encoder"] = doc["encoder"]
         die(f"{script_name} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
             code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script_name, **extra)