Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat(render): a video layer in overlays[] (overlay.py --video / --chromakey) (#331)
Shogo Kajiyamad889cc426dff
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6ed7300..b81e839 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,9 @@## Unreleased-(nothing yet)+### Added++- **A `render.py` project can carry a video layer (#326).** An `overlays[]` entry takes `"video": "webcam.mp4"` as a fourth kind next to `logo`/`image`/`text`, mapped to `overlay.py --video` with the same `position`/`scale`/`opacity`/`start`/`end`/`margin`/`platform` keys, plus `"chromakey"`, `"chromakey_similarity"` and `"chromakey_blend"` for green-screen removal. The layer is composited in the overlays stage, after `fit`, so its size is relative to the delivered frame and a template's safe margins apply; `--cache` keys the stage on the layer file's content, `--dry-run` plans the `overlay.py` command, and `--export-timeline` names the layer under `not_exported`. Refused before the first stage (`kind: input`): `video` with another kind in the same entry, a `chromakey*` key without `video`, a similarity or blend without `chromakey`, and a layer file that does not exist. No existing key changes meaning; a project without `video` renders as before. Reported by [@rymalia](https://github.com/rymalia).## 2.9.0diff --git a/README.md b/README.mdindex 3843f24..462908f 100644--- a/README.md+++ b/README.md@@ -257,7 +257,7 @@ These are the rules the skill file gives the agent and the code enforces.| Tool | What it does ||---|---|-| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind |+| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics and a picture-in-picture or chroma-keyed `video` layer sized for the final frame, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind || `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch`; `--jobs N` processes several files at once under one shared `--timeout` || `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list; `--switch energy` auto-cuts to whichever camera is loudest/talking instead of a hand-built list, with `--min-shot` (minimum shot length) and `--edl` (write a plain START-END cut list, not a CMX EDL; for Premiere/Resolve use `--write-project` then `render.py --export-timeline`) || `verify.py` | Run the toolchain on real device files and report PASS / FAIL per step |diff --git a/demos/build.py b/demos/build.pyindex 3a6d083..9867e76 100644--- a/demos/build.py+++ b/demos/build.py@@ -282,6 +282,19 @@ def build_fixtures(force=False):}path.write_text(json.dumps(project, indent=2, ensure_ascii=False), encoding="utf-8")+ # 9b. #326: a project with a keyed video layer, composited after the 9:16 reframe.+ path = need("project_pip.json")+ if path:+ project = {+ "output": str(OUT / "render_pip_after.mp4"),+ "frame": {"aspect": "9:16", "width": 540, "fit": "blur"},+ "clips": [{"src": str(FIX / "motion.mp4"), "in": 0, "out": 4}],+ "overlays": [{"video": str(FIX / "green.mp4"), "chromakey": "0x00b140",+ "chromakey_similarity": 0.18, "chromakey_blend": 0.05,+ "position": "bottom", "scale": 540}],+ }+ path.write_text(json.dumps(project, indent=2, ensure_ascii=False), encoding="utf-8")+# 10. A letterboxed clip: real picture in the middle, black bars top and bottom, so# cropdetect.py has something to measure and crop.py something to remove.path = need("letterbox.mp4")@@ -771,6 +784,17 @@ def demo_render_project(ctx):return before, after+def demo_render_pip(ctx):+ """#326: a video layer in a project's overlays[], keyed and placed after fit."""+ before = FIX / "motion.mp4"+ after = ctx.path("after.mp4")+ ctx.script("render.py", FIX / "project_pip.json", "--fast")+ if not after.exists():+ raise BuildError("render.py did not write %s" % after)+ ctx.note('overlays[]: {"video": "green.mp4", "chromakey": "0x00b140", "position": "bottom", "scale": 540}')+ return before, after++def demo_contact_sheet(ctx):"""look.py answers 'did that actually work?' with a picture; the 'after' side of thecomparison is that contact sheet, held as video so the gallery can show it inline."""@@ -1475,6 +1499,9 @@ _ROWS = [("render_project", PROJECTS, "Whole edit from one project file","Clips, a transition, captions and a title card described as JSON and rendered in one pass.",demo_render_project, "video", "latin"),+ ("render_pip", PROJECTS, "A keyed video layer in a project",+ "The 16:9 master is reframed to 9:16 on a blurred background, then a green-screen clip is keyed and composited at the bottom. The overlays stage runs after fit, so \"scale\": 540 is the full width of the delivered frame.",+ demo_render_pip, "video", None),("contact_sheet", PROJECTS, "Contact sheet","Twelve timecoded frames in one PNG: the fastest way to confirm an edit landed where it should.",demo_contact_sheet, "video", None),diff --git a/docs/demos.md b/docs/demos.mdindex 95799b9..20a6cd0 100644--- a/docs/demos.md+++ b/docs/demos.md@@ -646,6 +646,16 @@ python3 scripts/render.py demos/out/fixtures/project.json --export-timeline demo**Look for:** Clips, a transition, captions and a title card described as JSON and rendered in one pass.+### A keyed video layer in a project++++```bash+python3 scripts/render.py demos/out/fixtures/project_pip.json --fast+```++**Look for:** The 16:9 master is reframed to 9:16 on a blurred background, then a green-screen clip is keyed and composited at the bottom. The overlays stage runs after fit, so "scale": 540 is the full width of the delivered frame.+### Contact sheetdiff --git a/docs/demos/render_pip.gif b/docs/demos/render_pip.gifnew file mode 100644index 0000000..2d1bc01Binary files /dev/null and b/docs/demos/render_pip.gif differdiff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex f113c7e..456c5b2 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -1459,3 +1459,23 @@ not a new file format this tool would have to maintain.measured frame timing rather than on the whole-file average; `keyframe_snapped` takes`start_snapped`'s meaning (the presented start moved) and `precision` takes`least_exact_precision`'s (the least exact segment).++## Unreleased — a video layer in a project++- **`overlays[]` refuses `video` beside another layer kind, and only that combination.** A video+ layer is a fourth kind next to `logo`/`image`/`text`, as `overlay.py`'s `--logo`/`--image`/+ `--text`/`--video` are one mutually exclusive choice. An entry with a logo, an image and text+ together still draws the first of them (logo, then image, then text), as every release before+ #326 did: refusing those too would refuse projects 2.8.6 rendered. Making every combination a+ refusal is a separate change. Code: `render.check_overlay()`. Test:+ `test_render_video_overlay_refusals_and_dry_run_plan`.+- **`chromakey_similarity`/`chromakey_blend` without `chromakey` are refused in a project, though+ `overlay.py` accepts the flags alone.** The tool ignores them silently there; a project key that+ does nothing is what review 9 made a refusal (`OBJECT_KEYS`). A `chromakey*` key without+ `video` is refused as `overlay.py --chromakey` without `--video` is. Code:+ `render.check_overlay()`. Test: `test_render_video_overlay_refusals_and_dry_run_plan`.+- **A missing layer file is refused before the first stage, under `--dry-run` too.** No earlier+ stage writes an overlay video (it is the caller's file, like a clip source), so it is not a+ pending intermediate and a plan for it is no plan. A missing `image` is unchanged: a dry run+ still plans it and a real run fails in the overlays stage. Code: `render.main()`. Test:+ `test_render_video_overlay_refusals_and_dry_run_plan`.diff --git a/references/scripts.md b/references/scripts.mdindex 524915e..ec7892f 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -735,6 +735,23 @@ stem wins, and a stems level with no file to apply it to (`effects` without`"audio": {"voice": "light"|"medium"|"strong"}` picks the voice strength(`true` is `medium`).+An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or+`"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py+--video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`,+`platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to+overlay.py's flags. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and+`"chromakey_blend"` key a colour out of the video layer. The stage runs after+`fit`, so `"scale": 480` is 480 px of the delivered frame, and a template's+safe margins apply as they do to a logo. Refused (`kind: input`) before the+first stage: `video` together with `logo`/`image`/`text` in one entry (a+logo, image and text together still draw the first of them, as before), a+`chromakey*` key without `video`, `chromakey_similarity`/`_blend` without+`chromakey`, and a layer file that does not exist (under `--dry-run` too: no+earlier stage writes it). The layer's content is in the stage's `--cache`+key, so replacing the file re-runs `overlays` and what follows it; paths are+relative to the project file; `--export-timeline` lists the layer under+`not_exported`.+`"chapters"` is a chapters file path, or an inline list of `{"at": TIME,"title": STR}`; it runs `metadata.py` on the delivered file as the last stagebefore `check`, so the markers are in the file that ships (streams copied). Thediff --git a/scripts/_common/timeline.py b/scripts/_common/timeline.pyindex ad339fe..219fe9f 100644--- a/scripts/_common/timeline.py+++ b/scripts/_common/timeline.py@@ -39,7 +39,7 @@ _NOT_EXPORTED = {"silence": "the silence cut (render.py measures it at render time; the timeline keeps the clips whole)","captions": "captions (burn them with render.py, or import the .srt into the editor)","graphics": "graphics (titles, lower thirds, social templates)",- "overlays": "overlays (logos and text)",+ "overlays": "overlays (logos, images, text and video layers)","fit": "fit / reframe to the delivery aspect (set the sequence frame in the editor)","audiogram": "the audiogram picture","loudness": "loudness normalisation",diff --git a/scripts/render.py b/scripts/render.pyindex b44a3f1..169e4e8 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -22,7 +22,8 @@ Project format (all keys optional except clips):],"overlays": [{"logo": true},- {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}+ {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true},+ {"video": "webcam.mp4", "position": "bottom-right", "scale": 480, "chromakey": "0x00ff00"}],"audio": {"voice": "medium", "music": "bed.mp3", "music_volume": -16, "duck": true, "music_fade_out": 2,"effects": "sfx.wav", "stems": {"dialogue": 0, "music": -18, "effects": -22}},@@ -37,6 +38,9 @@ Stages run in this order: clips (cut) → join → silence → fit → captionsgraphics → overlays → audio → loudness → export → chapters → check. Missing stages areskipped. "brand" points caption/graphics/overlay at a brand.json (fonts,colours, logo, safe margin); {"logo": true} in overlays places the brand logo.+An overlay entry draws one of logo, image, text or video (a picture-in-picture+layer, overlay.py --video; "chromakey", "chromakey_similarity" and+"chromakey_blend" key a colour out of that video and need "video")."check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.pyitself failing to run) exits 1, same as running check.py directly would --@@ -140,8 +144,10 @@ OBJECT_KEYS: Dict[str, frozenset] = {"graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position","from", "scale", "primary", "text_color", "lang","text", "top", "bottom", "duration", "margin", "platform"}),+ # #326: "video" is a fourth layer kind (overlay.py --video), keyed with the chromakey* keys"overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity",- "scale", "font_size", "font", "font_file", "margin", "box", "platform"}),+ "scale", "font_size", "font", "font_file", "margin", "box", "platform",+ "video", "chromakey", "chromakey_similarity", "chromakey_blend"}),"audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out","gain", "duck_amount", "duck_threshold", "duck_attack", "duck_release","voice", "denoise", "duck", "music_loop", "stereo", "mono", "downmix",@@ -410,6 +416,28 @@ def check_keys(obj: Any, schema: str, label: str) -> None:else f" (valid keys: {', '.join(sorted(valid))})"))+def check_overlay(ov: Any, label: str) -> None:+ """#326: a video layer is one kind of overlay, as overlay.py's --image/--text/--logo/--video+ are one mutually exclusive choice, and the chromakey* keys only act on it. A logo, image and+ text in one entry still draw the first of them, as before; only a combination with the new+ "video" key is refused, so no project 2.8.6 rendered is refused now."""+ if not isinstance(ov, dict):+ return+ if ov.get("video"):+ others = [k for k in ("logo", "image", "text") if ov.get(k)]+ if others:+ die(f"{label}: give one of logo, image, text or video per entry, not video and {others[0]} "+ "(add a second overlays[] entry for the other layer)")+ else:+ keyed = [k for k in ("chromakey", "chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]+ if keyed:+ die(f"{label}: {keyed[0]} keys a colour out of a video layer and needs \"video\" (overlay.py --chromakey needs --video)")+ if ov.get("chromakey") is None:+ tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]+ if tuned:+ die(f"{label}: {tuned[0]} tunes \"chromakey\", which this entry does not set")++def require_object(obj: Any, label: str) -> None:"""Refuse a value that is not an object where the run reads it with .get(): "export": "reels"in a render, a string frame, a clip written as a bare path. 2.2.1 died there with a traceback@@ -470,6 +498,8 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: Odie(f"{name}[{i}]: must be an object {{...}}, got {type(item).__name__} {item!r:.60}")for i, item in enumerate(items if isinstance(items, list) else []):check_keys(item, f"{name}[]", f"{name}[{i}]")+ if name == "overlays":+ check_overlay(item, f"overlays[{i}]")if name != "clips":continue# every clip stage starts from rel(c["src"]): without one it was a KeyError traceback@@ -954,6 +984,15 @@ def main() -> int:output = rel(proj.get("output") or "final.mp4")# the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])+ if _reaches("overlays", args.stop_after):+ # #326: an overlay video is the caller's file, never an earlier stage's output, so a+ # missing one is refused here, under --dry-run too, not after every stage before it ran+ for i, ov in enumerate(proj.get("overlays") or []):+ if ov.get("video"):+ layer = rel(ov["video"])+ refuse_output_is_input(output, layer)+ if not os.path.isfile(layer):+ die(f"overlays[{i}].video: file not found: {layer}", kind="input")# 2.0 refuses an existing output without --overwrite; the final place_output() would, but# only after every stage had run -- say so before the first one instead_check_existing_output(["ffmpeg", output])@@ -1248,9 +1287,13 @@ def main() -> int:argv += ["--image", rel(ov["image"])]elif ov.get("text"):argv += ["--text", ov["text"]]+ elif ov.get("video"):+ # #326: sized and placed here, after fit, against the frame that ships+ argv += ["--video", rel(ov["video"])]else:- die(f"overlays[{i}] needs image or text")- for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform")):+ die(f"overlays[{i}] needs logo, image, text or video")+ for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform"),+ ("chromakey", "--chromakey"), ("chromakey_similarity", "--chromakey-similarity"), ("chromakey_blend", "--chromakey-blend")):if ov.get(k) is not None:argv += [flag, str(ov[k])]if ov.get("box"):diff --git a/tests/test_orchestration.py b/tests/test_orchestration.pyindex 3503509..62eede8 100644--- a/tests/test_orchestration.py+++ b/tests/test_orchestration.py@@ -659,7 +659,7 @@ class OrchestrationTests(MediaFixtures):"empty_clips": ([self._proj("render_e1.json", {"clips": []})], "clips is empty"),"captions_key": ([self._proj("render_e2.json", {"clips": full["clips"], "captions": {"size": 20}}), "--dry-run"], "captions needs text, srt or ass"),"graphics_key": ([self._proj("render_e3.json", {"clips": full["clips"], "graphics": [{"name": "x"}]}), "--dry-run"], "needs a template"),- "overlay_key": ([self._proj("render_e4.json", {"clips": full["clips"], "overlays": [{"opacity": 1}]}), "--dry-run"], "needs image or text"),+ "overlay_key": ([self._proj("render_e4.json", {"clips": full["clips"], "overlays": [{"opacity": 1}]}), "--dry-run"], "needs logo, image, text or video"),"child_failed": ([self._proj("render_e5.json", {"clips": [{"src": "source.mp4", "in": "not-a-time", "out": 2}]}), "--dry-run"], "cut.py failed"),}for name, (argv, message) in cases.items():@@ -691,6 +691,113 @@ class OrchestrationTests(MediaFixtures):self.assertIn("clip 0: missing: ", proc.stderr)self.assertNotIn("unknown key", proc.stderr)+ # ------------------------------------------------ #326: a video layer in overlays[]+ def _pip_plate(self, name, color, inset=False):+ """A 200x50 plate of one colour, 2 s; `inset` adds a white 40x40 square at (80,5)."""+ path = OUT / name+ cmd = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"color=c={color}:s=200x50:r=30:d=2"]+ if inset:+ cmd += ["-f", "lavfi", "-i", "color=c=white:s=40x40:r=30:d=2", "-filter_complex", "[0][1]overlay=80:5"]+ sh(*cmd, "-c:v", "libx264", "-pix_fmt", "yuv420p", path)+ return path++ @staticmethod+ def _rgb_at(path, x, y, at=1.0):+ r = subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-ss", str(at), "-i", str(path),+ "-vf", f"crop=2:2:{x}:{y}", "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)+ return tuple(r.stdout[:3])++ def test_render_video_overlay_is_placed_after_fit_against_the_final_frame(self):+ """#326: overlays[] took only logo/image/text, so a webcam PiP or a keyed green screen in a+ project was "unknown key 'video'", and running overlay.py before render.py sized the layer+ against the source frame. The layer is now composited in the overlays stage, after fit:+ scale 120 on a 360x640 frame is 120 px of it (on the 1280x720 source before fit it would+ have come out about 34 px wide)."""+ blue = self._pip_plate("pip326_blue.mp4", "blue")+ frame = {"aspect": "9:16", "width": 360, "fit": "pad"}+ proj = self._proj("render_pip326.json", {+ "clips": [{"src": "source.mp4", "in": 0, "out": 2}], "frame": frame,+ "overlays": [{"video": blue.name, "position": "bottom-right", "scale": 120, "margin": 0}]})+ data = json.loads(script("render.py", proj, "--fast", "--json").stdout)+ self.assertEqual(data["stages"], ["clips", "fit", "overlays"])+ out = Path(data["output"])+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))+ # 120x30 at the bottom-right corner: x 240..360, y 610..640, over the black pad+ r, g, b = self._rgb_at(out, 250, 620)+ self.assertTrue(b > 150 and r < 80, f"the PiP's left part should be blue at x=250, got {(r, g, b)}")+ self.assertLess(max(self._rgb_at(out, 230, 620)), 60, "left of the 120 px PiP the pad must remain")+ # chroma key: the green plate's green goes, its white inset stays+ green = self._pip_plate("pip326_green.mp4", "0x00ff00", inset=True)+ keyed = self._proj("render_pip326_key.json", {+ "clips": [{"src": "source.mp4", "in": 0, "out": 2}], "frame": frame,+ "overlays": [{"video": green.name, "chromakey": "0x00ff00", "chromakey_similarity": 0.2,+ "chromakey_blend": 0.05, "position": "bottom-right", "scale": 120, "margin": 0}]})+ proc = script("render.py", keyed, "--fast", "--json")+ self.assertIn("--chromakey 0x00ff00 --chromakey-similarity 0.2 --chromakey-blend 0.05", proc.stderr)+ out = Path(json.loads(proc.stdout)["output"])+ self.assertLess(self._rgb_at(out, 250, 620)[1], 80, "the keyed green must show the pad through it")+ self.assertGreater(min(self._rgb_at(out, 298, 620)), 150, "the white inset is not keyed")++ def test_render_video_overlay_refusals_and_dry_run_plan(self):+ """#326: one layer kind per entry (overlay.py's --image/--text/--logo/--video are mutually+ exclusive), the chromakey* keys only with a video, and a missing layer file named before+ the first stage -- under --dry-run too, since no earlier stage writes it. The plan carries+ the overlay.py command with the layer as an input."""+ pip = self._pip_plate("pip326_plan.mp4", "blue")+ clips = [{"src": "source.mp4", "in": 0, "out": 2}]+ cases = {+ "video_and_image": ({"video": pip.name, "image": "logo.png"}, "not video and image"),+ "video_and_logo": ({"video": pip.name, "logo": True}, "not video and logo"),+ "key_without_video": ({"image": "logo.png", "chromakey": "green"}, 'chromakey keys a colour out of a video layer and needs "video"'),+ "tune_without_key": ({"video": pip.name, "chromakey_blend": 0.1}, 'chromakey_blend tunes "chromakey"'),+ "missing_layer": ({"video": "pip326_gone.mp4"}, "overlays[0].video: file not found"),+ }+ for name, (overlay, message) in cases.items():+ proc = script("render.py", self._proj(f"render_pip326_{name}.json", {"clips": clips, "overlays": [overlay]}),+ "--dry-run", "--json", expect_fail=True)+ self.assertIn(message, proc.stderr, f"{name}: {proc.stderr[-400:]}")+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input", name)+ self.assertNotIn("cut.py", proc.stderr, f"{name}: refused before the first stage")+ # a run that stops before the overlays stage never reads the layer+ gone = self._proj("render_pip326_stop.json", {"clips": clips, "overlays": [{"video": "pip326_gone.mp4"}]})+ script("render.py", gone, "--dry-run", "--stop-after", "clips")+ # an entry with a logo, an image or text draws the first of them, as in 2.8.6+ script("render.py", self._proj("render_pip326_old.json", {"clips": clips, "overlays": [{"image": "logo.png", "text": "x"}]}), "--dry-run")+ # the plan: overlay.py with --video, and the layer is an input of its planned command+ proj = self._proj("render_pip326_plan.json", {"clips": clips, "overlays": [{"video": pip.name, "position": "top-left"}]})+ proc = script("render.py", proj, "--dry-run", "--json")+ plan = json.loads(proc.stdout)+ self.assertEqual(plan["stages"], ["clips", "overlays"])+ layer = str((OUT / pip.name).resolve()) # relative to the project file, as every project path is+ self.assertIn(f"--video {layer}", proc.stderr)+ self.assertTrue(any(layer in c and "overlay=" in c for c in plan["commands"]), plan["commands"])+ # an editor timeline cannot hold the layer, and says so+ doc = json.loads(script("render.py", proj, "--export-timeline", OUT / "render_pip326.otio", "--json").stdout)+ self.assertIn("video layers", " ".join(doc["timeline"]["not_exported"]))++ def test_render_cache_misses_the_overlays_stage_when_the_layer_video_changes(self):+ """#326: the layer file is part of the overlays stage's cache key (its content, not its+ name), so replacing webcam.mp4 re-runs the overlay and serves the earlier stages."""+ cdir = OUT / "rcache_pip326"+ shutil.rmtree(cdir, ignore_errors=True)+ self._pip_plate("pip326_cache.mp4", "blue")+ proj = self._proj("render_pip326_cache.json", {+ "clips": [{"src": "source.mp4", "in": 0, "out": 2}],+ "overlays": [{"video": "pip326_cache.mp4", "scale": 100}]})+ first = json.loads(script("render.py", proj, "--cache", cdir, "--fast", "--json").stdout)+ self.assertEqual(first["cache"]["hits"], [])+ same = json.loads(script("render.py", proj, "--cache", cdir, "--fast", "--json").stdout)+ self.assertEqual(sorted(same["cache"]["hits"]), ["clips", "overlays"])+ self._pip_plate("pip326_cache.mp4", "red") # same path, other picture+ changed = json.loads(script("render.py", proj, "--cache", cdir, "--fast", "--json").stdout)+ self.assertEqual(changed["cache"]["hits"], ["clips"])+ self.assertEqual(changed["cache"]["misses"], ["overlays"])+ r, g, b = self._rgb_at(changed["output"], 1240, 30)+ self.assertTrue(r > 150 and b < 80, f"the new red layer is the one composited, got {(r, g, b)}")+def test_render_names_every_unusable_clip_source_before_cutting(self):"""2.2.1: a missing third clip used to surface after the first two were cut, and a secondmissing clip only on the next run. Now every missing/empty source is named in one refusal."""