ffmpeg-skill 2.12.0 → 2.13.0

package/README.md

@@ -247,7 +247,7 @@ These are the rules the skill file gives the agent and the code enforces.
 | Tool | What it does |
 |---|---|
 | `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area — with `--platform`, the destination's own left/right safe zone, which since 1.17.2 is also what the burnt ASS states as its side margins — with a phrase-aware breaker (`--wrap phrase|measured`) and `--max-lines`/`--min-duration`/`--offset`; `--mode mux` takes a repeated `--srt file:lang` for several language-tagged, toggleable tracks in one file; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; `--fit-size` shrinks the size until a cue fits `--max-lines` instead of splitting the sentence (on by default on the delivery-template path since 1.17.1, where the size comes from the platform table); says `caption text unchanged` when it burned the cues exactly as given; optional local transcription |
-| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--platform NAME` keeps them clear of that destination's UI; `--video` for picture-in-picture, `--chromakey` for green-screen compositing |
+| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--platform NAME` keeps them clear of that destination's UI; `--video` for picture-in-picture, `--chromakey` for green-screen compositing, `--place` to lay ranges of a layer at chosen times |
 | `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs, social stickers, opening hook cards and meme captions drawn by FFmpeg from a brand kit; `--platform NAME` keeps them inside that destination's safe zone; `--text-render` routes shaping scripts through libass and `--emoji-assets` composites colour emoji |
 | `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |
 

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.13.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`
@@ -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.13.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; 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.13.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",
@@ -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/references/scripts.md

@@ -1534,6 +1534,7 @@ stream selection would have picked.
 overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
                   [--emoji auto|mono|none] [--emoji-assets DIR]
                   | --video CLIP [--chromakey COLOR [--chromakey-similarity 0-1] [--chromakey-blend 0-1]]
+                    [--place SRC_START-SRC_END@AT ...]
            [--position top-right|bottom-left|center|X,Y] [--margin N] [--platform NAME] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
 ```
 `--platform NAME` (1.14) takes each edge's margin from that destination's safe zone
@@ -1550,6 +1551,20 @@ playing. `--scale` / `--scale-percent` set the width of an image, logo or
 input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
 (with `--video`) keys out that colour first for green-screen compositing.
 
+`--place SRC_START-SRC_END@AT` (with `--video`, repeatable) shows only that range
+of the layer, starting at `AT` on the main timeline; outside its placed ranges
+the layer is hidden and the main picture is untouched. One pass lays several
+pieces of one layer at their own times -- e.g. graphics rendered back to back
+(only the seconds that have graphics) and placed where each belongs:
+`--video cues.mov --position 0,0 --margin 0 --place 0-2.5@12 --place 2.5-6@40`.
+An `hh:mm:ss:ff` timecode counts the layer's frames in `SRC_START-SRC_END` and
+the main video's in `AT` (an `@fps` suffix names the rate explicitly).
+Refused (`kind: input`): a range that ends before it starts, negative times,
+two pieces overlapping on the main timeline, a range past the layer's last
+picture (by more than half a frame), a
+piece starting after the main video ends, `--place` without `--video`, and
+`--place` with `--start`/`--end`/`--fade` (the placements already say when).
+
 `--fade S` fades the overlay in at `--start` (or 0); the fade-out happens
 only at `--end`, so a logo with no `--end` stays to the last frame.
 

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)

package/scripts/overlay.py

@@ -7,7 +7,10 @@ bottom-right, or explicit "X,Y" pixels (negative counts from the far edge).
 
 --video composites a second VIDEO as a picture-in-picture layer (position,
 scale, opacity, time-range -- same knobs as --image), instead of a still
-image or text. Only the main input's audio is kept; the PiP layer's own
+image or text. --place SRC_START-SRC_END@AT (repeatable, with --video) shows only
+that range of the layer, starting at AT on the main timeline: one pass lays
+several pieces of a layer (say, graphics rendered back to back) at their own
+times, and the main picture shows untouched everywhere else. Only the main input's audio is kept; the PiP layer's own
 audio track, if any, is dropped -- mixing two audio tracks is a job for
 audio.py, not this tool. --chromakey COLOR (with --video) turns that colour
 transparent first (green-screen removal) before compositing.
@@ -19,6 +22,7 @@ Examples:
   python3 overlay.py input.mp4 --text "こんにちは" --font-file /path/NotoSansCJK-Bold.ttc --box
   python3 overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480 --opacity 0.9
   python3 overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00 --chromakey-similarity 0.15
+  python3 overlay.py talk.mp4 --video cues.mov --position 0,0 --margin 0 --place 0-2.5@12 --place 2.5-6@40
 """
 import argparse
 import re
@@ -140,6 +144,34 @@ def per_line_drawtext(lines: List[str], x: str, y: str, font_opt: str, args: arg
     return ",".join(filters)
 
 
+# one time inside --place: seconds, mm:ss, hh:mm:ss.ms or hh:mm:ss:ff with an optional @fps
+# suffix (the time grammar's own); times are never negative, so '-' only separates the range
+_PLACE_TIME = r"[^@\-]+(?:@[0-9.]+)?"
+
+
+def parse_placements(specs: List[str], main_fps: Optional[float], layer_fps: Optional[float]) -> List[tuple]:
+    """--place SRC_START-SRC_END@AT -> [(src_start, src_end, at)], refusing empty, negative or
+    overlapping placements (two pieces on screen at once would stack in an order nobody asked for).
+    SRC_START/SRC_END are positions in the layer, so an hh:mm:ss:ff timecode there counts the
+    layer's frames; AT is a position on the main timeline and counts the main video's."""
+    out = []
+    for spec in specs:
+        m = re.fullmatch(rf"\s*({_PLACE_TIME})-({_PLACE_TIME})@({_PLACE_TIME})\s*", spec)
+        if not m:
+            die(f"--place {spec!r}: use SRC_START-SRC_END@AT, e.g. 0-2.5@12 (times are not negative)")
+        a = time_arg(m.group(1), "--place", layer_fps)
+        b = time_arg(m.group(2), "--place", layer_fps)
+        at = time_arg(m.group(3), "--place", main_fps)
+        if b <= a:
+            die(f"--place {spec!r}: the layer range ends before it starts")
+        out.append((a, b, at))
+    spans = sorted((at, at + (b - a)) for a, b, at in out)
+    for (s1, e1), (s2, _e2) in zip(spans, spans[1:]):
+        if s2 < e1 - 1e-6:
+            die(f"--place: pieces overlap on the main timeline ({s1:g}-{e1:g} s and from {s2:g} s)")
+    return out
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -153,6 +185,10 @@ def main() -> int:
     src.add_argument("--text", help="text to draw (drawtext)")
     src.add_argument("--logo", action="store_true", help="composite the brand logo from --brand (position/scale/opacity from brand.json)")
     src.add_argument("--video", help="a second video to composite as a picture-in-picture layer")
+    ap.add_argument("--place", action="append", default=[], metavar="SRC_START-SRC_END@AT",
+                    help="with --video, repeatable: show this range of the layer starting at AT on the main "
+                         "timeline (e.g. 0-2.5@12); the layer is hidden outside its placed ranges. Times in "
+                         "seconds or HH:MM:SS. Not with --start/--end/--fade")
     ck = ap.add_argument_group("chroma key (with --video)")
     ck.add_argument("--chromakey", help="colour to key out (green-screen removal), e.g. 0x00ff00 or green")
     ck.add_argument("--chromakey-similarity", type=float, default=0.15, help="how close a pixel must be to --chromakey to become transparent, 0..1 (default 0.15)")
@@ -304,6 +340,10 @@ def main() -> int:
         die("--chromakey-similarity must be within (0, 1]")
     if not 0 <= args.chromakey_blend <= 1:
         die("--chromakey-blend must be within 0..1")
+    if args.place and not args.video:
+        die("--place needs --video")
+    if args.place and (args.start or args.end or args.fade):
+        die("--place sets when each piece shows: drop --start / --end / --fade")
 
     output = args.output or default_output(args.input, "overlay")
     enable = enable_expr(start, end)
@@ -355,6 +395,24 @@ def main() -> int:
         pip_meta = probe(args.video)
         if not pip_meta.get("video"):
             die(f"--video {args.video} has no video stream")
+        layer_fps = pip_meta["video"].get("fps")
+        placements = parse_placements(args.place, fps, layer_fps) if args.place else []
+        # bounds from the video streams (a longer audio track would let a range run past the last
+        # picture); the container duration only when a stream has none
+        layer_dur = pip_meta["video"].get("duration") or pip_meta.get("duration")
+        main_dur = meta["video"].get("duration") or meta.get("duration")
+        # half a layer frame of slack absorbs a hand-typed end that rounds the last frame's end
+        # (2.033 for 61 frames at 30 fps); anything longer asks for pictures the layer does not have
+        slack = 0.5 / layer_fps if layer_fps else 0.02
+        for a, b, at in placements:
+            if layer_dur and a >= layer_dur:
+                # the slack below is for an end rounded past the last frame; a start there selects
+                # no picture at all and the "placed" piece would silently never show
+                die(f"--place {a:g}-{b:g}@{at:g}: starts at or after the layer's end ({layer_dur:.3f} s)")
+            if layer_dur and b > layer_dur + slack:
+                die(f"--place {a:g}-{b:g}@{at:g}: the layer is only {layer_dur:.3f} s long")
+            if main_dur and at >= main_dur:
+                die(f"--place {a:g}-{b:g}@{at:g}: starts after the main video ends ({main_dur:.3f} s)")
         chain = []
         if args.scale_percent:
             chain.append(f"scale={int(vw * args.scale_percent / 100)}:-2")
@@ -376,8 +434,26 @@ def main() -> int:
         base, pip = matrix_chain(meta, meta), matrix_chain(pip_meta, meta)
         if base or pip:
             base, pip = base or label_chain(meta, meta), pip or label_chain(pip_meta, meta)
-        fc = (f"[1:v]{pip}{','.join(chain)}[ov];"
-              + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
+        if placements:
+            # each placed piece: its range of the layer, re-timed to start at AT; eof_action=pass shows
+            # the main picture untouched once a piece ends (the default would freeze its last frame)
+            pieces = len(placements)
+            # trim selects by timestamp: start the layer's at 0 so SRC_START/SRC_END count from its
+            # first picture even when its video stream starts later than the file (audio first)
+            fc = f"[1:v]setpts=PTS-STARTPTS,{pip}{','.join(chain)},split={pieces}" + "".join(f"[p{i}]" for i in range(pieces)) + ";"
+            for i, (a, b, at) in enumerate(placements):
+                fc += f"[p{i}]trim=start={a:.6f}:end={b:.6f},setpts=PTS-STARTPTS+{at:.6f}/TB[q{i}];"
+            prev = f"[0:v]{base}null[m]" if base else None
+            if prev:
+                fc += prev + ";"
+            cur = "[m]" if base else "[0:v]"
+            for i in range(pieces):
+                nxt = "[out]" if i == pieces - 1 else f"[m{i}]"
+                fc += f"{cur}[q{i}]{ov}:eof_action=pass{nxt}" + ("" if i == pieces - 1 else ";")
+                cur = nxt
+        else:
+            fc = (f"[1:v]{pip}{','.join(chain)}[ov];"
+                  + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
         cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
             # See the --image branch above: -t (exact, bounds only the main input) instead of