ffmpeg-skill 2.12.1 → 2.14.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) |
 
@@ -420,7 +420,7 @@ The encode path a tool will actually take is Apple VideoToolbox, for h264, hevc
 
 ## FFmpeg compatibility
 
-The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only); Python 3.10+ is recommended: 3.9 still works but is deprecated since 2.10.9 (CPython 3.9 is end of life), `doctor` and the `npx` installer warn on it, and 3.0 drops it. What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). FFmpeg 6.1+ is recommended: FFmpeg 5.x still works but is deprecated since 2.14.0, `doctor` and the `npx` installer warn on it, and 3.0 requires 6.1. Python 3.10+ is recommended too: 3.9 still works but is deprecated since 2.10.9 (CPython 3.9 is end of life), `doctor` and the `npx` installer warn on it, and 3.0 drops it. What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
 
 | FFmpeg | `-filters` row layout | Source |
 |---|---|---|
@@ -527,7 +527,7 @@ FFmpeg itself:
 
 ## Requirements
 
-- FFmpeg 5.0+. Always required: `libx264`, `aac`, and the `drawtext`, `subtitles` (libass), `loudnorm`, `xfade`, `acrossfade`, `scdet`, `silencedetect` and `tile` filters. Needed only by the flags that use them: `libx265`, `prores_ks`, `libzimg` / `zscale`, `libmp3lame`, `libopus`, `libvorbis`, the `ass` filter. `doctor` tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack `libass` / `libfreetype` / `libzimg`, which `doctor` reports as missing.
+- FFmpeg 5.0+ (FFmpeg 5.x is deprecated since 2.14.0 and 3.0 requires 6.1; 6.1+ recommended). Always required: `libx264`, `aac`, and the `drawtext`, `subtitles` (libass), `loudnorm`, `xfade`, `acrossfade`, `scdet`, `silencedetect` and `tile` filters. Needed only by the flags that use them: `libx265`, `prores_ks`, `libzimg` / `zscale`, `libmp3lame`, `libopus`, `libvorbis`, the `ass` filter. `doctor` tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack `libass` / `libfreetype` / `libzimg`, which `doctor` reports as missing.
 - Python 3.10+ recommended, standard library only. 3.9 still works but is deprecated (end of life upstream; support ends in 3.0)
 - Node 16+ only for the `npx` installer
 

package/bin/install.js

@@ -55,6 +55,16 @@ function pythonDeprecation(version) {
   return version === '3.9' ? PY39_DEPRECATION : null;
 }
 
+// 2.14.0 deprecates FFmpeg 5.x the same way. The same line as scripts/_contract.py's
+// FFMPEG5_DEPRECATION (a test keeps them equal).
+const FFMPEG5_DEPRECATION = 'warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (the 5.x branches date from 2022; Ubuntu 24.04 ships 6.1); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.';
+
+// The line for `ffmpeg -version`'s first line, or null (not 5.x, or not a release number).
+function ffmpegDeprecation(versionLine) {
+  const m = /^ffmpeg version n?(\d+)\.\d+/.exec(versionLine || '');
+  return m && m[1] === '5' ? FFMPEG5_DEPRECATION : null;
+}
+
 function pythonCandidates(platform) {
   return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
 }
@@ -146,7 +156,10 @@ function checkFfmpeg() {
     console.warn('    Windows: winget install Gyan.FFmpeg\n');
     return false;
   }
-  console.log(`  found ${r.stdout.split('\n')[0]}`);
+  const first = r.stdout.split('\n')[0];
+  console.log(`  found ${first}`);
+  const line = ffmpegDeprecation(first);
+  if (line) console.warn(`\n  ${line}`);
   return true;
 }
 
@@ -211,4 +224,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { pythonCandidates, runWithPython, findPython, pythonDeprecation, warnDeprecatedPython, PY39_DEPRECATION };
+module.exports = { pythonCandidates, runWithPython, findPython, pythonDeprecation, warnDeprecatedPython, PY39_DEPRECATION, ffmpegDeprecation, FFMPEG5_DEPRECATION };

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.1`) | any release |
+| `skill.version` | the npm / package.json version (`2.14.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`
@@ -88,6 +88,11 @@ in October 2025 and gets no security fixes, but raising the floor is a break, so
 recommended: on 3.9, `doctor` and the `npx` installer print one stderr line,
 `warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (...); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.`
 Like every deprecation warning it is stderr only: `doctor --json`'s document has no key for it.
+Since 2.14.0 there is a second entry, **running on FFmpeg 5.x** (`where: behaviour`, `removed_in: 3.0.0`),
+handled the same way: `requirements.ffmpeg` stays `>=5.0` and CI keeps its 5.1.1 job until 3.0, which
+requires 6.1. When `ffmpeg -version` reads 5.x, `doctor` and the `npx` installer print one stderr line,
+`warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (...); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.`
+A version that is not a release number (a git snapshot) gets no line.
 `tests/test_contract.py` refuses a package.json major bump that still lists an entry that major should remove, or that
 comes before step 2's window has passed -- unless the waiver is written here, as 2.0.0's is.
 
@@ -123,12 +128,13 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
 ```json
 {
   "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"}],
+  "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"},
+                 {"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"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.12.1", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.14.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"},
+  "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 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},
   "execution": {"shell": false, "arbitrary_executables": false, "network": false,
                 "model_downloads": {"when": "...", "in_process": {"faster-whisper": "..."},
                                     "child_process": {"parakeet-mlx": "...", "openai-whisper": "..."},

package/package.json

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

@@ -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/_contract.py

@@ -987,6 +987,20 @@ def python_deprecation(version_info: Optional[tuple] = None) -> Optional[str]:
     return PY39_DEPRECATION if vi == (3, 9) else None
 
 
+# 2.14.0 deprecates FFmpeg 5.x the same way (DEPRECATED below): 2.x keeps running on it and CI keeps
+# its 5.1.1 job, and the line names 3.0.0 as the release that raises the floor to 6.1. bin/install.js
+# prints it too (FFMPEG5_DEPRECATION there; a test keeps the two equal).
+FFMPEG5_DEPRECATION = ("warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (the 5.x branches date from 2022; "
+                       "Ubuntu 24.04 ships 6.1); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.")
+
+
+def ffmpeg_deprecation(version: Optional[str]) -> Optional[str]:
+    """The deprecation line for this ffmpeg's version token, or None (not 5.x, or not a release
+    number: a git snapshot gets no line, as with the security advisory)."""
+    v = _parse_ffmpeg_version(version)
+    return FFMPEG5_DEPRECATION if v and v[0] == 5 else None
+
+
 def _exe_report() -> Dict[str, Any]:
     """`ffmpeg_path` / `ffmpeg_source` / `ffprobe_path` / `ffprobe_source`: which binary the tools run
     and why ("path": what PATH resolves; "homebrew-ffmpeg-full": macOS, a lean Homebrew ffmpeg on
@@ -1549,6 +1563,12 @@ DEPRECATED: List[Dict[str, str]] = [
     {"what": "running on Python 3.9 (the requirements.python floor)",
      "since": "2.10.9", "removed_in": "3.0.0", "where": "behaviour",
      "replacement": "Python 3.10 or later; on 3.9, doctor and the npx installer print a one-line warning"},
+    # FFmpeg 5.x: the 5.x branches date from 2022 and keep version-specific workarounds alive.
+    # 2.x keeps running on 5.0+ (CI still tests 5.1.1) and doctor / bin/install.js print
+    # FFMPEG5_DEPRECATION; 3.0.0 raises requirements.ffmpeg to 6.1.
+    {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)",
+     "since": "2.14.0", "removed_in": "3.0.0", "where": "behaviour",
+     "replacement": "FFmpeg 6.1 or later; on 5.x, doctor and the npx installer print a one-line warning"},
 ]
 
 # What 2.0.0 removed or changed, with the version that deprecated each: the "Removed" half of the
@@ -1787,7 +1807,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             },
             "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", "node": ">=16 (npx installer only)"},
+        "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 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
@@ -1872,8 +1892,9 @@ def main() -> int:
         # Advisories, never failures: on stderr in both modes, so `doctor --json`'s stdout stays one
         # JSON document. The FFmpeg ones are also in the document (`ffmpeg_security.warnings`); the
         # Python 3.9 deprecation is stderr-only, as every deprecation warning is (docs/contract.md
-        # "Deprecation policy" step 1), and machine-readable in `contract --json`'s `deprecated`.
-        for line in [python_deprecation()] + d["ffmpeg_security"]["warnings"]:
+        # "Deprecation policy" step 1), and machine-readable in `contract --json`'s `deprecated`;
+        # so is the FFmpeg 5.x one.
+        for line in [python_deprecation(), ffmpeg_deprecation(d.get("ffmpeg"))] + d["ffmpeg_security"]["warnings"]:
             if line:
                 print(line, file=sys.stderr)
         if args.json:

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