ffmpeg-skill 2.8.7 → 2.10.0

package/README.md

@@ -82,7 +82,7 @@ An agent that "knows FFmpeg" still guesses: it assumes a frame rate, picks a cod
 - **Structured tools, not shell strings.** Each operation is a script with typed arguments. Nothing runs through a shell; no filter graph is accepted from the caller.
 - **A contract the agent can read.** `contract --json` states, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified. The MCP surface is derived from it.
 - **Verification after execution.** The result is probed, checked against the destination's spec and, when the picture changed, looked at as a contact sheet.
-- **Local first.** No cloud, no API keys, no Python dependencies. Optional local transcription is used when a speech engine (Parakeet or a whisper) is installed, never required — by `caption.py --transcribe` and, since 1.17, by `silence.py --filler --transcribe`; both take a transcript you already have instead, and both refuse with the install lines rather than guessing. The engine runs on your machine and the audio is never uploaded; parakeet-mlx, faster-whisper and openai-whisper download their model weights the first time they run (parakeet-mlx's default from Hugging Face).
+- **Local first.** No cloud, no API keys, no Python dependencies. Optional local transcription is used when a speech engine (Parakeet or a whisper) is installed, never required — by `caption.py --transcribe` and, since 1.17, by `silence.py --filler --transcribe`; both take a transcript you already have instead, and both refuse with the install lines rather than guessing. Both take `--engine` and `--model`; `FFMPEG_SKILL_ASR_ENGINE` and `FFMPEG_SKILL_ASR_MODEL` set this machine's defaults (e.g. `large-v3-turbo` where that whisper.cpp model is installed; without either, auto and `base`). The engine runs on your machine and the audio is never uploaded; parakeet-mlx, faster-whisper and openai-whisper download their model weights the first time they run (parakeet-mlx's default from Hugging Face).
 
 ## Quick start
 
@@ -257,7 +257,7 @@ These are the rules the skill file gives the agent and the code enforces.
 
 | Tool | What it does |
 |---|---|
-| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind |
+| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics and a picture-in-picture or chroma-keyed `video` layer sized for the final frame, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind |
 | `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch`; `--jobs N` processes several files at once under one shared `--timeout` |
 | `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list; `--switch energy` auto-cuts to whichever camera is loudest/talking instead of a hand-built list, with `--min-shot` (minimum shot length) and `--edl` (write a plain START-END cut list, not a CMX EDL; for Premiere/Resolve use `--write-project` then `render.py --export-timeline`) |
 | `verify.py` | Run the toolchain on real device files and report PASS / FAIL per step |

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.8.7`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.8.7", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -378,7 +378,11 @@ engine present. Whisper is never a dependency of this skill.
 `external:parakeet` is the same kind of optional capability for the same two flags:
 parakeet-mlx, or parakeet-cli with a `.gguf` model it can find. Either engine family
 satisfies `--transcribe`; `--engine auto` (the default, or `FFMPEG_SKILL_ASR_ENGINE`) runs
-Parakeet for English speech and Whisper for every other language. When no `--language` is given
+Parakeet for English speech and Whisper for every other language. `--model` (both tools) is the
+model; without it `FFMPEG_SKILL_ASR_MODEL` is this machine's default, else `base`. An explicit
+`--model` goes to whichever engine runs; a Parakeet model in the variable goes to the Parakeet
+engines only, and the Whisper engines keep `base`. `doctor` reports neither variable (it prints no
+environment values); the result's `transcription.model` names the model that ran. When no `--language` is given
 and no detector can name it, a Whisper engine that can run takes it (whisper.cpp is passed
 `-l auto`: its own default is English). Parakeet then runs only on English *assumed* -- when no
 Whisper engine is installed, or every one failed, or `--model` names an English-only Parakeet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.8.7",
+  "version": "2.10.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -558,7 +558,7 @@ silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-ke
 silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|es|de|fr|pt|it]
            [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02]
            [--transcribe] [--engine auto|parakeet-mlx|parakeet.cpp|whisper.cpp|faster-whisper|openai-whisper]
-           [--filler-list] [--max-cuts 400]
+           [--model MODEL] [--filler-list] [--max-cuts 400]
 ```
 Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
 gaps shorter than `--min-silence`, and re-encodes once with `select`/`aselect`
@@ -735,6 +735,23 @@ stem wins, and a stems level with no file to apply it to (`effects` without
 `"audio": {"voice": "light"|"medium"|"strong"}` picks the voice strength
 (`true` is `medium`).
 
+An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or
+`"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py
+--video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`,
+`platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to
+overlay.py's flags. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
+`"chromakey_blend"` key a colour out of the video layer. The stage runs after
+`fit`, so `"scale": 480` is 480 px of the delivered frame, and a template's
+safe margins apply as they do to a logo. Refused (`kind: input`) before the
+first stage: `video` together with `logo`/`image`/`text` in one entry (a
+logo, image and text together still draw the first of them, as before), a
+`chromakey*` key without `video`, `chromakey_similarity`/`_blend` without
+`chromakey`, and a layer file that does not exist (under `--dry-run` too: no
+earlier stage writes it). The layer's content is in the stage's `--cache`
+key, so replacing the file re-runs `overlays` and what follows it; paths are
+relative to the project file; `--export-timeline` lists the layer under
+`not_exported`.
+
 `"chapters"` is a chapters file path, or an inline list of `{"at": TIME,
 "title": STR}`; it runs `metadata.py` on the delivered file as the last stage
 before `check`, so the markers are in the file that ships (streams copied). The
@@ -1025,12 +1042,14 @@ missing one is `kind: missing_tool`; an installed one that fails is `kind: input
 engine_failed`, with its own error line in `detail`). Without a language whisper.cpp is passed
 `-l auto` (its own default is English), else the named or detected language, and `-mc 0` (no
 previous-text context, so one hallucinated line is not repeated to the end of the file; #318). `--model` is the
-whisper model; a Parakeet engine takes it only when it names a Parakeet model
+whisper model (default `FFMPEG_SKILL_ASR_MODEL`, this machine's default, else `base`); a Parakeet engine takes it only when it names a Parakeet model
 (`mlx-community/parakeet-*` or a `.gguf`), else `PARAKEET_MODEL` / `PARAKEET_CPP_MODEL`, else the
-English `tdt-0.6b-v2`. A non-English `--language` on an English-only Parakeet model is refused; a
+English `tdt-0.6b-v2`. A Parakeet model in `FFMPEG_SKILL_ASR_MODEL` goes to the Parakeet engines
+only (the Whisper engines keep `base`); one given with `--model` goes to whichever engine runs.
+A non-English `--language` on an English-only Parakeet model is refused; a
 multilingual (v3) model assumes no language, so it gets no English-assumed note. The result's
 `transcription` names the engine, model and routing. `silence.py --filler --transcribe` takes
-the same `--engine`.
+the same `--engine` and `--model`.
 Nothing is required: without an engine it prints install hints and the user can supply `--text`
 cues instead. When engines are installed but none transcribed, the refusal names each and why
 instead (`reason: engine_failed`, or `english_only` for a Parakeet engine auto passed over for

package/scripts/_common/asr.py

@@ -28,6 +28,9 @@ WHISPER_ENGINES = ("whisper.cpp", "faster-whisper", "openai-whisper")
 ASR_ENGINES = PARAKEET_ENGINES + WHISPER_ENGINES
 ENGINE_CHOICES = ("auto",) + ASR_ENGINES
 ASR_ENGINE_ENV = "FFMPEG_SKILL_ASR_ENGINE"
+# This machine's default --model (#328); --model wins, and without either the model is "base".
+ASR_MODEL_ENV = "FFMPEG_SKILL_ASR_MODEL"
+DEFAULT_WHISPER_MODEL = "base"
 # whisper.cpp conditions every window on the text before it, and once a hallucinated line is in that
 # context it can repeat it to the end of the file (#318: one sentence ~300 times, ~7 minutes of speech
 # lost). -mc / --max-context 0 keeps no previous text. Given to the commands that write a transcript,
@@ -200,10 +203,11 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
 
 
-def transcribe_result(video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int = 0,
+def transcribe_result(video: str, out_srt: str, language: Optional[str], model: Optional[str], audio_stream: int = 0,
                       engine: Optional[str] = None) -> Transcription:
     """Optional local ASR bridge: the SRT written to `out_srt`, and a Transcription saying what
-    produced it. `engine` (else $FFMPEG_SKILL_ASR_ENGINE, else auto) picks the engine; auto tries
+    produced it. `model` (else $FFMPEG_SKILL_ASR_MODEL, else base: requested_model()) is the
+    model; `engine` (else $FFMPEG_SKILL_ASR_ENGINE, else auto) picks the engine; auto tries
     Parakeet (parakeet-mlx, parakeet.cpp) for English speech, then whisper-cli / main
     (whisper.cpp), faster-whisper (python), whisper (openai-whisper CLI). No engine installed ->
     clear error with install hints; the skill never depends on one."""
@@ -213,14 +217,16 @@ def transcribe_result(video: str, out_srt: str, language: Optional[str], model:
     from _common import require_tool
     ffmpeg = require_tool("ffmpeg")
     wanted = requested_engine(engine)
+    model, parakeet_model = requested_model(model)
     tmpdir = tempfile.mkdtemp(prefix="ffskill_asr_")
     try:
-        return _transcribe_in(tmpdir, video, out_srt, language, model, audio_stream, ffmpeg, shutil, subprocess, wanted)
+        return _transcribe_in(tmpdir, video, out_srt, language, model, audio_stream, ffmpeg, shutil, subprocess, wanted,
+                              parakeet_model=parakeet_model)
     finally:
         shutil.rmtree(tmpdir, ignore_errors=True)
 
 
-def transcribe(video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int = 0,
+def transcribe(video: str, out_srt: str, language: Optional[str], model: Optional[str], audio_stream: int = 0,
                engine: Optional[str] = None) -> List[Tuple[float, float, str]]:
     """transcribe_result()'s cues alone: the call shape caption.transcribe has always had. A caller
     that reports which engine ran (caption.py does) calls transcribe_result() instead."""
@@ -304,8 +310,12 @@ def _skipped_parakeet(route: "Route", language: Optional[str], language_flag: st
 
 
 def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int,
-                   ffmpeg: str, shutil, subprocess, wanted: str = "auto") -> Transcription:
+                   ffmpeg: str, shutil, subprocess, wanted: str = "auto",
+                   parakeet_model: Optional[str] = None) -> Transcription:
+    """`model` is what the Whisper engines run; the Parakeet engines are offered `parakeet_model`
+    (default `model`), which differs only for a Parakeet model from $FFMPEG_SKILL_ASR_MODEL."""
     from _common import run_analysis, STATE
+    pmodel = model if parakeet_model is None else parakeet_model
     language = engine_language(language)
     wav = os.path.join(tmpdir, "audio.wav")
     # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
@@ -318,7 +328,7 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
     tried: "List[Dict[str, str]]" = []
 
     def parakeet(engines: "List[str]", facts: Dict[str, Any]) -> Optional[Transcription]:
-        done = _parakeet_attempt(engines, facts, wanted, language, wav, tmpdir, model, shutil, subprocess, video, "--language",
+        done = _parakeet_attempt(engines, facts, wanted, language, wav, tmpdir, pmodel, shutil, subprocess, video, "--language",
                                  tried=tried)
         if not done:
             return None
@@ -328,13 +338,13 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
         return run
 
     # 0. Parakeet (English), when auto-routing picks it or it was asked for by name
-    route = parakeet_route(wanted, language, wav, shutil, subprocess, model)
+    route = parakeet_route(wanted, language, wav, shutil, subprocess, pmodel, whisper_model=model)
     done = parakeet(route.first, route.facts)
     if done:
         return done
     tried.extend(_skipped_parakeet(route, language, "--language"))
     if wanted in PARAKEET_ENGINES:
-        die_engine_failed(wanted, video, tried, _parakeet_available(wanted, shutil, model))
+        die_engine_failed(wanted, video, tried, _parakeet_available(wanted, shutil, pmodel))
     facts = route.facts
     if route.first:
         # auto chose Parakeet and no Parakeet engine transcribed it: the routing says why Whisper ran
@@ -665,6 +675,25 @@ def requested_engine(engine: Optional[str]) -> str:
     return name
 
 
+def requested_model(model: Optional[str]) -> Tuple[str, str]:
+    """(the model the Whisper engines run, the model the Parakeet engines are offered): --model,
+    else $FFMPEG_SKILL_ASR_MODEL, else base.
+
+    --model is one call's choice and goes to whichever engine runs, as it always has. The
+    variable is this machine's default for every call, so it never hands an engine a model that
+    engine cannot load: a Parakeet model there (an mlx-community/parakeet-* repo or a .gguf) goes
+    to the Parakeet engines only, and the Whisper engines keep base. A Whisper name reaches the
+    Parakeet engines too, which pass over it for their own model, as they do for --model."""
+    if model:
+        return model, model
+    name = os.environ.get(ASR_MODEL_ENV, "").strip()
+    if not name:
+        return DEFAULT_WHISPER_MODEL, DEFAULT_WHISPER_MODEL
+    if _names_parakeet_model(name):
+        return DEFAULT_WHISPER_MODEL, name
+    return name, name
+
+
 def _is_english(language: Optional[str]) -> bool:
     # "eng" too: caption.py's --language is also the mux track tag, where ISO 639-2 is natural
     return (language or "").lower().split("-")[0].split("_")[0] in ("en", "eng", "english")
@@ -926,7 +955,7 @@ def _heard_nothing(text: str, key: str) -> bool:
     return isinstance(doc, dict) and doc.get(key) == []
 
 
-def transcribe_words(video: str, language: "Optional[str]" = None, model: str = "base",
+def transcribe_words(video: str, language: "Optional[str]" = None, model: "Optional[str]" = None,
                      audio_stream: int = 0, engine: "Optional[str]" = None) -> "Tuple[List[Dict[str, Any]], Optional[str]]":
     """transcribe_words_result()'s (words, engine) alone: the call shape this function has had
     since 1.17. A caller that reports which engine ran (silence.py does) calls
@@ -935,11 +964,12 @@ def transcribe_words(video: str, language: "Optional[str]" = None, model: str =
     return run.words, run.engine
 
 
-def transcribe_words_result(video: str, language: "Optional[str]" = None, model: str = "base",
+def transcribe_words_result(video: str, language: "Optional[str]" = None, model: "Optional[str]" = None,
                             audio_stream: int = 0, engine: "Optional[str]" = None,
                             language_flag: str = "--filler-lang") -> Transcription:
     """[{word, start, end}, ...] from a local speech engine, as a Transcription naming the engine.
 
+    `model` (else $FFMPEG_SKILL_ASR_MODEL, else base: requested_model()) is the model and
     `engine` (else $FFMPEG_SKILL_ASR_ENGINE, else auto) picks it; auto tries Parakeet for English
     speech first (parakeet-mlx sub-word tokens merged into words, parakeet.cpp `--json` words),
     then drives whichever whisper is installed with ITS word-timestamp option -- whisper.cpp
@@ -957,7 +987,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     ffmpeg = require_tool("ffmpeg")
     wanted = requested_engine(engine)
     language = engine_language(language)
-    parakeet_model = None if model == "base" else model
+    model, parakeet_model = requested_model(model)
     tmpdir = _tempfile.mkdtemp(prefix="ffskill_asrw_")
     try:
         wav = os.path.join(tmpdir, "audio.wav")

package/scripts/_common/timeline.py

@@ -39,7 +39,7 @@ _NOT_EXPORTED = {
     "silence": "the silence cut (render.py measures it at render time; the timeline keeps the clips whole)",
     "captions": "captions (burn them with render.py, or import the .srt into the editor)",
     "graphics": "graphics (titles, lower thirds, social templates)",
-    "overlays": "overlays (logos and text)",
+    "overlays": "overlays (logos, images, text and video layers)",
     "fit": "fit / reframe to the delivery aspect (set the sequence frame in the editor)",
     "audiogram": "the audiogram picture",
     "loudness": "loudness normalisation",

package/scripts/caption.py

@@ -916,9 +916,10 @@ 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="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("--model", default=None,
+                     help="speech model for --transcribe: a whisper model name/path (default: $FFMPEG_SKILL_ASR_MODEL, "
+                          "else 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)")

package/scripts/render.py

@@ -22,7 +22,8 @@ Project format (all keys optional except clips):
   ],
   "overlays": [
     {"logo": true},
-    {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}
+    {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true},
+    {"video": "webcam.mp4", "position": "bottom-right", "scale": 480, "chromakey": "0x00ff00"}
   ],
   "audio": {"voice": "medium", "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2,
             "effects": "sfx.wav", "stems": {"dialogue": 0, "music": -18, "effects": -22}},
@@ -37,6 +38,9 @@ Stages run in this order: clips (cut) → join → silence → fit → captions
 graphics → overlays → audio → loudness → export → chapters → check. Missing stages are
 skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
+An overlay entry draws one of logo, image, text or video (a picture-in-picture
+layer, overlay.py --video; "chromakey", "chromakey_similarity" and
+"chromakey_blend" key a colour out of that video and need "video").
 
 "check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.py
 itself failing to run) exits 1, same as running check.py directly would --
@@ -140,8 +144,10 @@ OBJECT_KEYS: Dict[str, frozenset] = {
     "graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position",
                              "from", "scale", "primary", "text_color", "lang",
                              "text", "top", "bottom", "duration", "margin", "platform"}),
+    # #326: "video" is a fourth layer kind (overlay.py --video), keyed with the chromakey* keys
     "overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity",
-                             "scale", "font_size", "font", "font_file", "margin", "box", "platform"}),
+                             "scale", "font_size", "font", "font_file", "margin", "box", "platform",
+                             "video", "chromakey", "chromakey_similarity", "chromakey_blend"}),
     "audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out",
                         "gain", "duck_amount", "duck_threshold", "duck_attack", "duck_release",
                         "voice", "denoise", "duck", "music_loop", "stereo", "mono", "downmix",
@@ -410,6 +416,28 @@ def check_keys(obj: Any, schema: str, label: str) -> None:
             else f" (valid keys: {', '.join(sorted(valid))})"))
 
 
+def check_overlay(ov: Any, label: str) -> None:
+    """#326: a video layer is one kind of overlay, as overlay.py's --image/--text/--logo/--video
+    are one mutually exclusive choice, and the chromakey* keys only act on it. A logo, image and
+    text in one entry still draw the first of them, as before; only a combination with the new
+    "video" key is refused, so no project 2.8.6 rendered is refused now."""
+    if not isinstance(ov, dict):
+        return
+    if ov.get("video"):
+        others = [k for k in ("logo", "image", "text") if ov.get(k)]
+        if others:
+            die(f"{label}: give one of logo, image, text or video per entry, not video and {others[0]} "
+                "(add a second overlays[] entry for the other layer)")
+    else:
+        keyed = [k for k in ("chromakey", "chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
+        if keyed:
+            die(f"{label}: {keyed[0]} keys a colour out of a video layer and needs \"video\" (overlay.py --chromakey needs --video)")
+    if ov.get("chromakey") is None:
+        tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
+        if tuned:
+            die(f"{label}: {tuned[0]} tunes \"chromakey\", which this entry does not set")
+
+
 def require_object(obj: Any, label: str) -> None:
     """Refuse a value that is not an object where the run reads it with .get(): "export": "reels"
     in a render, a string frame, a clip written as a bare path. 2.2.1 died there with a traceback
@@ -470,6 +498,8 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
                     die(f"{name}[{i}]: must be an object {{...}}, got {type(item).__name__} {item!r:.60}")
         for i, item in enumerate(items if isinstance(items, list) else []):
             check_keys(item, f"{name}[]", f"{name}[{i}]")
+            if name == "overlays":
+                check_overlay(item, f"overlays[{i}]")
             if name != "clips":
                 continue
             # every clip stage starts from rel(c["src"]): without one it was a KeyError traceback
@@ -954,6 +984,15 @@ def main() -> int:
     output = rel(proj.get("output") or "final.mp4")
     # the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
     refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
+    if _reaches("overlays", args.stop_after):
+        # #326: an overlay video is the caller's file, never an earlier stage's output, so a
+        # missing one is refused here, under --dry-run too, not after every stage before it ran
+        for i, ov in enumerate(proj.get("overlays") or []):
+            if ov.get("video"):
+                layer = rel(ov["video"])
+                refuse_output_is_input(output, layer)
+                if not os.path.isfile(layer):
+                    die(f"overlays[{i}].video: file not found: {layer}", kind="input")
     # 2.0 refuses an existing output without --overwrite; the final place_output() would, but
     # only after every stage had run -- say so before the first one instead
     _check_existing_output(["ffmpeg", output])
@@ -1248,9 +1287,13 @@ def main() -> int:
             argv += ["--image", rel(ov["image"])]
         elif ov.get("text"):
             argv += ["--text", ov["text"]]
+        elif ov.get("video"):
+            # #326: sized and placed here, after fit, against the frame that ships
+            argv += ["--video", rel(ov["video"])]
         else:
-            die(f"overlays[{i}] needs image or text")
-        for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform")):
+            die(f"overlays[{i}] needs logo, image, text or video")
+        for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform"),
+                        ("chromakey", "--chromakey"), ("chromakey_similarity", "--chromakey-similarity"), ("chromakey_blend", "--chromakey-blend")):
             if ov.get(k) is not None:
                 argv += [flag, str(ov[k])]
         if ov.get("box"):

package/scripts/silence.py

@@ -127,7 +127,7 @@ def resolve_filler(args, meta):
         # cannot answer this question: a cue has a start and an end, a word does not.
         # 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)
+                                               model=args.model, engine=args.engine)
         words, engine = asr_run.words, asr_run.engine
         transcription = dict(asr_run.facts)
         args._asr_notes = list(asr_run.notes)
@@ -277,6 +277,9 @@ def main() -> int:
     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("--model", default=None,
+                     help="speech model for --transcribe, as caption.py's: a whisper model name/path (default: "
+                          "$FFMPEG_SKILL_ASR_MODEL, else base), or a Parakeet model for the Parakeet engines")
     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,