ffmpeg-skill 2.5.0 → 2.5.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 (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.5.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.5.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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.5.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.5.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.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.5.0",
+  "version": "2.5.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/__init__.py

@@ -94,7 +94,7 @@ from _common.color import (
     bt709_tag_args, color_hex, _COLOR_TOKEN_RE, _sdr_bt709, validate_color
 )
 from _common.text import (
-    ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw,
+    ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
     drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
     _EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
     _EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
@@ -188,7 +188,7 @@ __all__ = [
     "BEAT_REFRACTORY_S", "BEAT_WINDOW_S", "BEAT_SUPPORT_DIVISOR", "BEAT_ALIGN_DIVISOR",
     "BEAT_Z_FLOOR", "BEAT_Z_SPAN",
     "_onset_strength", "_pick_onsets", "_autocorrelation_peak", "_grid_score",
-    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw",
+    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align",
     "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
     "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
     "emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",

package/scripts/_common/drawtext.py

@@ -97,6 +97,13 @@ def escape_drawtext(text: str) -> str:
     )
 
 
+def drawtext_center_align() -> str:
+    """`:text_align=C` for a centred drawtext, so each line of a multi-line label is centred on
+    its own. The option arrived in FFmpeg 6.1 (5.x and 6.0 reject it); there the block is still
+    centred as a whole by its x expression, with its lines left-aligned inside it."""
+    return ":text_align=C" if ffmpeg_version() >= (6, 1) else ""
+
+
 def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
     every character on every build shape this repo uses.
@@ -106,8 +113,11 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
     and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
     `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
-    done"` losing both characters. Control characters are still stripped: a one-line burnt-in
-    label has no use for them.
+    done"` losing both characters. A newline is kept (`\r\n` and `\r` become `\n`): drawtext
+    draws it as a line break, and graphics.py's wrap puts them there on purpose (stripping them
+    ran a wrapped title off both edges of the frame). A tab, vertical tab or form
+    feed becomes a space, as the wrap measures it; other control characters are stripped (that
+    dates from the inline-escape route, where they broke the graph parser).
 
     The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
     removed when the process ends. It is *registered* here and written by run() only if the
@@ -115,7 +125,8 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
     printed plan therefore names a path that no longer exists once the run is over, which is the
     same promise every other temp file in this skill makes.
     """
-    cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+    cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
     import hashlib
     name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
     if tmpdir is None:

package/scripts/_common/text.py

@@ -31,7 +31,7 @@ from _common.emoji import (
 )
 from _common.drawtext import (
     drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
-    escape_drawtext, drawtext_text_opts,
+    escape_drawtext, drawtext_text_opts, drawtext_center_align,
 )
 from _common.wrap import (
     ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,

package/scripts/graphics.py

@@ -35,7 +35,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as
 from _common import (aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path,
                      ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args,
-                     drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
+                     drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
@@ -356,14 +356,14 @@ def main() -> int:
         h2 = int(base * 0.045)
         filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
         add_text(args.title,
-                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
+                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
                  y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
                  outline_color="000000", start=s, end=e, fade=(300, 300))
         filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{h1 // 2 + (0 if args.subtitle else 0)}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
         if args.subtitle:
             add_text(args.subtitle,
-                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
+                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
                      size=h2, color=primary, font=ass_font_family(), align=5, x=W / 2,
                      y=H / 2 + h1 // 2 + int(base * 0.03), outline=max(1.0, h2 / 20.0),
                      outline_color="000000", start=s, end=e, fade=(300, 300))
@@ -444,8 +444,8 @@ def main() -> int:
         filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
         hook_title = wrapped(args.title, h1)
         add_text(hook_title,
-                 f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
-                 f"x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
+                 f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}"
+                 f"{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
                  outline=max(1.0, h1 / 20.0), outline_color="000000", start=s, end=he)
         filters.append(f"drawbox=x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}:"
@@ -466,7 +466,7 @@ def main() -> int:
             meme_line = wrapped(text.upper(), fs)
             add_text(meme_line,
                      f"drawtext={drawtext_text_opts(meme_line)}:{fo}:fontsize={fs}:fontcolor={white}:"
-                     f"borderw={bw}:bordercolor={black}:x=(w-text_w)/2:y={y}:{en}",
+                     f"borderw={bw}:bordercolor={black}{drawtext_center_align()}:x=(w-text_w)/2:y={y}:{en}",
                      size=fs, color="FFFFFF", font=ass_font_family(), bold=True,
                      align=(8 if y == f"{m_top}" else 2), x=W / 2,
                      y=(m_top if y == f"{m_top}" else H - m_bottom),