ffmpeg-skill 2.12.0 → 2.12.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.12.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.12.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`
@@ -125,7 +125,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "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"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.12.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.12.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; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.12.0",
+  "version": "2.12.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",
@@ -51,6 +51,7 @@
   ],
   "scripts": {
     "test": "python3 tests/test_all.py && python3 tests/test_contract.py",
+    "test:fast": "python3 tests/test_contract.py",
     "release-check": "bash tests/release_check.sh",
     "demo": "python3 demos/build.py",
     "demo:pipeline": "bash examples/make_demo.sh",

package/scripts/look.py

@@ -28,7 +28,12 @@ def fmt_hms(sec: float) -> str:
     return f"{int(h):02d}:{int(m):02d}:{s_:06.3f}"
 
 
-def timecode_filter(font_prefix: str) -> str:
+def timecode_filter(font_prefix: str, offset: float = 0.0) -> str:
+    """Burned-in timecode. `offset` is added to each frame's pts: an input-side -ss resets
+    timestamps to 0 at the seek point, so a sheet that starts reading mid-slice must add the seek
+    back or every tile is labelled `offset` seconds early (the contact sheet below seeks step/2)."""
+    if offset > 0:
+        return f"drawtext=text='%{{pts\\:hms\\:{offset:.6f}}}':{font_prefix}{FONT}"
     return f"drawtext=text='%{{pts\\:hms}}':{font_prefix}{FONT}"
 
 
@@ -256,10 +261,12 @@ def main() -> int:
         tile_w = max(2, (args.width // cols) // 2 * 2)
         out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
         # sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
-        vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc},"
-              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
         # with only a handful of frames a mid-slice seek skips past them all: start at 0 instead
         seek = 0.0 if frames_avail < 4 else step / 2
+        # the seek resets pts to 0, so the burned-in timecode gets the seek added back
+        tc_sheet = tc.replace(timecode_filter(font_prefix), timecode_filter(font_prefix, seek)) if seek else tc
+        vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc_sheet},"
+              f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
         cmd = ffmpeg_base() + ["-ss", f"{seek:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
         run(cmd)
         outputs.append(out)