ffmpeg-skill 3.1.0 → 3.1.1

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 (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.1.0`) | any release |
+| `skill.version` | the npm / package.json version (`3.1.1`) | 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`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.1.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.1.1", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "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/scripts/_common/asr.py

@@ -991,7 +991,7 @@ def transcribe_words(video: str, language: "Optional[str]" = None, model: "Optio
 
 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:
+                            language_flag: str = "--filler-lang", prompt: "Optional[str]" = None) -> 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
@@ -1003,7 +1003,10 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     when the engine ran but its build produced no word-level timings, so the caller can refuse
     naming that engine instead of pretending the audio had no words in it. No engine at all
     raises through die_no_engine(), the same refusal caption.py gives. `language_flag` is the
-    caller's flag for the language, named in assumed_english_note().
+    caller's flag for the language, named in assumed_english_note(). `prompt` is passed to a
+    Whisper engine as its initial prompt (whisper.cpp --prompt, faster-whisper initial_prompt,
+    openai-whisper --initial_prompt): Whisper writes clean text and leaves out "uh"/"um" unless
+    the context shows it that they are wanted, so silence.py --filler primes it with its own list.
     """
     import shutil as _shutil
     from _common.runner import SafeShutil
@@ -1058,7 +1061,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             base = os.path.join(tmpdir, "out")
             # whisper.cpp's own default is -l en: without "auto" it decodes any speech as English
             cmd = [cli, "-m", model_path, "-f", wav, "--output-json-full", "-of", base, "-l", lang or "auto",
-                   *WHISPER_CPP_NO_CONTEXT]
+                   *WHISPER_CPP_NO_CONTEXT] + (["--prompt", prompt] if prompt else [])
             proc = _asr_run(cmd, _subprocess, "whisper.cpp")
             if proc.returncode == 0 and os.path.exists(base + ".json"):
                 words = _words_from_whisper_cpp_json(base + ".json")
@@ -1084,7 +1087,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             def work() -> None:
                 try:
                     m = WhisperModel(model, device="cpu", compute_type="int8")
-                    segments, decoded = m.transcribe(wav, language=lang, word_timestamps=True)
+                    segments, decoded = m.transcribe(wav, language=lang, word_timestamps=True,
+                                                     **({"initial_prompt": prompt} if prompt else {}))
                     heard.append(getattr(decoded, "language", None))
                     for seg in segments:
                         for w in (getattr(seg, "words", None) or []):
@@ -1119,6 +1123,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
                    "--output_format", "json", "--output_dir", tmpdir]
             if lang:
                 cmd += ["--language", lang]
+            if prompt:
+                cmd += ["--initial_prompt", prompt]
             proc = _asr_run(cmd, _subprocess, "openai-whisper")
             doc = os.path.join(tmpdir, "audio.json")
             if proc.returncode == 0 and os.path.exists(doc):

package/scripts/silence.py

@@ -246,8 +246,12 @@ def resolve_filler(args, meta):
         # 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.
         # The call's own result, not module state: engine, routing and notes belong to this run.
+        # Whisper leaves "uh"/"um" out of its text unless the context shows them: prime it with the
+        # filler list of the language asked for (English under auto, where most filler cuts are)
+        primer = FILLER_WORDS.get(args.filler_lang if args.filler_lang != "auto" else "en") or []
+        prompt = (", ".join(sorted(primer)[:8]).capitalize() + ". So, I mean...") if primer else None
         asr_run = _asr.transcribe_words_result(args.input, args.filler_lang if args.filler_lang != "auto" else None,
-                                               model=args.model, engine=args.engine)
+                                               model=args.model, engine=args.engine, prompt=prompt)
         words, engine = asr_run.words, asr_run.engine
         transcription = dict(asr_run.facts)
         args._asr_notes = list(asr_run.notes)