ffmpeg-skill 1.4.14 → 1.5.0

package/README.md

@@ -355,6 +355,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **36 / 36** | 1.4.15 re-run (2026-09-12, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, report format 25/25, user's language 9/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3, one Japanese report with English labels; trigger set 22/22. Both iteration-5 defects gone (no raw ffmpeg fallback, music no longer shortens the video). Details in `evals/results/iteration-6.json` |
 | **36 / 36** | 1.4.0 re-run (2026-09-11, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, user's language 8/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3; trigger set 22/22. Details and the six findings in `evals/results/iteration-5.json` |
 | **6 / 6** | 0.9.1 audio evals (audio join, extraction, track selection, sample-accurate trim, typed dynamics; 2 in Japanese): routing, report format and audio-as-audio handling 6/6 |
 

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.14`) | any release |
+| `skill.version` | the npm / package.json version (`1.5.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`
@@ -46,7 +46,7 @@ For the whole of 1.x:
 | Tool ids (`ffmpeg-skill/<name>`) and script names | never removed or renamed |
 | CLI arguments (`argparse` dests, flags, positionals) | never removed, renamed, or made newly required; new optional arguments may be added |
 | `--json` output keys, and the keys of `contract --json` / `doctor --json` | never removed or given a different type; new keys may be added |
-| Exit codes (0 success, 1 failure, 2 unknown/undecidable in `doctor`) | unchanged |
+| Exit codes (0 success, 1 failure incl. ffmpeg failures, 2 unknown/undecidable in `doctor`, 124 timeout, 127 missing tool, 128+signal interrupted) | unchanged |
 | `contract_version` (`1.0`) | unchanged; a ToolSpec shape change is a major |
 | MCP `tools/list` names and `inputSchema` property names | derived from the above, so covered by the same promise |
 | Behaviour of a tool for the same input and arguments | may change only to fix a defect or to track an FFmpeg change, and every such change gets a CHANGELOG line |
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.4.14", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.5.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"},
@@ -299,6 +299,15 @@ Success (`exit 0`): one document matching `output_schema`, always with
 `status: "completed"`, `output`, `dry_run`, `commands`, and `probe` of the output when a
 file was written. `probe` prints its measurement document directly.
 
+With `FFMPEG_SKILL_RESULT_V2=1` in the environment, every writing tool's success document
+also carries `result_v2`: a preview of the one shape 2.0 will use for every tool
+(issue #189). `{"schema": 2, "output", "probe", "commands", "metrics", "notes", "dropped":
+{"non_av_streams"}, "details"}` -- `metrics` holds the numbers a caller keys on (loudness's
+measurement dicts flattened, plus any numeric top-level key such as `expected_duration` or
+`offset_seconds`), `notes` the free text, `details` the tool's remaining keys unchanged. The
+1.x keys are not moved; the environment variable only adds the key, and its absence is the
+default until 2.0.
+
 Success is decided by `verify_output` in `_common.py`, not by the ffmpeg exit code alone:
 the file must exist, be non-empty and give ffprobe at least one stream. A tool that ran
 ffmpeg successfully but has no usable artifact fails with `kind: output` (a 0-byte file is
@@ -318,7 +327,8 @@ before, and, when `--json` was given, on stdout:
 `message` carries the script's own reason (missing input, ffprobe failure, the last
 stderr lines of ffmpeg, the verification that failed); an optional `error.hint` names the
 flag change that would make a retry meaningful (never a diagnosis of the media); `commands` lists what was planned
-or run so the caller can retry or report without re-deriving the command. `code` is a
+or run so the caller can retry or report without re-deriving the command; `kind: ffmpeg`
+failures add `ffmpeg_returncode` (ffmpeg's own exit code; the process exits 1). `code` is a
 purely additive, statically-mapped relabelling of `kind` (never a new distinction `kind`
 doesn't already make) for a caller that wants a stable enum instead of matching `kind`
 strings. `retryable` is currently always `false`: none of the kinds are distinguishable

package/package.json

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

@@ -281,6 +281,8 @@ rather than a continuous curve. `START`/`END` take seconds or `mm:ss`;
 0.5 = half speed). Picking exactly where a ramp should ease in or out is a
 judgement call for the calling agent, made concrete here as the segment
 boundaries it supplies.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### loop.py — repeat a clip
 ```
@@ -308,6 +310,8 @@ overlap or run past A's end, and B must have enough material from `--from`.
 `--audio a` (default) keeps A's audio untouched and stream-copied; `b` replaces
 it inside each window with B's; `mix` plays both. The output's length is
 verified against A's.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### metadata.py — chapter markers and container tags, streams copied
 ```
@@ -362,6 +366,8 @@ channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
 silent track generated for clips without audio), then chains `xfade` +
 `acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
+A subtitle/data track in the source is not carried into the retimed/concatenated
+output; the result says so with `dropped_non_av_streams: true`.
 
 ### render.py — the whole edit in one project.json
 ```
@@ -596,7 +602,8 @@ standard talking-head chain. `--duck` uses a sidechain compressor keyed by the
 speech so music dips under dialogue and swells in pauses. `--downmix` uses the
 ITU centre/LFE weights for 5.1/7.1 → stereo. `--mono` averages a stereo pair,
 leaves a 1-channel input untouched and downmixes >2 channels through
-swresample. Video is always stream-copied.
+swresample. Video is always stream-copied, and so is a subtitle/data track
+when the container can hold it (`dropped_non_av_streams` says when it could not).
 Run `loudness.py` after this for final levels.
 
 ### loudness.py — EBU R128 normalisation
@@ -604,7 +611,8 @@ Run `loudness.py` after this for final levels.
 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
+the true-peak ceiling allows). Video and any subtitle/data track are
+stream-copied (`dropped_non_av_streams` reports a track the container refused); 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
@@ -629,6 +637,7 @@ proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]
 Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
 factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest
 x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
-run `color.py --to-sdr` first if SDR is wanted). Only executes the spec
+run `color.py --to-sdr` first if SDR is wanted) and keeps a subtitle/data
+track when the container can hold it (`dropped_non_av_streams`). Only executes the spec
 given — does not decide which asset to proxy or what for.
 

package/scripts/_common.py

@@ -348,11 +348,44 @@ def emit(output: Optional[str], **extra: Any) -> None:
         if meta:
             doc["probe"] = meta
         doc.update(extra)
+        if os.environ.get("FFMPEG_SKILL_RESULT_V2", "") not in ("", "0"):
+            doc["result_v2"] = _result_v2(output, meta, extra)
         print_json(doc)
     elif output:
         print(output)
 
 
+_V2_HANDLED = ("result", "measured", "notes", "dropped_non_av_streams")
+
+
+def _result_v2(output: Optional[str], meta: Dict[str, Any], extra: Dict[str, Any]) -> Dict[str, Any]:
+    """The 2.0 success-document shape, previewed in 1.x as a parallel `result_v2` key when
+    FFMPEG_SKILL_RESULT_V2=1 (issue #189 B). Every tool gets the same six slots: `output`,
+    `probe`, `commands`, `metrics` (numbers a caller keys on: loudness's `result`/`measured`
+    dicts flattened, plus every top-level numeric extra such as `expected_duration` or
+    `offset_seconds`), `notes` (free text), `dropped` (what did not make it into the output),
+    and `details` (the tool's remaining extras, unchanged). The 1.x keys stay where they are;
+    this key is additive and its shape is what 2.0 promotes to the top level."""
+    metrics: Dict[str, Any] = {}
+    for key in ("measured", "result"):
+        if isinstance(extra.get(key), dict):
+            metrics.update(extra[key])
+    for key, value in extra.items():
+        if key not in _V2_HANDLED and isinstance(value, (int, float)) and not isinstance(value, bool):
+            metrics[key] = value
+    notes = extra.get("notes")
+    return {
+        "schema": 2,
+        "output": output,
+        "probe": meta or None,
+        "commands": list(STATE.commands),
+        "metrics": metrics,
+        "notes": list(notes) if isinstance(notes, (list, tuple)) else ([notes] if notes else []),
+        "dropped": {"non_av_streams": bool(extra.get("dropped_non_av_streams", False))},
+        "details": {k: v for k, v in extra.items() if k not in _V2_HANDLED and k not in metrics},
+    }
+
+
 def _cmdline(cmd: Sequence[str]) -> str:
     return " ".join(shell_quote(c) for c in cmd)
 
@@ -398,8 +431,12 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:
 def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
     # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
     # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
+    # The process exit code is always 1 for an ffmpeg failure: ffmpeg's own code (1, 69, 218, 234,
+    # a negative signal number...) varies by build and by the failing stage, and 124/127/130/143
+    # are reserved for timeout, missing tool and interrupts. The raw code is kept in the JSON
+    # document as `ffmpeg_returncode` for a caller that wants it. docs/design-decisions.md.
     tail = "\n".join(stderr.strip().splitlines()[-15:])
-    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1, kind="ffmpeg")
+    die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=1, kind="ffmpeg", ffmpeg_returncode=returncode)
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:

package/scripts/audio.py

@@ -20,7 +20,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, fmt_secs
+from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
@@ -226,8 +226,11 @@ def main() -> int:
     if not keep_video:
         # audio-only outputs: a looped music bed is infinite, -shortest ends the run with the main track
         cmd.append("-shortest")
-    cmd.append(output)
-    run(cmd)
+    if keep_video:
+        dropped_streams = run_keeping_subtitles(cmd, output)
+    else:
+        dropped_streams = bool(has_video and (meta.get("subtitle_streams") or meta.get("data_streams")))
+        run(cmd + [output])
     r = probe(output, role="output")
     a = r["audio"]
     if r.get("video") and audio_out and not STATE.dry_run:
@@ -235,7 +238,8 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(r['duration'])}, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
          + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
     emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
-         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f])
+         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f],
+         dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/broll.py

@@ -145,7 +145,8 @@ def main() -> int:
     if not STATE.dry_run and dur_a and abs((result.get("duration") or 0.0) - dur_a) > max(0.1, 1.5 / fps):
         die(f"output is {fmt_secs(result.get('duration'))} but the A-roll is {dur_a:.3f}s -- a cutaway must not change the length", kind="output")
     info(f"wrote {output} ({result.get('duration', 0):.3f}s, {len(cutaways)} cutaway(s), audio={args.audio})")
-    emit(output, cutaways=[{"insert": c["path"], "at": c["at"], "end": c["at"] + c["length"], "from": c["from"]} for c in cutaways], audio=args.audio)
+    emit(output, cutaways=[{"insert": c["path"], "at": c["at"], "end": c["at"] + c["length"], "from": c["from"]} for c in cutaways], audio=args.audio,
+         dropped_non_av_streams=bool(meta_a.get("subtitle_streams") or meta_a.get("data_streams")))
     return 0
 
 

package/scripts/join.py

@@ -206,7 +206,8 @@ def main() -> int:
     expected = sum(durs) - d * (n - 1)
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
-    emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3))
+    emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3),
+         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 
 

package/scripts/loudness.py

@@ -18,7 +18,7 @@ import os
 import re
 import sys
 
-from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, dry_run_input_pending
+from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
 
@@ -90,7 +90,10 @@ def main() -> int:
     bitrate_pinned = args.audio_bitrate is not None
     bitrate = args.audio_bitrate or "192k"
 
+    dropped_streams = False
+
     def encode(tp: float, bitrate: str) -> None:
+        nonlocal dropped_streams
         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']}"
@@ -101,6 +104,8 @@ def main() -> int:
             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]
+            dropped_streams = run_keeping_subtitles(cmd, output)
+            return
         cmd.append(output)
         run(cmd)
 
@@ -149,7 +154,7 @@ def main() -> int:
             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)
+    emit(output, result=result, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/proxy.py

@@ -25,7 +25,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, fmt_secs
+from _common import add_common, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, fmt_secs
 
 
 def even(n: float) -> int:
@@ -67,14 +67,13 @@ def main() -> int:
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", f"scale={out_w}:-2"]
     cmd += video_args(meta, args.crf, "veryfast")
     cmd += cfr_args(meta, args.fps)
-    cmd += ["-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"]
-    cmd.append(output)
-    run(cmd)
+    cmd += ["-map", "0:v:0"] + (["-map", "0:a:0", "-c:a", "aac", "-b:a", "96k"] if has_audio else ["-an"])
+    dropped_streams = run_keeping_subtitles(cmd, output)
 
     result = probe(output)
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']}, crf {args.crf})")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/speedramp.py

@@ -115,7 +115,7 @@ def main() -> int:
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {len(segments)} speed segments)")
-    emit(output)
+    emit(output, dropped_non_av_streams=bool(meta.get("subtitle_streams") or meta.get("data_streams")))
     return 0