Skip to content

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.

feat(render): a video layer in overlays[] (overlay.py --video / --chromakey) (#331)

Shogo Kajiyamad889cc426dff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.0
diff --git a/README.md b/README.md
index 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.py
index 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 the
comparison 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.md
index 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
+
+![A keyed video layer in a project](demos/render_pip.gif)
+
+```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 sheet
![Contact sheet](demos/contact_sheet.gif)
diff --git a/docs/demos/render_pip.gif b/docs/demos/render_pip.gif
new file mode 100644
index 0000000..2d1bc01
Binary files /dev/null and b/docs/demos/render_pip.gif differ
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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.md
index 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 stage
before `check`, so the markers are in the file that ships (streams copied). The
diff --git a/scripts/_common/timeline.py b/scripts/_common/timeline.py
index 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.py
index 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 → captions
graphics → overlays → audio → loudness → export → chapters → check. Missing stages are
skipped. "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.py
itself 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: O
die(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.py
index 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 second
missing clip only on the next run. Now every missing/empty source is named in one refusal."""