ffmpeg-skill 1.4.9 → 1.4.11

package/README.md

@@ -293,7 +293,7 @@ The contract is generated from the code that runs, not maintained beside it. For
 | `mutates_input` | always `false` |
 | `idempotency_hint` | `bit_exact`, `content_equivalent`, `cached` or `environment_dependent` |
 
-`contract_version` (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure (`{"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification", "message": …}}`), and that no tool runs a shell or executes anything other than the named script, `ffmpeg` and `ffprobe`. Field-by-field reference: [docs/contract.md](docs/contract.md).
+`contract_version` (1.0) is separate from the skill version, so a consumer can pin the shape and read the version for provenance. The document also states the invocation mapping (structured arguments → argv), the JSON shapes for success and failure (`{"status": "failed", "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification | interrupted", "message": …}}`), and that no tool runs a shell or executes anything other than the named script, `ffmpeg` and `ffprobe`. Field-by-field reference: [docs/contract.md](docs/contract.md).
 
 ### MCP
 

package/SKILL.md

@@ -265,7 +265,7 @@ Notes: send a valid .cube, or say if you want the clip left as is
 
 A refusal (the request asks for a judgement this skill does not make, or for something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run (usually only probe), `Look: not needed`. Both keep the five labels so a reader can scan a failed report the way they scan a successful one. When a tool's failure JSON carries `error.hint`, quote it in `Notes:` — it is the flag change that would make the retry meaningful.
 
-Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
+Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, do not paraphrase it into a success.
 
 ## Things that look right but are wrong
 

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 (`1.4.9`) | any release |
+| `skill.version` | the npm / package.json version (`1.4.11`) | 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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.4.9", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.4.11", "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"},
@@ -309,7 +309,7 @@ before, and, when `--json` was given, on stdout:
 
 ```json
 {"status": "failed", "exit_code": 1,
- "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification", "message": "...",
+ "error": {"kind": "input | ffmpeg | output | missing_tool | timeout | verification | interrupted", "message": "...",
            "code": "INPUT_INVALID | DEPENDENCY_MISSING | FFMPEG_EXECUTION_FAILED | OUTPUT_INVALID | TIMEOUT | VERIFICATION_FAILED | INTERNAL_ERROR",
            "retryable": false},
  "commands": ["ffmpeg ..."]}

package/package.json

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

@@ -596,6 +596,13 @@ loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
 Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
 the true-peak ceiling allows). Video is stream-copied; audio becomes AAC in
 video containers or the codec matching the extension (.wav → PCM, .flac, .mp3).
+The written file is measured again: a lossy encoder can push peaks past the
+ceiling loudnorm held (ffmpeg's AAC at 192k turned one transient from -2.4 to
++3.7 dBFS). When it does, the tool re-encodes -- first at 256k then 320k if you
+did not pass `--audio-bitrate`, then with the loudnorm ceiling lowered by the
+overshoot -- until the file itself meets `--tp`. `result` reports
+`tp_ceiling_used`, `audio_bitrate_used`, `encodes`, and a `note` when the
+integrated loudness ended more than 1 LU from the target because of it.
 
 ### export.py — delivery presets
 ```

package/scripts/_common.py

@@ -64,6 +64,7 @@ ERROR_CODE = {
     "output": "OUTPUT_INVALID",
     "timeout": "TIMEOUT",
     "verification": "VERIFICATION_FAILED",
+    "interrupted": "INTERRUPTED",
 }
 
 # Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
@@ -263,6 +264,66 @@ def apply_common(args: "argparse.Namespace") -> None:
     crf = getattr(args, "crf", None)
     if crf is not None and not 0 <= int(crf) <= 51:
         die(f"--crf must be between 0 and 51 (x264/x265 scale; 18 is visually lossless, 23 the encoder default), got {crf}")
+    install_signal_handlers()
+
+
+# The child processes this tool is waiting on right now (an ffmpeg, or a sibling script under
+# run_tool), with the command whose partial output would need removing. A signal handler
+# reads it; the runners keep it current. Before 1.4.9 a SIGTERM to the tool (a cancelled MCP
+# call, a supervisor's stop, a closed terminal) killed only the Python parent: ffmpeg carried on
+# as an orphan, finished a file nobody verified, and the caller got no JSON at all; SIGINT was a
+# KeyboardInterrupt traceback with the partial left on disk.
+_CHILDREN: List[Tuple[subprocess.Popen, Sequence[str]]] = []
+_SIGNALS_INSTALLED = False
+
+
+def _on_signal(signum: int, frame: Any) -> None:
+    import signal as _signal
+    name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
+    for proc, cmd in list(_CHILDREN):
+        try:
+            proc.terminate()  # ffmpeg exits promptly on SIGTERM; a sibling script runs this same handler
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+        except OSError:
+            pass
+        if cmd:
+            _cleanup_partial_output(cmd)
+    _CHILDREN.clear()
+    die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
+        code=128 + signum, kind="interrupted")
+
+
+def install_signal_handlers() -> None:
+    """SIGINT/SIGTERM stop the child, remove its partial output and exit with a failure document
+    (kind: interrupted, exit 130/143). Main thread only; on Windows SIGTERM is never delivered,
+    SIGINT (Ctrl-C) is."""
+    global _SIGNALS_INSTALLED
+    if _SIGNALS_INSTALLED:
+        return
+    import signal as _signal
+    import threading
+    if threading.current_thread() is not threading.main_thread():
+        return
+    for sig in (getattr(_signal, "SIGINT", None), getattr(_signal, "SIGTERM", None)):
+        if sig is None:
+            continue
+        try:
+            _signal.signal(sig, _on_signal)
+        except (ValueError, OSError):
+            pass
+    _SIGNALS_INSTALLED = True
+
+
+def _watch(proc: subprocess.Popen, cmd: Sequence[str]) -> None:
+    _CHILDREN.append((proc, cmd))
+
+
+def _unwatch(proc: subprocess.Popen) -> None:
+    _CHILDREN[:] = [(p, c) for p, c in _CHILDREN if p is not proc]
 
 
 def emit(output: Optional[str], **extra: Any) -> None:
@@ -376,6 +437,20 @@ def refuse_output_is_input(output: str, *inputs: str) -> None:
                 f"(the result would replace the source) -- choose a different --output/-o path", kind="input")
 
 
+def _check_output_path(cmd: Sequence[str]) -> None:
+    """An output whose directory does not exist, or that names a directory, is a caller mistake:
+    say so as `kind: input` before ffmpeg runs, instead of the muxer's "No such file or directory"
+    as `kind: ffmpeg` (which reads as an encoder failure) or an `OUTPUT_INVALID` after the fact."""
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+        return
+    if os.path.isdir(output):
+        die(f"output {output!r} is a directory; pass a file path (e.g. {os.path.join(output, 'result.mp4')!r})")
+    parent = os.path.dirname(os.path.abspath(output))
+    if not os.path.isdir(parent):
+        die(f"output directory {parent!r} does not exist; create it first (this tool never creates directories)")
+
+
 def _check_existing_output(cmd: Sequence[str]) -> None:
     """An output path that already exists is someone's file: a previous result, a source the
     agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
@@ -461,6 +536,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
         _check_no_overwrite_input(cmd)
+        _check_output_path(cmd)
         _check_existing_output(cmd)
         STATE.commands.append(_cmdline(cmd))
     if not quiet:
@@ -534,9 +610,16 @@ def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subpro
     document (kind timeout, exit 124), so callers that parse the child's --json see a timeout
     exactly as they would from the child itself."""
     limit = child_limit(per_call)
+    child = subprocess.Popen([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    _watch(child, [])  # a sibling script removes its own partial output; there is none of ours to clean
     try:
-        return subprocess.run([sys.executable] + list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+        out, err = child.communicate(timeout=limit)
+        _unwatch(child)
+        return subprocess.CompletedProcess(child.args, child.returncode, out, err)
     except subprocess.TimeoutExpired as e:
+        child.kill()
+        child.communicate()
+        _unwatch(child)
         name = os.path.basename(str(argv[0]))
         msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
         doc = {"status": "failed", "exit_code": 124,
@@ -628,10 +711,18 @@ def _limit_for(cmd: Sequence[str]) -> Optional[float]:
 def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Plain run with stdout/stderr captured."""
     limit = _limit_for(cmd)
+    child = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    _watch(child, cmd)
     try:
-        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+        out, err = child.communicate(timeout=limit)
     except subprocess.TimeoutExpired:
+        child.kill()
+        child.communicate()
+        _unwatch(child)
         _timed_out(cmd, limit or 0)
+    finally:
+        _unwatch(child)
+    proc = subprocess.CompletedProcess(list(cmd), child.returncode, out, err)
     if proc.returncode == 0 and _is_ffmpeg(cmd):
         _remember_output(cmd)
     if proc.returncode != 0:
@@ -671,6 +762,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     t0 = time.time()
     limit = _limit_for(cmd)
     proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    _watch(proc, cmd)
     assert proc.stdout is not None and proc.stderr is not None
     lines: "queue.Queue[Optional[str]]" = queue.Queue()
     err_chunks: List[str] = []
@@ -722,6 +814,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
         proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))
     except subprocess.TimeoutExpired:
         timed_out()
+    _unwatch(proc)
     err_thread.join()
     err = "".join(err_chunks)
     clear_line()
@@ -1020,12 +1113,17 @@ def escape_filter_path(path: str) -> str:
     written `D\\\\:/x.srt`; with a single backslash the second pass still splits at the colon and
     ffmpeg reads `/x.srt` as the next option (`Unable to parse "original_size" option value`).
     Backslashes are turned into forward slashes first (ffmpeg accepts them on Windows), so a backslash
-    never has to be escaped itself; `'`, `,`, `;`, `[` and `]` are graph-level characters.
+    never has to be escaped itself; `,`, `;`, `[` and `]` are graph-level characters and survive with
+    one backslash. `'` is special: the graph parser also treats a quote as the start of a quoted
+    token, so a single `\\'` is consumed by the first pass and "Ryo's Mac/cues.srt" reaches the
+    filter as "Ryos Mac/cues.srt" (Unable to open ...). Three backslashes survive both passes
+    (measured on 6.1 and 7.1 with subtitles=, ass= and lut3d=file=).
     """
     p = str(Path(path))
     p = p.replace("\\", "/")
     p = p.replace(":", "\\\\:")
-    for ch in ("'", ",", ";", "[", "]"):
+    p = p.replace("'", "\\\\\\'")
+    for ch in (",", ";", "[", "]"):
         p = p.replace(ch, "\\" + ch)
     return p
 

package/scripts/_contract.py

@@ -1040,7 +1040,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
             "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached); exit 1"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124", "verification": "the tool ran but its result failed the requested check: check.py platform rows (checks attached), render.py's check stage (output written, check attached), batch.py items (results attached), verify.py steps (files attached); exit 1", "interrupted": "the tool received SIGINT or SIGTERM: the running ffmpeg (or sibling script) was stopped and its partial output removed; exit 130 or 143"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/batch.py

@@ -144,7 +144,7 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    folder = Path(args.folder)
+    folder = Path(args.folder).resolve()  # relative 'bdir' used to become bdir/bdir/out once joined with the default outdir
     if not folder.is_dir():
         die(f"not a folder: {folder}")
     try:

package/scripts/loudness.py

@@ -50,7 +50,7 @@ def main() -> int:
     ap.add_argument("--tp", type=float, default=-1.0, help="true peak ceiling in dBTP (default -1)")
     ap.add_argument("--lra", type=float, default=11.0, help="loudness range target in LU (default 11)")
     ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
-    ap.add_argument("--audio-bitrate", default="192k", help="AAC bitrate when the container is video (default 192k)")
+    ap.add_argument("--audio-bitrate", default=None, help="AAC bitrate when the container is video (default 192k; raised to 256k/320k only when the encoder overshoots the true-peak ceiling and you did not pin it)")
     ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
     add_common(ap)
     args = ap.parse_args()
@@ -80,24 +80,79 @@ def main() -> int:
     )
     sr = args.sample_rate or meta["audio"].get("sample_rate") or 48000
     ext = os.path.splitext(output)[1].lower()
-    cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
-    if ext in AUDIO_CODECS or not meta.get("video"):
-        cmd += ["-vn"] + audio_codec_for(output, args.audio_bitrate)
-    else:
-        cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", args.audio_bitrate]
-    cmd.append(output)
-    run(cmd)
+    bitrate_pinned = args.audio_bitrate is not None
+    bitrate = args.audio_bitrate or "192k"
 
+    def encode(tp: float, bitrate: str) -> None:
+        af = (
+            f"loudnorm=I={args.lufs}:TP={tp}:LRA={args.lra}"
+            f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
+            f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
+        )
+        cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
+        if ext in AUDIO_CODECS or not meta.get("video"):
+            cmd += ["-vn"] + audio_codec_for(output, bitrate)
+        else:
+            cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
+        cmd.append(output)
+        run(cmd)
+
+    encode(args.tp, bitrate)
     if STATE.dry_run:
         # pass 1 measured the input for real; there is no output to measure
         emit(output, measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
         return 0
     after = measure(output, args.lufs, args.tp, args.lra)
+    # loudnorm holds the ceiling on the float samples it outputs; the lossy encoder then adds
+    # its own overshoot. ffmpeg's native AAC at 192k turned one transient of a 12-minute film
+    # from -2.4 dBFS into +3.7 dBFS, so the file measured +1.2 dBTP after "--tp -1" and
+    # check.py's fix hint pointed straight back here. Two remedies, in this order: more bits
+    # (256k, then 320k: the overshoot is quantisation noise and shrinks with bitrate, and the
+    # loudness target is untouched) when the caller did not pin the bitrate; then a lower
+    # loudnorm ceiling by the measured overshoot, which in linear mode also lowers the
+    # integrated loudness -- reported, never hidden.
+    ceiling, rounds = args.tp, 0
+    steps = [] if bitrate_pinned or ext in AUDIO_CODECS and "aac" not in AUDIO_CODECS[ext] else [b for b in ("256k", "320k") if _kbps(b) > _kbps(bitrate)]
+    while not after.get("silent") and float(after["input_tp"]) > args.tp + 0.1 and rounds < 5:
+        rounds += 1
+        overshoot = float(after["input_tp"]) - args.tp
+        if steps:
+            bitrate = steps.pop(0)
+            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {args.tp:g} dBTP after encoding "
+                 f"(codec overshoot); re-encoding at {bitrate}")
+        else:
+            ceiling -= overshoot + 0.2
+            info(f"true peak {float(after['input_tp']):.2f} dBTP exceeds the requested {args.tp:g} dBTP after encoding "
+                 f"(codec overshoot); re-encoding with the loudnorm ceiling at {ceiling:.2f} dBTP")
+        encode(ceiling, bitrate)
+        after = measure(output, args.lufs, args.tp, args.lra)
     if not after.get("silent"):
-        info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
-    emit(output, result={k: after[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")})
+        info(f"result:   {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS, TP <= {args.tp:g})")
+    result = {k: after[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")}
+    result["tp_ceiling_used"] = round(ceiling, 2)
+    if ext not in AUDIO_CODECS or "aac" in AUDIO_CODECS[ext]:
+        result["audio_bitrate_used"] = bitrate
+    result["encodes"] = rounds + 1
+    if not after.get("silent") and abs(float(after["input_i"]) - args.lufs) > 1.0:
+        result["note"] = (f"integrated loudness is {float(after['input_i']) - args.lufs:+.1f} LU from the target because the "
+                          f"true-peak ceiling had to absorb the encoder's overshoot; a lossless delivery (wav/flac) or a pinned "
+                          f"higher --audio-bitrate keeps both")
+    if not after.get("silent") and float(after["input_tp"]) > args.tp + 0.1:
+        die(f"true peak is still {float(after['input_tp']):.2f} dBTP after {rounds + 1} encodes (requested <= {args.tp:g}); "
+            f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
+            kind="verification", output=output, result=result,
+            hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
+    emit(output, result=result)
     return 0
 
 
+def _kbps(value: str) -> int:
+    v = value.lower().rstrip("k")
+    try:
+        return int(float(v)) if value.lower().endswith("k") else int(float(v)) // 1000
+    except ValueError:
+        return 0
+
+
 if __name__ == "__main__":
     sys.exit(main())