ffmpeg-skill 2.22.1 → 2.22.2

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.22.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.22.2`) | 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`
@@ -131,7 +131,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "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"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.22.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.22.2", "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; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.22.1",
+  "version": "2.22.2",
   "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

@@ -221,7 +221,9 @@ def transcribe_result(video: str, out_srt: str, language: Optional[str], model:
     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,
+        # the engines' own CLIs are looked up and launched by full path, never from the working directory
+        from _common.runner import SafeShutil
+        return _transcribe_in(tmpdir, video, out_srt, language, model, audio_stream, ffmpeg, SafeShutil(shutil), subprocess, wanted,
                               parakeet_model=parakeet_model)
     finally:
         shutil.rmtree(tmpdir, ignore_errors=True)
@@ -412,8 +414,9 @@ def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str
     except ImportError:
         pass
     # 3. openai-whisper CLI
-    if wanted in ("auto", "openai-whisper") and shutil.which("whisper"):
-        cmd = ["whisper", wav, "--model", model, "--output_format", "srt", "--output_dir", tmpdir]
+    whisper_exe = shutil.which("whisper") if wanted in ("auto", "openai-whisper") else None
+    if whisper_exe:
+        cmd = [whisper_exe, wav, "--model", model, "--output_format", "srt", "--output_dir", tmpdir]
         if lang:
             cmd += ["--language", lang]
         proc = _asr_run(cmd, subprocess, "openai-whisper")
@@ -924,7 +927,11 @@ def run_parakeet(engine: str, wav: str, tmpdir: str, model: Optional[str], langu
 
     if engine == "parakeet-mlx":
         outdir = os.path.join(tmpdir, "pmlx")
-        cmd = ["parakeet-mlx", wav, "--model", chosen, "--output-format", "json", "--output-dir", outdir,
+        exe = shutil.which("parakeet-mlx")
+        if not exe:  # never the bare name: the OS would look for it in the working directory
+            failed("not on PATH")
+            return None
+        cmd = [exe, wav, "--model", chosen, "--output-format", "json", "--output-dir", outdir,
                "--max-duration", f"{CUE_MAX_SECONDS:g}", "--silence-gap", f"{CUE_GAP_SECONDS:g}"]
         # the JSON is looked for as <outdir>/audio.json: a host PARAKEET_OUTPUT_TEMPLATE would name it otherwise
         env = {k: v for k, v in os.environ.items() if k != "PARAKEET_OUTPUT_TEMPLATE"}
@@ -939,7 +946,11 @@ def run_parakeet(engine: str, wav: str, tmpdir: str, model: Optional[str], langu
         except OSError:
             raw, key = "", "sentences"
     else:
-        cmd = ["parakeet-cli", "transcribe", "--model", chosen, "--input", wav, "--json"]
+        exe = shutil.which("parakeet-cli")
+        if not exe:
+            failed("not on PATH")
+            return None
+        cmd = [exe, "transcribe", "--model", chosen, "--input", wav, "--json"]
         proc = _asr_run(cmd, subprocess, "parakeet.cpp")
         if proc.returncode != 0:
             failed("found but failed: " + _failure_line(proc))
@@ -993,6 +1004,8 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     caller's flag for the language, named in assumed_english_note().
     """
     import shutil as _shutil
+    from _common.runner import SafeShutil
+    _shutil = SafeShutil(_shutil)  # look engines up and launch them by full path, never from the working directory
     import subprocess as _subprocess
     import tempfile as _tempfile
     from _common import require_tool, run_analysis, STATE
@@ -1098,8 +1111,9 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
             pass
 
         # 3. openai-whisper CLI
-        if (not failed or every_whisper) and wanted in ("auto", "openai-whisper") and _shutil.which("whisper"):
-            cmd = ["whisper", wav, "--model", model, "--word_timestamps", "True",
+        whisper_exe = _shutil.which("whisper") if (not failed or every_whisper) and wanted in ("auto", "openai-whisper") else None
+        if whisper_exe:
+            cmd = [whisper_exe, wav, "--model", model, "--word_timestamps", "True",
                    "--output_format", "json", "--output_dir", tmpdir]
             if lang:
                 cmd += ["--language", lang]

package/scripts/_common/drawtext.py

@@ -10,7 +10,7 @@ import shutil
 import subprocess
 from typing import Dict, List, Optional
 from _common.decision import escape_filter_path
-from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, ffmpeg_version
+from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, ffmpeg_version, require_tool
 
 
 def _on_windows() -> bool:
@@ -254,7 +254,7 @@ def drawtext_line_metrics(lines: "List[str]", font_opt: str, fontsize: int) -> "
                              f"y='print({-(1000 + i)},16)+print(text_w,16)+print(top_a,16)+print(bottom_d,16)+print(lh,16)'")
         if not chain:
             return out
-        cmd = [ffmpeg_exe("ffmpeg")[0] or "ffmpeg", "-hide_banner", "-nostdin", "-v", "error", "-f", "lavfi",
+        cmd = [require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "error", "-f", "lavfi",
                "-i", "color=c=black:s=16x16:r=1", "-frames:v", "1", "-vf", ",".join(chain), "-f", "null", "-"]
         try:
             flush_drawtext_textfiles(cmd)

package/scripts/_common/emoji.py

@@ -5,12 +5,12 @@ Split out of _common.text in the refactor after 1.17.3; every body is byte-ident
 from __future__ import annotations
 
 import os
-import shutil
 import subprocess
 from typing import Any, Dict, List, Tuple, Optional
 from _common.decision import escape_filter_path
 from _common.emit import die
 from _common.runner import ffmpeg_exe
+from _common.runner import safe_which as _safe_which
 
 
 # --------------------------------------------------------------------------- emoji (1.15)
@@ -183,7 +183,7 @@ _EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
 
 def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
     """(family, file, fontconfig_answered) for the first installed colour emoji family."""
-    exe = shutil.which("fc-list")
+    exe = _safe_which("fc-list")
     if not exe:
         return None, None, False
     for family in _EMOJI_COLOR_FAMILIES:

package/scripts/_common/fonts.py

@@ -7,12 +7,12 @@ from __future__ import annotations
 import os
 import platform
 import re
-import shutil
 import subprocess
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, info, record_fallback, warn
 from _common.emoji import _is_emoji_char
+from _common.runner import safe_which as _safe_which
 
 
 def default_font_file(font_name: str) -> Optional[str]:
@@ -79,7 +79,7 @@ def resolve_font(font_name: str) -> "Dict[str, object]":
             return {"file": str(candidate), "family": "Arial",
                     "substituted": bool(wanted) and wanted != "arial" and wanted not in _GENERIC_FAMILIES, "via": "windows_fonts"}
         return none
-    exe = shutil.which("fc-match")
+    exe = _safe_which("fc-match")
     if not exe:
         return none
     try:
@@ -220,7 +220,7 @@ def font_family_of_file(path: str) -> "Optional[str]":
     the file directly; without fontconfig the file stem is the honest best guess."""
     if not path or not os.path.isfile(path):
         return None
-    exe = shutil.which("fc-scan")
+    exe = _safe_which("fc-scan")
     if exe:
         try:
             proc = subprocess.run([exe, "--format", "%{family[0]}", path], stdout=subprocess.PIPE,
@@ -307,7 +307,7 @@ def _fc_list_fonts(fc_lang: str) -> "Optional[List[Tuple[str, List[str]]]]":
     asked at all (no `fc-list` on PATH, or it failed/timed out) -- the difference between
     "missing" and "unknown", which the caller must not collapse: unknown is not a refusal.
     """
-    exe = shutil.which("fc-list")
+    exe = _safe_which("fc-list")
     if not exe:
         return None
     try:
@@ -426,7 +426,7 @@ def font_covers_script(font_name: str, script: str) -> bool:
     """
     if script not in FC_LANG or not font_name:
         return True
-    exe = shutil.which("fc-list")
+    exe = _safe_which("fc-list")
     if not exe:
         return True
     try:
@@ -460,7 +460,7 @@ def fonts_dir_covers_script(fonts_dir: str, script: str) -> "Optional[bool]":
     """
     if script not in FC_LANG or not fonts_dir or not os.path.isdir(fonts_dir):
         return None
-    exe = shutil.which("fc-scan")
+    exe = _safe_which("fc-scan")
     if not exe:
         return None
     try:

package/scripts/_common/runner.py

@@ -118,7 +118,7 @@ def ffmpeg_version() -> "Tuple[int, int]":
     if _FFMPEG_VERSION is None:
         _FFMPEG_VERSION = (0, 0)
         try:
-            out = subprocess.run([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
+            out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
                                  timeout=PROBE_TIMEOUT).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
             if m:
@@ -155,7 +155,7 @@ def ffmpeg_release() -> "Optional[Tuple[int, int, int]]":
     if not _FFMPEG_RELEASE_READ:
         _FFMPEG_RELEASE_READ = True
         try:
-            out = subprocess.run([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
+            out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
                                  timeout=PROBE_TIMEOUT).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)(?:\.(\d+))?", out)
             if m:
@@ -187,21 +187,90 @@ def _homebrew_full_build(path: str, name: str) -> str:
     return full if os.path.isfile(full) and os.access(full, os.X_OK) else ""
 
 
+def _real_dir(path: str) -> str:
+    """`path` with symlinks resolved, so a PATH entry that links to the working directory is
+    recognised as the working directory."""
+    return os.path.normcase(os.path.realpath(path))
+
+
+def _cwd_on_path(entries: List[str]) -> bool:
+    cwd = _real_dir(os.getcwd())
+    return any(e and os.path.isabs(e) and _real_dir(e) == cwd for e in entries)
+
+
+def _which_on_path(name: str, entries: List[str]) -> Optional[str]:
+    """The first `name` in an absolute PATH entry that is not the working directory."""
+    cwd = _real_dir(os.getcwd())
+    exts = [""]
+    if os.name == "nt" and not os.path.splitext(name)[1]:
+        exts = [e for e in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(os.pathsep) if e] + [""]
+    for entry in entries:
+        if not entry or not os.path.isabs(entry) or _real_dir(entry) == cwd:
+            continue
+        for ext in exts:
+            candidate = os.path.join(entry, name + ext)
+            if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+                return candidate
+    return None
+
+
+def safe_which(name: str, which: Optional[Any] = None) -> Optional[str]:
+    """shutil.which() without the working directory. On Windows it looks in the current directory
+    before PATH (and so does a bare name handed to subprocess), and a `.` or relative PATH entry
+    does the same elsewhere: an `ffmpeg.exe` in a folder the skill is run from would run instead
+    of the real one. A hit there (or in a directory that links to it) is dropped and PATH searched
+    again, unless the working directory is on PATH as an absolute entry, which is the caller's own
+    choice. `which` lets a test pass
+    its own lookup."""
+    found = (which or shutil.which)(name)
+    if not found:
+        return found
+    entries = os.environ.get("PATH", "").split(os.pathsep)
+    if _real_dir(os.path.dirname(os.path.abspath(found))) != _real_dir(os.getcwd()):
+        return found
+    if _cwd_on_path(entries):
+        return os.path.abspath(found)  # Windows answers `.\ffmpeg.EXE`; a later chdir must not change what runs
+    return _which_on_path(name, entries)
+
+
+class SafeShutil:
+    """A shutil stand-in whose which() is safe_which(); the transcription code takes a `shutil`
+    argument (tests pass their own), so the real one is wrapped where it is handed in."""
+
+    def __init__(self, inner: Any) -> None:
+        self._inner = inner
+
+    def which(self, name: str) -> Optional[str]:
+        return safe_which(name, self._inner.which)
+
+    def __getattr__(self, attr: str) -> Any:
+        return getattr(self._inner, attr)
+
+
 def ffmpeg_exe(name: str) -> Tuple[str, str]:
     """`(path, source)` of the ffmpeg/ffprobe the tools run; `("", "")` when none is on PATH.
 
     `source` is "path" (what PATH resolves) or "homebrew-ffmpeg-full" (see _homebrew_full_build).
     Not cached: PATH is read every time, as `shutil.which` was before this existed."""
-    found = shutil.which(name)
+    found = safe_which(name)
     if not found:
         return "", ""
     full = _homebrew_full_build(found, name)
     return (full, "homebrew-ffmpeg-full") if full else (found, "path")
 
 
+def found_exe(name: str) -> str:
+    """ffmpeg_exe()'s path, or FileNotFoundError when there is none: never the bare name, which
+    the OS would look up in the working directory (Windows) or through a relative PATH entry."""
+    path = ffmpeg_exe(name)[0]
+    if not path:
+        raise FileNotFoundError(f"{name} not on PATH")
+    return path
+
+
 def require_tool(name: str) -> str:
     """Return the absolute path of ffmpeg/ffprobe or exit with install steps."""
-    path = ffmpeg_exe(name)[0] if name in ("ffmpeg", "ffprobe") else shutil.which(name)
+    path = ffmpeg_exe(name)[0] if name in ("ffmpeg", "ffprobe") else safe_which(name)
     if path:
         return path
     system = platform.system()
@@ -991,7 +1060,7 @@ def apple_silicon() -> bool:
         _APPLE_SILICON = platform.machine() == "arm64"
         if not _APPLE_SILICON and platform.system() == "Darwin":
             try:
-                out = subprocess.run([shutil.which("sysctl") or "/usr/sbin/sysctl", "-n", "hw.optional.arm64"],
+                out = subprocess.run([safe_which("sysctl") or "/usr/sbin/sysctl", "-n", "hw.optional.arm64"],
                                      stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8",
                                      errors="replace", timeout=10).stdout
                 _APPLE_SILICON = out.strip() == "1"
@@ -1603,7 +1672,7 @@ def _read_ff_list(flag: str, pattern: str) -> set:
     names: set = set()
     why = None
     try:
-        proc = subprocess.run([ffmpeg_exe(tool)[0] or tool, "-hide_banner", flag], stdout=subprocess.PIPE,
+        proc = subprocess.run([found_exe(tool), "-hide_banner", flag], stdout=subprocess.PIPE,
                               stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", timeout=limit)
         names = set(re.findall(pattern, proc.stdout or "", re.M))
         if not names:

package/scripts/_contract.py

@@ -1034,7 +1034,8 @@ def _exe_report() -> Dict[str, Any]:
 
 
 def _whisper_available() -> bool:
-    if shutil.which("whisper-cli") or shutil.which("whisper-cpp") or shutil.which("whisper"):
+    from _common.runner import safe_which
+    if safe_which("whisper-cli") or safe_which("whisper-cpp") or safe_which("whisper"):
         return True
     return importlib.util.find_spec("faster_whisper") is not None or importlib.util.find_spec("whisper") is not None
 
@@ -1043,7 +1044,8 @@ def _parakeet_available() -> bool:
     """parakeet-mlx on PATH, or parakeet-cli with a model it can find (PARAKEET_CPP_MODEL or a
     .gguf in ~/.cache/parakeet.cpp) -- the same test the speech bridge applies before running it."""
     from _common.asr import _parakeet_available as runtime_check  # the bridge's own test, not a copy of it
-    return any(runtime_check(e, shutil) for e in ("parakeet-mlx", "parakeet.cpp"))
+    from _common.runner import SafeShutil
+    return any(runtime_check(e, SafeShutil(shutil)) for e in ("parakeet-mlx", "parakeet.cpp"))
 
 
 def _hw_default() -> Dict[str, Any]:
@@ -1134,7 +1136,8 @@ def _font_available(font_name: str) -> Dict[str, Any]:
     silently renders with a different typeface. `fc-match` is queried instead, since it reports the
     family fontconfig actually resolved to; that only equals the request when the font is installed.
     """
-    exe = shutil.which("fc-match")
+    from _common.runner import safe_which
+    exe = safe_which("fc-match")
     if not exe:
         return {"status": "unknown", "detail": "fc-match not on PATH; drawtext succeeding proves nothing (fontconfig substitutes silently), so availability cannot be verified"}
     try:

package/scripts/color.py

@@ -23,7 +23,7 @@ import os
 import sys
 from typing import List, Optional
 
-from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, ffmpeg_exe, info, probe, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
@@ -256,7 +256,7 @@ def retag_mismatch(output: str, want: tuple) -> "Optional[str]":
     got = probe(output, role="output")["video"]
     stream = (got.get("color_space"), got.get("color_primaries"), got.get("color_transfer"))
     keys = ("color_space", "color_primaries", "color_transfer")
-    proc = run_analysis([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-v", "error", "-select_streams", "v:0", "-show_frames",
+    proc = run_analysis([require_tool("ffprobe"), "-v", "error", "-select_streams", "v:0", "-show_frames",
                          "-read_intervals", "%+#1", "-show_entries", "frame=" + ",".join(keys), "-of", "json", output],
                         check=False)
     try:

package/scripts/render.py

@@ -74,8 +74,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, ffmpeg_exe, X264_PRESETS
-from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args
+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, X264_PRESETS
+from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, found_exe
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 import subprocess
 from _contract import CONTRACT_VERSION
@@ -679,7 +679,7 @@ def ffmpeg_banner() -> str:
     key. Unreadable falls back to the parsed pair, which still separates the major releases.
     """
     try:
-        out = subprocess.run([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-version"], stdout=subprocess.PIPE,
+        out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE,
                              stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=20).stdout
         first = (out or "").strip().splitlines()
         if first: