ffmpeg-skill 3.1.2 → 3.1.3

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.2`) | any release |
+| `skill.version` | the npm / package.json version (`3.1.3`) | 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.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.1.3", "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.2",
+  "version": "3.1.3",
   "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/emit.py

@@ -13,6 +13,59 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
 
 
+# Characters that never belong in a message a calling agent reads (#400): C0 controls (a line
+# break is one), DEL and C1, the Unicode line/paragraph separators and the bidi embedding,
+# override and isolate marks. A path or other argument carrying one would otherwise reach
+# error.message / a diagnostic verbatim, where a newline can start what reads as a new line of
+# instructions and a bidi override can reorder what is shown.
+_UNSAFE = frozenset([chr(c) for c in range(0x20) if c not in (0x09, 0x0A)] + [chr(0x7F)]
+                    + [chr(c) for c in range(0x80, 0xA0)]
+                    + ["\u2028", "\u2029", "\u200e", "\u200f"] + [chr(c) for c in range(0x202A, 0x202F)]
+                    + [chr(c) for c in range(0x2066, 0x206A)])
+_LINE_BREAKS = frozenset("\n")
+
+
+def shown(value: Any) -> str:
+    """`value` as text with every unsafe character (and any line break) written as an escape
+    (\\n, \\x1b, \\u202e). A clean value comes back unchanged, so an ordinary path, a Windows one
+    with backslashes included, reads exactly as before."""
+    text = str(value)
+    if not any(ch in _UNSAFE or ch in _LINE_BREAKS for ch in text):
+        return text
+    return "".join((ch.encode("unicode_escape").decode("ascii") if (ch in _UNSAFE or ch in _LINE_BREAKS) else ch)
+                   for ch in text)
+
+
+def _argument_forms(arg: str) -> List[str]:
+    """The spellings a message may print an argument in: as given, resolved, and its file name;
+    for `--opt=value`, the same for the value, which is what a tool prints back."""
+    given = [arg] + ([arg.split("=", 1)[1]] if arg.startswith("-") and "=" in arg else [])
+    forms = set(given)
+    for a in given:
+        try:
+            forms.update({os.path.abspath(a), os.path.realpath(a), os.path.basename(a)})
+        except (OSError, ValueError):
+            pass
+    return sorted((f for f in forms if f), key=len, reverse=True)
+
+
+def neutralize(msg: Any) -> Any:
+    """A message with caller-supplied text made inert (#400): every command-line argument that
+    carries a line break or an unsafe character is replaced by its shown() form wherever it
+    appears (as given, resolved or as a file name), then any unsafe character left is escaped.
+    Line breaks the tool itself wrote (an ffmpeg stderr tail) stay; one inside an argument does not."""
+    if not isinstance(msg, str):
+        return msg
+    for arg in sys.argv[1:]:
+        if isinstance(arg, str) and any(ch in _UNSAFE or ch in _LINE_BREAKS for ch in arg):
+            for form in _argument_forms(arg):
+                if form in msg and (form != os.path.basename(arg) or any(ch in _UNSAFE or ch in _LINE_BREAKS for ch in form)):
+                    msg = msg.replace(form, shown(form))
+    if any(ch in _UNSAFE for ch in msg):
+        msg = "".join(ch.encode("unicode_escape").decode("ascii") if ch in _UNSAFE else ch for ch in msg)
+    return msg
+
+
 def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]" = None,
         error_extra: "Optional[Dict[str, Any]]" = None, **extra: Any) -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
@@ -26,7 +79,8 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
 
     `error_extra` goes inside `error` (refuse() passes `reason` and `details` there); the
     collector's records (warn() and friends) are merged into the document as emit() merges them."""
-    hint = extra.pop("hint", None)
+    hint = neutralize(extra.pop("hint", None))
+    msg = neutralize(msg)
     ctx = ctx or STATE  # 1.10: the optional per-request Context (2.0 makes it required); STATE is the default instance
     _set_current_ctx(ctx)  # the atexit hook has no argument: it reads the ctx emit()/die() last used
     ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
@@ -61,6 +115,28 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
     sys.exit(code)
 
 
+def _report_dropped_audio_tracks(meta: Dict[str, Any], ctx: "Context") -> None:
+    """The tools write one audio track: a source with several must say how many did not come
+    along (#397, every tool, not only cut.py). Only when the output kept sound at all: a tool told
+    to drop it (--no-audio, a picture-only output) left nothing out by surprise."""
+    first = getattr(STATE, "first_input", None)
+    if not first or first[1] < 2 or not meta:
+        return
+    if len(getattr(STATE, "audio_inputs", None) or ()) > 1:
+        return  # several sources with sound: which one's tracks the output carries is the tool's own choice
+    kept = len(meta.get("audio_streams") or [])
+    if not kept or kept >= first[1]:
+        return
+    if any(w.get("code") == "audio_tracks_dropped" for w in ctx.warnings):
+        return  # the tool said it already (cut.py, with its own field)
+    warn(f"the source has {first[1]} audio tracks; this output kept {kept} and left {first[1] - kept} out "
+         "(the tools write one audio track; --audio-stream N picks which, where a tool takes it)",
+         "audio_tracks_dropped", ctx=ctx, source=first[1], kept=kept, dropped=first[1] - kept)
+    note_line = ctx.warnings[-1]["message"] if ctx.warnings else None
+    if note_line and note_line not in ctx.notes:
+        ctx.notes.append(note_line)
+
+
 def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code: int = 1,
            ctx: "Optional[Context]" = None, extra: "Optional[Dict[str, Any]]" = None, **details: Any) -> "None":
     """die() for a refusal a caller has to act on: `error.reason` is a stable snake_case code for
@@ -72,6 +148,7 @@ def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code
 
 def _record(bucket: str, msg: str, code: str, ctx: "Optional[Context]", data: Dict[str, Any], prefix: str) -> Dict[str, Any]:
     ctx = ctx or STATE
+    msg = neutralize(msg)
     entry: Dict[str, Any] = {"code": code, "message": msg}
     entry.update(data)
     # once per run: a decision taken for every encode of a job (an AV1 encoder fallback, a CRF
@@ -116,6 +193,9 @@ def _merge_collector(doc: Dict[str, Any], ctx: "Context") -> None:
     extra_notes = [n for n in ctx.notes if n not in (doc.get("notes") or [])]
     if extra_notes:
         doc["notes"] = list(doc.get("notes") or []) + extra_notes
+    if doc.get("notes"):
+        # a tool's own notes can quote an input path (join.py's duplicates): made inert as messages are (#400)
+        doc["notes"] = [neutralize(n) for n in doc["notes"]]
     diag = {k: list(getattr(ctx, k)) for k in ("warnings", "fallbacks", "skipped") if getattr(ctx, k)}
     if diag:
         merged = dict(doc.get("diagnostics") or {})
@@ -601,6 +681,7 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
     meta: Dict[str, Any] = {}
     if output and not ctx.dry_run:
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
+        _report_dropped_audio_tracks(meta, ctx)
     if ctx.json:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:

package/scripts/_common/probe.py

@@ -355,6 +355,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "language": (a.get("tags") or {}).get("language"),
             "title": (a.get("tags") or {}).get("title"),
         } for n, a in enumerate(s for s in streams if s.get("codec_type") == "audio")]
+    if role == "input" and out.get("audio_streams"):
+        STATE.audio_inputs.add(os.path.realpath(path))
+    if role == "input" and getattr(STATE, "first_input", None) is None:
+        STATE.first_input = (path, len(out.get("audio_streams") or []))
     return out
 
 

package/scripts/_common/runner.py

@@ -324,7 +324,7 @@ class Context:
 
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
-                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification")
+                 "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs")
 
     def __init__(self) -> None:
         self.reset()
@@ -332,6 +332,8 @@ class Context:
     def reset(self) -> None:
         self.dry_run = False      # print ffmpeg commands, run nothing (ffprobe still runs)
         self.json = False         # emit() prints a JSON document instead of the output path
+        self.first_input = None   # (path, audio track count) of the first input probed: emit() reports tracks the output left out
+        self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
         self.fast = False         # x264 preset forced to veryfast

package/scripts/_contract.py

@@ -109,7 +109,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                     required=FF + [X264, AAC, "filter:v360"], optional=[HDR_X265],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "grid": dict(role="execution", inputs=["cols*rows video assets, filled left-to-right top-to-bottom"], outputs=["composited grid video artifact"],
-                 required=FF + [X264, "filter:xstack"], optional=[{"capability": "filter:drawtext", "when": "--label auto (the default)"}, {"capability": AAC, "when": "--audio-from"}],
+                 required=FF + [X264, "filter:xstack"], optional=[{"capability": "filter:drawtext", "when": "--label auto (the default; without drawtext the cells are not labelled, fallback grid_no_drawtext)"}, {"capability": AAC, "when": "--audio-from"}],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "straighten": dict(role="execution", inputs=["video asset"], outputs=["video artifact rotated by the given angle (horizon correction)"],
                        required=FF + [X264, AAC, "filter:rotate"], optional=[HDR_X265],
@@ -464,7 +464,9 @@ DIAGNOSTIC_CODES = {
     "crf_clamped": ("warnings", "the CRF handed to the encoder was above its maximum and was capped (the HEVC HDR line adds 2); {encoder, requested, asked, used}"),
     # fonts and text
     "emoji_not_drawn": ("warnings", "caption.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; {count, reason}"),
-    "audio_tracks_dropped": ("warnings", "cut.py: the source has more audio tracks than the cut wrote (one); {source, kept, dropped}"),
+    "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams); {source, kept, dropped}"),
+    "grid_no_drawtext": ("fallbacks", "grid.py --label auto on a build without the drawtext filter: the cells were not labelled, as with --label none"),
+    "scenes_sheet_no_drawtext": ("fallbacks", "scenes.py --sheet on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
     "look_no_drawtext": ("fallbacks", "look.py on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
     "font_substituted": ("fallbacks", "the asked font family is not installed: fontconfig or the Windows Fonts folder gave another (font_used names it); {asked, file, family, via}"),
     "font_lacks_script": ("warnings", "an explicit --font does not cover the text's script and is kept as asked; {font, script}"),

package/scripts/grid.py

@@ -29,6 +29,8 @@ from _common import add_common, apply_common, aac_args, cfr_args, default_output
     draws_chroma, drawn_chain, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, probe, run, validate_color, video_args
 from _common.fonts import font_choice, record_font_choice
 from _common import drawtext_fontfile  # noqa: E402
+from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
+from _common.emit import note, record_fallback  # noqa: E402
 
 LABEL_MARGIN = 10
 
@@ -56,6 +58,13 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.label == "auto" and ffmpeg_filters() and "drawtext" not in ffmpeg_filters():
+        # the labels are the only drawtext in the grid: without the filter (Homebrew's plain
+        # ffmpeg) draw the grid unlabelled and say so, as look.py does for its stamps (#394)
+        args.label = "none"
+        record_fallback("this ffmpeg build has no drawtext filter, so the cells are not labelled "
+                        "(the same as --label none)", "grid_no_drawtext")
+        note("no cell labels: this ffmpeg build has no drawtext filter (" + filter_missing_hint("drawtext") + ")")
 
     n = args.cols * args.rows
     if args.cols <= 0 or args.rows <= 0:

package/scripts/scenes.py

@@ -27,6 +27,8 @@ from _common import (guard_sidecar, detect_scenes, STATE, add_common, apply_comm
                      ffmpeg_base, info, print_json, probe, run, decode_pcm_mono,
                      rms_envelope, BEAT_MIN_CONFIDENCE, decode_gray_frames, frame_flow, label_shot_flow)
 from _common import drawtext_fontfile  # noqa: E402
+from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
+from _common.emit import note, record_fallback  # noqa: E402
 
 SHOT_FPS = 4.0          # frames/second sampled for --shots' flow estimate
 SHOT_W, SHOT_H = 48, 27  # decode size for --shots (16:9-ish; enough blocks, still a few KB/shot)
@@ -287,6 +289,13 @@ def main() -> int:
         fps = meta["video"].get("fps") or 30.0
         expr = "+".join(f"eq(n\\,{int(round(sc['start'] * fps))})" for sc in scenes)
         stamp = ""
+        if not args.no_timecode and ffmpeg_filters() and "drawtext" not in ffmpeg_filters():
+            # as look.py (#394): the sheet needs drawtext only for its stamps
+            args.no_timecode = True
+            record_fallback("this ffmpeg build has no drawtext filter, so the --sheet has no timecode stamps "
+                            "(the same as --no-timecode)", "scenes_sheet_no_drawtext")
+            note("--sheet without timecode stamps: this ffmpeg build has no drawtext filter ("
+                 + filter_missing_hint("drawtext") + ")")
         if not args.no_timecode:
             default_font = default_font_file("DejaVu Sans")
             font_prefix = f"{drawtext_fontfile(default_font)}:" if default_font else ""
@@ -297,7 +306,7 @@ def main() -> int:
         info(f"wrote {args.sheet}")
         result["sheet"] = args.sheet
 
-    if args.json:
+    if STATE.json:  # --json-brief too: emit() is what adds the diagnostics (scenes_sheet_no_drawtext)
         emit(None, **result)
     else:
         print_json(result)