Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

feat: per-machine ASR model (FFMPEG_SKILL_ASR_MODEL) and silence.py --model (#330)

Shogo Kajiyama54727f976b1c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52436ca..812a0d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
## Unreleased
-(nothing yet)
+### Added
+
+- **A per-machine speech model, and `--model` on `silence.py --filler --transcribe` (#328).** `FFMPEG_SKILL_ASR_MODEL` is the model `caption.py --transcribe` and `silence.py --filler --transcribe` use when no `--model` is given (else `base`, as before), so a machine with `ggml-large-v3-turbo.bin` no longer needs `--model` on every call, and filler timing is no longer stuck on `base`. An explicit `--model` still wins and still goes to whichever engine runs. A Parakeet model in the variable (an `mlx-community/parakeet-*` repo or a `.gguf`) is offered to the Parakeet engines only and the Whisper engines keep `base`, so a machine default never makes auto's Whisper route for another language fail on a model it cannot load; a Whisper name leaves Parakeet routing and Parakeet's own model as they were. The result's `transcription.model` names the model that ran. `caption.py --model` no longer advertises a `base` default in its schema (it is resolved at run time); `silence.py`'s MCP schema gains `model`.
## 2.8.7
diff --git a/README.md b/README.md
index 609fc6e..3843f24 100644
--- a/README.md
+++ b/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
diff --git a/docs/contract.md b/docs/contract.md
index 3c4475a..ed19711 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -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
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index a7f1ce0..f113c7e 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -1095,6 +1095,20 @@ not a new file format this tool would have to maintain.
the run reads as "whisper.cpp found but failed" with the build's last output line and the next
engine is tried (`engine_failed` when whisper.cpp was named). Reverse this if a measurement on other material shows `-mc 0` costing more than the
loops it prevents. Test: `WhisperContextTests`.
+- **`FFMPEG_SKILL_ASR_MODEL` names a model for the engine that can load it; `--model` goes where it
+ is told.** The variable is this machine's default `--model` for `caption.py --transcribe` and
+ `silence.py --filler --transcribe` (#328). An explicit `--model` is one call's choice and goes to
+ whichever engine runs, as it did in 2.8.6. The variable applies to every call, including the
+ ones auto sends to Whisper for another language, so a Parakeet model there (an
+ `mlx-community/parakeet-*` repo or a `.gguf`) is offered to the Parakeet engines only and the
+ Whisper engines keep `base`; passed through as `--model` is, it would make every non-English
+ transcription on that machine fail on a model no Whisper engine loads. A Whisper name reaches the
+ Parakeet engines too, which pass over it for their own model, so it changes neither routing nor
+ Parakeet's model. The variable is not refused for a Parakeet name (`PARAKEET_MODEL` /
+ `PARAKEET_CPP_MODEL` remain the Parakeet engines' own setting, and `--model` beats them, so the
+ variable does too). `doctor` reports it no more than `FFMPEG_SKILL_ASR_ENGINE`: it prints no
+ environment values, and the result's `transcription.model` names the model that ran. Tests:
+ `ModelDefaultTests`, `test_the_machine_model_reaches_caption_and_silence`.
## Unreleased — cuts that say what they did
diff --git a/references/scripts.md b/references/scripts.md
index b020664..524915e 100644
--- a/references/scripts.md
+++ b/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
diff --git a/scripts/_common/asr.py b/scripts/_common/asr.py
index df4e148..067c592 100644
--- a/scripts/_common/asr.py
+++ b/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")
diff --git a/scripts/caption.py b/scripts/caption.py
index 70714b2..8ec26cf 100755
--- a/scripts/caption.py
+++ b/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)")
diff --git a/scripts/silence.py b/scripts/silence.py
index b9424e3..8f934d0 100755
--- a/scripts/silence.py
+++ b/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,
diff --git a/tests/_fixtures.py b/tests/_fixtures.py
index cfe5bfa..622937b 100644
--- a/tests/_fixtures.py
+++ b/tests/_fixtures.py
@@ -22,9 +22,10 @@ HERE = Path(__file__).resolve().parent
OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
# The host's own defaults must not reach the suite (every tool subprocess inherits os.environ):
-# FFMPEG_SKILL_ASR_ENGINE or a PARAKEET_* setting would change which speech engine a --transcribe
-# test drives, or where parakeet-mlx writes. Tests that exercise those opt in with an explicit env.
-for _k in ("FFMPEG_SKILL_ASR_ENGINE", "PARAKEET_MODEL", "PARAKEET_CPP_MODEL", "PARAKEET_OUTPUT_TEMPLATE"):
+# FFMPEG_SKILL_ASR_ENGINE, FFMPEG_SKILL_ASR_MODEL or a PARAKEET_* setting would change which speech
+# engine or model a --transcribe test drives, or where parakeet-mlx writes. Tests that exercise those
+# opt in with an explicit env.
+for _k in ("FFMPEG_SKILL_ASR_ENGINE", "FFMPEG_SKILL_ASR_MODEL", "PARAKEET_MODEL", "PARAKEET_CPP_MODEL", "PARAKEET_OUTPUT_TEMPLATE"):
os.environ.pop(_k, None)
sys.path.insert(0, str(SCRIPTS))
sys.path.insert(0, str(HERE))
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index c58ad25..117374b 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -1055,6 +1055,7 @@
"max_cuts",
"min_keep",
"min_silence",
+ "model",
"no_hw",
"output",
"overwrite",
diff --git a/tests/test_asr.py b/tests/test_asr.py
index 87843b3..b57fecc 100644
--- a/tests/test_asr.py
+++ b/tests/test_asr.py
@@ -260,8 +260,8 @@ class _BridgeHarness:
mock.patch.dict(sys.modules, {"faster_whisper": faster_whisper}),
# a host ggml model in ~/.cache/whisper.cpp must not change the model named below
mock.patch.object(asr, "_whisper_cpp_model", lambda m: m),
- mock.patch.dict(os.environ, dict({"PARAKEET_MODEL": "", "PARAKEET_CPP_MODEL": "", asr.ASR_ENGINE_ENV: ""},
- **(env or {})))]
+ mock.patch.dict(os.environ, dict({"PARAKEET_MODEL": "", "PARAKEET_CPP_MODEL": "", asr.ASR_ENGINE_ENV: "",
+ asr.ASR_MODEL_ENV: ""}, **(env or {})))]
for p in stack:
p.start()
try:
@@ -721,6 +721,78 @@ class AutoRoutingFallbackTests(_SrtDir, _BridgeHarness, unittest.TestCase):
self.assertNotIn("PARAKEET_OUTPUT_TEMPLATE", env)
+class ModelDefaultTests(_SrtDir, _BridgeHarness, unittest.TestCase):
+ """#328: caption.py --transcribe ran `base` unless every call passed --model, and silence.py
+ --filler --transcribe had no --model at all. $FFMPEG_SKILL_ASR_MODEL is this machine's default
+ for both; an explicit --model still wins."""
+
+ TURBO = {asr.ASR_MODEL_ENV: "large-v3-turbo"}
+ V3 = "mlx-community/parakeet-tdt-0.6b-v3"
+
+ @staticmethod
+ def _model(fake, exe="whisper-cli"):
+ argv = fake.ran(exe)[-1]
+ return argv[argv.index("-m" if exe == "whisper-cli" else "--model") + 1]
+
+ def _srt(self, model, env=None, engines=("whisper-cli",), language="en"):
+ fake = _FakeEngines(engines)
+ run = self._with([], lambda: asr.transcribe_result("talk.mp4", self.srt, language, model), fake=fake, env=env)
+ return run, fake
+
+ def _words(self, model, env=None, engines=("whisper-cli",), language="en"):
+ fake = _FakeEngines(engines)
+ run = self._with([], lambda: asr.transcribe_words_result("talk.mp4", language, model), fake=fake, env=env)
+ return run, fake
+
+ def test_precedence(self):
+ with mock.patch.dict(os.environ, {asr.ASR_MODEL_ENV: ""}):
+ self.assertEqual(asr.requested_model(None), ("base", "base"))
+ os.environ[asr.ASR_MODEL_ENV] = " large-v3-turbo "
+ self.assertEqual(asr.requested_model(None), ("large-v3-turbo", "large-v3-turbo"))
+ self.assertEqual(asr.requested_model("small"), ("small", "small"))
+ # a Parakeet model in the variable is offered to Parakeet only; the Whisper engines keep base
+ os.environ[asr.ASR_MODEL_ENV] = self.V3
+ self.assertEqual(asr.requested_model(None), ("base", self.V3))
+ # --model is one call's choice and goes to whichever engine runs, as before
+ self.assertEqual(asr.requested_model(self.V3), (self.V3, self.V3))
+
+ def test_the_environment_reaches_both_transcripts(self):
+ for transcribe in (self._srt, self._words):
+ run, fake = transcribe(None, env=self.TURBO)
+ self.assertEqual((self._model(fake), run.facts["model"]), ("large-v3-turbo", "large-v3-turbo"))
+
+ def test_an_explicit_model_wins(self):
+ for transcribe in (self._srt, self._words):
+ run, fake = transcribe("small", env=self.TURBO)
+ self.assertEqual(self._model(fake), "small")
+
+ def test_unset_keeps_base(self):
+ for transcribe in (self._srt, self._words):
+ run, fake = transcribe(None)
+ self.assertEqual(self._model(fake), "base")
+
+ def test_a_whisper_model_in_the_environment_leaves_parakeet_routing_alone(self):
+ """English still goes to Parakeet, which runs its own model, not the Whisper name."""
+ for transcribe in (self._srt, self._words):
+ run, fake = transcribe(None, env=self.TURBO, engines=("parakeet-mlx", "whisper-cli"))
+ self.assertEqual((run.engine, run.facts["routing"]), ("parakeet-mlx", "auto: --language is English"))
+ self.assertEqual(self._model(fake, "parakeet-mlx"), asr.PARAKEET_MLX_DEFAULT_MODEL)
+ self.assertEqual(fake.ran("whisper-cli"), [])
+
+ def test_a_parakeet_model_in_the_environment_never_reaches_whisper(self):
+ """English runs the variable's Parakeet model; French, which auto gives to Whisper, runs base
+ rather than a Parakeet name no Whisper engine can load."""
+ env = {asr.ASR_MODEL_ENV: self.V3}
+ for transcribe in (self._srt, self._words):
+ run, fake = transcribe(None, env=env, engines=("parakeet-mlx", "whisper-cli"))
+ self.assertEqual((run.engine, run.facts["model"]), ("parakeet-mlx", self.V3))
+ run, fake = transcribe(None, env=env, engines=("parakeet-mlx", "whisper-cli"), language="fr")
+ self.assertEqual((run.engine, self._model(fake)), ("whisper.cpp", "base"))
+ # the same name given with --model still goes to Whisper as given, as in 2.8.6
+ run, fake = self._srt(self.V3, engines=("parakeet-mlx", "whisper-cli"), language="fr")
+ self.assertEqual(self._model(fake), self.V3)
+
+
class InstallHintTests(unittest.TestCase):
"""Review of #305: parakeet-mlx fetches its default model from Hugging Face on first use. The
hints say so, and say the audio stays on the machine, so "no cloud" stays a true sentence."""
@@ -1048,6 +1120,36 @@ class ParakeetEngineTests(MediaFixtures):
self.assertEqual(fil["filler"]["transcription"]["routing"], asr.ROUTING_LAST_RESORT)
self.assertEqual(len(_assumed(fil)), 1, fil.get("notes"))
+ def test_the_machine_model_reaches_caption_and_silence(self):
+ """#328 through the real parsers: $FFMPEG_SKILL_ASR_MODEL is the model when no --model is given,
+ silence.py's new --model beats it, and English still goes to Parakeet with Parakeet's model."""
+ d, home = self._with_whisper_cli(fail=False)
+ args = home / "whisper-args.json"
+ turbo = home / ".cache" / "whisper.cpp" / "ggml-large-v3-turbo.bin"
+ turbo.write_bytes(b"")
+ try:
+ env = self.env(PATH=str(d), HOME=str(home), FFMPEG_SKILL_ASR_MODEL="large-v3-turbo")
+ doc = json.loads(script("caption.py", self.src, "--transcribe", "--language", "fr", "--mode", "mux", "--json",
+ "-o", OUT / "pk_envmodel.mp4", env=env).stdout)
+ caption_args = json.loads(args.read_text())
+ fil = json.loads(script("silence.py", self.src, "--filler", "--transcribe", "--filler-lang", "fr",
+ "--filler-list", "--json", env=env).stdout)
+ filler_args = json.loads(args.read_text())
+ script("silence.py", self.src, "--filler", "--transcribe", "--filler-lang", "fr", "--model", "small",
+ "--filler-list", "--json", env=env)
+ explicit_args = json.loads(args.read_text())
+ english = json.loads(script("caption.py", self.src, "--transcribe", "--language", "en", "--mode", "mux",
+ "--json", "-o", OUT / "pk_envmodel_en.mp4", env=env).stdout)
+ finally:
+ shutil.rmtree(d, ignore_errors=True)
+ shutil.rmtree(home, ignore_errors=True)
+ for argv in (caption_args, filler_args):
+ self.assertEqual(argv[argv.index("-m") + 1], str(turbo), argv)
+ self.assertEqual((doc["transcription"]["model"], fil["filler"]["transcription"]["model"]), (str(turbo), str(turbo)))
+ self.assertEqual(explicit_args[explicit_args.index("-m") + 1], "small")
+ self.assertEqual((english["transcription"]["engine"], english["transcription"]["model"]),
+ ("parakeet-mlx", asr.PARAKEET_MLX_DEFAULT_MODEL))
+
def test_caption_another_language_skips_parakeet(self):
"""Parakeet is installed and auto passes it over for French: the refusal says that, not
"no local speech-to-text engine found" with a line telling the caller to install it."""
diff --git a/tests/test_contract.py b/tests/test_contract.py
index e4a14ec..1429832 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -34,10 +34,11 @@ from _common.runner import HW_ENV, HW_FORCED_ENV # noqa: E402
for _k in (HW_ENV, HW_FORCED_ENV):
os.environ.pop(_k, None)
-# The host's own speech defaults must not reach the suite either: FFMPEG_SKILL_ASR_ENGINE or a
-# PARAKEET_* setting would change which speech engine a --transcribe test drives, or where
-# parakeet-mlx writes. Tests that exercise those opt in with an explicit env.
-for _k in ("FFMPEG_SKILL_ASR_ENGINE", "PARAKEET_MODEL", "PARAKEET_CPP_MODEL", "PARAKEET_OUTPUT_TEMPLATE"):
+# The host's own speech defaults must not reach the suite either: FFMPEG_SKILL_ASR_ENGINE,
+# FFMPEG_SKILL_ASR_MODEL or a PARAKEET_* setting would change which speech engine or model a
+# --transcribe test drives, or where parakeet-mlx writes. Tests that exercise those opt in with an
+# explicit env.
+for _k in ("FFMPEG_SKILL_ASR_ENGINE", "FFMPEG_SKILL_ASR_MODEL", "PARAKEET_MODEL", "PARAKEET_CPP_MODEL", "PARAKEET_OUTPUT_TEMPLATE"):
os.environ.pop(_k, None)
import _common # noqa: E402
import server as mcp_server # noqa: E402