ffmpeg-skill 2.8.7 → 2.9.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
 

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.9.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.9.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.9.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`
@@ -1025,12 +1025,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/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/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,