make-vox — layered-collage documentary shorts, end to end

Every scene is DISSECTED into separate image layers (paper board, die-cut subjects, maps, archival prints, label chips, arrows) and the TSX side choreographs the layers so they assemble on screen. Polish = many simple staggered layer moves + a virtual camera — never complex per-image animation. The visual language + architecture live in vox-shorts/DESIGN.md (read it first); this skill is the build pipeline. Proven on vox-1 (coffee).

Run everything from the repo root. Layer production needs extra Python deps (the only tools in this repo that do): pip install pillow rembg (die-cuts) and pip install playwright && playwright install chromium (HTML→PNG captures).

Artifact contract

vox-shorts/vox-N-<topic>/
  script.md        — beat sheet: per scene → on-screen layers + camera + (VO)
  scenes.json      — optional machine contract once voice lands (like beats.json)
  voice/ · sfx-plan.json · output/        (same machinery as the short-N flow) [voice/output gitignored]
remotion/src/shots/vox-N/VoxN<Name>.tsx   — THE composition
media/projects/vox-N-<topic>/layers/      — every generated layer + gen_image sidecars (committed)

Kit: remotion/src/lib/collage.tsx — CollageBoard (camera keyframes + parallax context), Cutout, ArchivalPhoto, PaperBG, LabelChip, SerifStatement, SketchArrow, Grain, VOX palette. Grow the kit generically; project-specific hacks stay in the shot.

Format

1080×1920 @30, 35–45s. The hook grammar of make-short applies: composed frame 0, loop-friendly tail, no CTA outros.

Stage 1 — script + scene dissection

Write script.md: scenes with, for EACH scene — the camera move (anchor x/y/zoom), the layer list (what image, which source, entrance + timing), annotations (chips/routes/statements). Facts verified before scripting. A scene is 2–6 layers; if you can't name the layers, the scene isn't designed yet.

Stage 2 — layer production (cheapest source that works, reuse first)

• Photographic subjects / textures / maps / archival prints → python tools/gen_image.py, then python tools/cutout.py for die-cuts (rembg auto; white-key is the no-deps fallback and FAILS on contact shadows — don't fight it, install rembg).
  • Maps/archival: prompt "NO text, no labels" — AI text is gibberish; chips annotate instead.
  • Cutout subjects: "isolated on plain white background" still helps rembg edge quality.
• Charts / UI / documents / styled text blocks → HTML file + Playwright screenshot (python tools/capture_web.py, omitBackground for alpha).
• Arrows, routes, shapes → SVG directly in TSX (SketchArrow etc.) — never rasterize.
• Layers land in media/projects/vox-N-<topic>/layers/; anything reusable by 2+ videos graduates to media/library/.

Stage 3 — TSX assembly (the choreography)

• ONE CollageBoard cam={CAM} at the root; scenes are <Sequence layout="none">s INSIDE it so the camera travels ACROSS scene boundaries. Cam keys are GLOBAL frames; entrance ats are LOCAL to their Sequence (the classic local-frame bug — check every cue).
• Persistent scenery (a map under two scenes) gets its own long Sequence; annotations get a shorter one wrapped in a fade-out so they leave before the next scene composes over them.
• Geometry pattern: place big layers via constants (MAP = {cx,cy,w}) and derive annotation positions as fractions of the layer (mapPt(0.24, 0.52)), so re-generating art only means re-eyeballing two fractions.
• Depth taste: background board −0.06, scenery 0–0.05, foreground props 0.08–0.15. Every layer keeps its idle drift (default) — nothing fully freezes.
• Contrast rule (locked): SerifStatement over any busy layer (map/photo) MUST use backing; light-accent chips (VOX.yellow) need dark kickerColor. Headlines are FONT_EDITORIAL (Source Serif 4 @700) — don't swap fonts per video.
• Hard rules (frame-based only, monotonic interpolate, Easing.bezier, <Img> never <img>) → vidtsx-2d-generator.

Stage 4 — QA (do not skip; it caught real bugs on vox-1)

cd remotion && npm run gen
node scripts/frames.mjs VoxNName <f0,entrance-cues,camera-arrivals,transitions,last> --scale=0.5

READ every PNG: every entrance landed · camera framing at each arrival (nothing critical cropped) · text contrast over its actual background · cutout edges clean (re-cutout, don't mask in TSX) · scene handoffs (fading annotations gone before the next scene needs the space). Then node scripts/render-all.mjs VoxNName --scale=1 and spot-check frames FROM THE MP4.

Stage 5 — voice

python tools/gen_voice.py --beats … --emit-ts exactly as make-short Stage 4 (word-exact captions if the format wants captions; documentary style often runs caption-free).

Stage 6 — SFX/music (suggest-sfx machinery)

Collage taste: paper slides on entrances, soft thuds on place landings, whooshes on camera moves, route-draw scribbles — sparse and editorial, decorative cues optional: true. The user's ear is the audit gate.

Done =

script.md scenes each name their layers · all layers generated + sidecars in media/projects · composition QA'd at cues and from the final mp4 · contrast rule honored · voice + SFX when requested · kit additions generic.