@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/vox-director/references/local-engine.md

@@ -0,0 +1,73 @@
+# Advanced: element-level motion collage (local keyframe engine)
+
+Use this when the standard whole-poster animation isn't dramatic enough — when you want the
+**pieces-fly-in-and-assemble** look (à la cr7v2), or you must animate **real people with full
+control and zero content filters**. The video model is not used here at all; frames are drawn
+locally, so nothing is blocked and everything is exact and reproducible.
+
+The tradeoff: it's **hands-on**. Cutting the pieces and hand-placing each element's keyframes
+is the bulk of the work — decomposition and hand-placement are where most of the time goes. The engine is
+reusable; the per-video layout is manual (until an LLM auto-layout layer exists).
+
+## Two stages
+
+### 1. `extract_elements.py` — cut the poster into pieces
+Reads `<project>/elements_spec.json`:
+```json
+{"card": "<poster.png>",
+ "elements": [
+   {"name": "hero",  "bbox": [x0,y0,x1,y1], "mode": "cutout", "erase": [[x0,y0,x1,y1]]},
+   {"name": "title", "bbox": [x0,y0,x1,y1], "mode": "crop"}
+ ]}
+```
+- `crop` — rectangle kept as-is (newspaper strips, text blocks). Faster, cleaner.
+- `cutout` — crop → `youchuan/v8.1/remove-background` → transparent PNG (figures, trophies,
+  stickers).
+- `erase` — optional feathered regions to delete after cutout, in CARD coords. Needed when
+  the cutout drags in a neighbor (e.g. the player cutout also grabbed the trophy → erase the
+  trophy's box so it doesn't double with the separately-animated trophy).
+- Pick bboxes by overlaying a labeled grid on the poster and reading coordinates.
+- Clean residue: background-removal leaves color edges/ghosts — connected-components (keep the
+  largest blob), color-key, or geometric masks.
+
+### 2. `motion.py` — animate the pieces
+- **`Layer(img, keys, sway, pulse, shadow)`** — each element. `keys` is a list of
+  `dict(t, x, y, s, r, a, e)`: time, center x/y, scale, rotation, alpha, and the segment's
+  easing. `sway`+`pulse` add a low-frequency wobble / scale-breath so settled pieces aren't
+  dead-still.
+- **Easings**: `smooth/in/out` (normal), `back` (settle with slight overshoot — the paper
+  "snap" feel), `bounce` (drop-in). NOTE: `back` overshoots the target, so on scale it can dip
+  below 1.0 and briefly reveal a copy — use `out` for scale-settles over a full backdrop.
+- **Entrance helpers**: `fly_in(t0,x,y,W,H,frm,spin)` (off-screen fly + overshoot),
+  `slap(t0,x,y)` (from enlarged → snap in), `drop(...)` (bounce down),
+  `pop_settle(t0,x,y)` (focus-pop in place — opaque, scale 1.35→1.0, no off-screen travel, so
+  it never ghosts against a full backdrop).
+- **Procedural VFX** (drawn in code, keyed to the beat's palette): `starburst`, `Confetti`.
+  Confetti drifting throughout is a big part of the tactile energy.
+- **Camera**: `cam()` = slow zoom + impact shake (exponential-decay sine on entrances) + whip
+  between beats (sample from a 1.2× overscan canvas with directional blur — never affine
+  translate, or you reveal black edges).
+- **Render**: Pillow draws each frame, piped as rawvideo to ffmpeg. Supports `--only` to
+  re-render selected shots.
+
+## Making the assembly reconstruct the ORIGINAL poster
+
+The key lesson: if you scatter pieces into a *new* arrangement on a new background, the result
+stops looking like the source poster (the user will notice). To avoid that:
+- Elements rest at their **original positions** on the card (bbox center × canvas scale). The
+  canvas aspect must match the card (e.g. 3:4), so the assembled frame == the original poster.
+- Use the **original poster as the backdrop** so context/background matches.
+- **Placeholder problem**: before a flying element lands, its home spot on the backdrop would
+  show a copy (ghost). Dimming/lightening that region makes a visible dark/bright patch
+  (worse on off-color backgrounds). The fix that works: **blur that region only** — luminance
+  and color are preserved (no patch), and the sharp element flies in to "focus" it. Or inpaint
+  the region to clean background.
+
+## When NOT to bother
+If the content is non-real and "living poster" motion is enough, stay on the standard path —
+it's one prompt and fully automated. The local engine is worth it for hero pieces, real
+people, or when a client specifically wants the fragment-assembly aesthetic.
+
+Scripts: `extract_elements.py`, `motion.py`, plus `confetti.py` (overlay asset), `kenburns.py`
+(pure-ffmpeg fallback when no AI motion is available), and `mg_scrapbook.py` (a lighter
+"tilted cards on a desk + confetti + whip + ending layout" assembler).

package/skills/vox-director/references/models-and-gotchas.md

@@ -0,0 +1,91 @@
+# Models & Gotchas
+
+Everything here was learned the hard way while building this pipeline. Read it before
+debugging — most failures are already solved below.
+
+## Model selection (verify IDs live first)
+
+`GET https://api.atlascloud.ai/api/v1/models` (no auth) → keep only `display_console: true`.
+Model schemas live at `https://static.atlascloud.ai/model/schema/<id-with-slashes-as-dashes>.json`
+under `components.schemas.Input`.
+
+| Job | Model | Price | Why |
+|---|---|---|---|
+| Keyframe / collage poster | `google/nano-banana-2/text-to-image` | ~$0.08 | best CN+EN text rendering; layered look |
+| Animate — non-real content | `google/gemini-omni-flash/image-to-video` | ~$0.13 | keeps on-screen text stable, layered/parallax motion |
+| Animate — **real people/brands** | `kwaivgi/kling-video-o3-pro/image-to-video` | ~$0.095 | the ONLY one that allows celebrities/logos |
+| Element cut-out (advanced) | `youchuan/v8.1/remove-background` | ~$0.086 | `image`=URL, submit via `generateImage` |
+| Narration | `xai/tts-v1` | ~$0.015 | clean multilingual TTS; `voice_id`, `language`, `speed` |
+| Music | `minimax/music-2.6` | ~$0.11 | `is_instrumental: true`; returns ~2min, trim in mix |
+| SFX (whoosh, ambience) | `bytedance/seed-audio-1.0` | ~$0.015 | describe the sound in the `text` field |
+
+### Content blocks (architecture-level, verified)
+Feeding a recognizable **real celebrity + brand logos** into a video model:
+- `gemini-omni-flash` (both image-to-video AND reference-to-video) → **blocked**:
+  "The prompt is blocked due to prohibited contents". Removing the name from the prompt,
+  converting PNG→JPG, or using a face-less silhouette does NOT help — it's the image content.
+- `bytedance/seedance-2.0` → **blocked**: "Content suspected of infringing digital rights"
+  (only an abstract silhouette passed).
+- `kwaivgi/kling-video-o3-pro` → **allows it.** Use Kling for real people.
+- The **local keyframe engine never hits this** (no video model in the loop) — the other way
+  through for real-person content.
+
+### Voice: seed-audio needs a pinned speaker (then it's beat-stable)
+`bytedance/seed-audio-1.0` is a general *audio-scene* model, not a plain TTS. Given bare
+narration with no pinned voice it adds pauses/SFX and produced wildly inconsistent lengths
+(same 3 lines: 22s / 14s / 12s vs xai-tts's clean 8.6 / 10.2 / 9.0s). **But pinned, it is
+beat-alignable** — validated 2026-07-17 with the voice-clone template in `audio.py`
+(pinned **Speaker A** @audio1 + "clean dry studio vocal only — no background music, no
+sound effects, no room noise or reverb"): 62 words rendered in 19.3s, verbatim, one natural
+0.5s pause. The earlier "rhythm doesn't match the beats" failures were the bare-narration
+usage, not the model. Default to `xai/tts-v1` for narration; reach for seed-audio for
+voice cloning (`voice.clone_ref` → `references` payload), Chinese-specific voices, or SFX
+like transition whooshes — and always derive final timing from the ACTUAL audio (ASR word
+timestamps), never from the script.
+
+## API gotchas (Atlas, behind a proxy)
+
+1. **Every request MUST send a real `User-Agent` header** — default Python `urllib` UA is
+   blocked by the WAF → 403 Forbidden. (`scripts/atlas_cloud.py` sets one.)
+2. **Download generated assets with curl, not urllib** — the OSS host behind the local proxy
+   kills `urlretrieve` with `RemoteDisconnected`.
+3. **Audio/TTS/music/video all submit via `POST /api/v1/model/generateVideo`**, image &
+   background-removal via `/generateImage`; poll `/model/prediction/{id}`.
+   (A playbook noted a `/generateAudio` endpoint — go by what the live schema/API accepts.)
+4. **A failed generation makes the prediction GET return HTTP 500** (not a clean
+   `status:failed`) — treat a persistent 500 on poll as a failure, and read `message` for the
+   reason.
+5. POST generation calls are **not** retried (they create billable tasks); GET polls are.
+
+## ffmpeg gotchas (this machine's build)
+
+The local ffmpeg is minimal: **no libass, no drawtext** (no libfreetype). So:
+- **Captions & watermark → render PNGs with Pillow and composite via `overlay`**
+  (`scripts/text_overlay.py`). Size text by `min(W,H)` so it works in 16:9 and 9:16.
+- **Off-aspect clips** (e.g. a 3:4 card in a 9:16 frame): use a blurred-cover background +
+  fitted sharp foreground via `overlay`, not black bars.
+- **Slow, don't freeze**: if a clip is shorter than its narration-driven segment, stretch it
+  with `setpts` to fill instead of `tpad` freezing the last frame.
+- **`blend` needs both inputs in the same pixel format** — convert both to `gbrp` before a
+  `screen` blend (confetti overlay) or the whole frame turns magenta.
+- **`sidechaincompress` output length follows its sidechain** — `apad` the narration track to
+  the full duration, or `-shortest` will cut a music-only ending (e.g. a scrapbook outro).
+- **Whip transitions**: `xfade` slides between shots; recompute each beat's start time
+  (each transition overlaps by the transition duration) so narration/captions stay in sync.
+- **Verify by extracting frames** — you can't read an mp4's content. `mjpeg` refuses
+  full-range YUV, so add `format=yuvj420p` when grabbing jpgs.
+
+## Host mode (Seedance reference-to-video + Omni, keyed)
+
+- Seedance takes `reference_images` / `reference_audios` (not `images`), `ratio` (not
+  `aspect_ratio`), and a reference audio of 2-15 s. Omni takes `image` + `aspect_ratio` and is
+  only verified to 10 s.
+- Pricing units differ and the catalog `base_price` is NOT a per-second price: Seedance is
+  billed per token (720p about $0.194/s after promo, list $0.2429), Omni $0.13/s with a 3 s
+  minimum, nano-banana by resolution (1k $0.08, 2k $0.12). Read the model page, not the field.
+- Full recipe and rules: `references/host-mode.md`.
+
+## Cost
+
+A ~30s standard film ≈ **$0.8–1.0** (6 keyframes + 6 clips + VO + music). The element-level
+advanced path is pricier (~$1.5) because of ~15 background-removal calls.

package/skills/vox-director/references/prompt-guide.md

@@ -0,0 +1,275 @@
+# Prompt Guide — the heart of the Vox collage look
+
+Two prompts decide whether the film reads as a real Vox collage or a moving poster: the
+**image prompt** (makes the collage look) and the **video/motion prompt** (makes it move like
+collage). Get these right and the rest is plumbing.
+
+This one file is the whole **LOOK layer** — the prompt *structures*, the *vocabulary* that
+fills them, and the ready-made *theme presets*. (The **STORY layer** — narrative arcs, pacing,
+shot patterns — is its counterpart `beat-layer.md`.)
+
+Everything below sits on top of the **common Vox constraints** (never drop these):
+> torn/scissor-cut paper edges · tape · halftone dots · newspaper clippings · paper-stencil
+> shapes · real paper drop-shadows · bold flat color · PRINTED/illustrated cut-outs · **NOT
+> 3D, NOT CGI, NOT photoreal** · keep print grain · headline text baked in **"quotes"**.
+
+- [1. Image prompt — structure + vocabulary](#1-image-prompt)
+- [2. Video / motion prompt — structure + vocabulary](#2-video-prompt)
+- [3. Why layering the image is what unlocks good AI motion](#3-layering)
+- [4. Real people](#4-real-people)
+- [5. Theme presets — combine the dimensions](#5-themes)
+
+---
+
+## 1. Image prompt
+
+The collage look is *born here*. On the standard (whole-poster-animation) path this single
+image carries the entire aesthetic, so invest in it. Structure every image prompt in 5 parts:
+
+```
+[1 STYLE BLOCK — identical on every beat]
+  Mixed-media hand-cut PAPER COLLAGE, editorial zine style. Torn/scissor-cut paper edges,
+  tape corners, halftone print dots, newspaper clippings, paper-stencil shapes, real paper
+  drop shadows. Figures are PRINTED-texture cut-outs of real imagery (photo / woodblock /
+  mural), NOT CGI, NOT a 3D render — keep print grain and paper imperfections. High-contrast.
+
+[2 SCENE — describe as SEPARATE cut-out pieces]
+  SCENE as layered paper cut-outs: {main subject}, {a prop}, {a text strip}, {a decorative
+  scrap}; elements have clear edges, distinct layers, each with its own drop shadow.
+
+[3 BACKGROUND — one bold flat color]
+  on a bold flat {bg color} paper background.
+
+[4 HEADLINE — baked in, short + bold]
+  A torn-paper banner with a big bold headline "{TITLE}" (+ small subtitle), plus a red seal.
+
+[5 TECH]
+  aspect ratio {16:9|9:16|3:4}, 2k resolution.
+```
+
+### Techniques
+- **Reuse the style block verbatim on every beat.** Only the scene, bg color and headline
+  change. This is what makes 6 different beats feel like one film.
+- **Describe distinct pieces with visible edges + shadows.** Two reasons: it looks assembled
+  (collage, not a smooth painting), and it gives the *video* model separable layers to
+  parallax (see §3). A blended scene can only be panned as one flat plane.
+- **Bake the headline text into the image** — image models render crisp text; video models
+  smear it. Keep it short, bold, 2–3 words.
+- **Bold flat background color, one per beat.** Busy backgrounds muddy the cut-out silhouettes
+  and kill the Vox punch. Let the palette travel across beats to carry mood (see the color
+  axis below): e.g. aged sepia → bold pop colors → champion gold.
+- **Say "NOT 3D / NOT CGI, printed texture, keep grain"** or the model drifts toward smooth
+  render-CGI and loses the paper feel.
+- **2k** so cut-outs stay crisp if scaled/animated.
+- Keep a **consistent paper-texture language** across beats (edge roughness, halftone
+  density); color can change, texture shouldn't.
+
+### Worked example (2008 "KING OF EUROPE" beat, deep-red)
+> Mixed-media hand-cut PAPER COLLAGE, editorial zine style; torn edges, tape, halftone dots,
+> newspaper clippings, paper-stencil texture, real drop shadows; PRINTED-texture cut-outs, NOT
+> 3D/CGI, keep print grain. SCENE as layered paper cut-outs: a roaring footballer in a red
+> kit, a gold trophy, a big cut-out "7", a torn "KING OF EUROPE" newspaper strip, a club
+> crest, scattered geometric scraps — clear edges and drop shadows. Bold flat deep-red paper
+> background. Torn-paper banner headline "KING OF EUROPE" + small subtitle, red seal. 3:4, 2k.
+
+### The image dimensions (pick one term per axis to fill the structure)
+The style block above is the default. To differentiate a topic — or compose a custom theme —
+choose a term from each axis. (⭐ = the strongest theme levers.)
+
+| Dimension | Controls | Vocab bank (mix & match) |
+|---|---|---|
+| **Medium/technique** | the strongest style lever | paper collage · torn-paper collage · photomontage · screenprint · **risograph** · letterpress · linocut/woodcut · lithograph · halftone print · gouache · flat vector · photocopy/xerox · rubber-stamp |
+| **Art movement / era** ⭐ | single best "theme knob" — shifts palette+type+layout at once | Swiss/International Typographic · Bauhaus · mid-century modern · Russian Constructivism · Dada photomontage · Pop Art · psychedelic '60s · punk zine · Memphis · Art Deco · WPA/vintage travel poster · Soviet · atomic-age · retro-futurism |
+| **Composition/layout** ⭐ | poster hierarchy + negative space | modular grid · asymmetric · strong negative space · diagonal dynamic · foreground–midground–background depth · hero headline + subhead hierarchy · full-bleed · radial · stacked bands · off-center focal |
+| **Color palette** ⭐ | cleanest theme distinguisher (stops muddy gradients) | limited 2–3 color · duotone · monochrome + 1 accent · **riso fluorescent-pink + federal-blue** · Bauhaus primaries (red/yellow/blue) · '70s mustard/rust/avocado · '60s pop (hot-pink/orange) · teal-&-orange · CMYK process · cream/kraft base · neon-on-black · named hex (e.g. `#0047AB`) |
+| **Typography treatment** ⭐ | headline LOOK (we only passed the words) | **put exact words in "quotes"** + name a REAL type style: bold condensed grotesque (Helvetica/Akzidenz) · geometric sans (Futura/Bauhaus) · slab serif · '70s display serif · wood-type · hand-lettered · **ransom-note cut-out letters** · stencil · all-caps · knockout/reversed · huge headline + small caption |
+| **Print finish / texture** | "made by hand, not AI-slick" | halftone dots · **Ben-Day dots** · riso ink misregistration/overprint · letterpress deboss · newsprint · kraft/cardstock · aged/foxed paper · fold creases · coffee stains · deckled vs scissor-cut edges |
+| **Lighting / capture** | keeps it "scanned" not "rendered" (anti-3D) | flat even studio light · shadowless scanned-document light · straight-on/head-on · flat-lay top-down · subtle paper drop-shadows |
+| **Mood** | tone anchor | playful · bold · urgent · editorial/serious · nostalgic · optimistic · ominous · satirical · activist/protest |
+
+**One-line image structure** (consensus of Nano-Banana/Ideogram/OpenAI/Flux — Ideogram is
+"format-first", best for baked text):
+`[MEDIUM] + [ART MOVEMENT/ERA] of [SUBJECT + SCENE], [COMPOSITION/hierarchy/negative space],
+[straight-on scanned-flat framing] + [flat even light, paper drop-shadows], [named limited COLOR
+PALETTE], [PRINT FINISH/texture], headline "EXACT WORDS" in [NAMED TYPE STYLE] [placement], [MOOD],
+[aspect]` — then per model: Omni/Nano-Banana/Flux/DALL·E take **no negatives** (phrase positively);
+SDXL needs a negative field; Midjourney uses `--no` + params last.
+Sources: Nano-Banana https://deepmind.google/models/gemini-image/prompt-guide/ · Ideogram
+https://docs.ideogram.ai/using-ideogram/prompting-guide/2-prompting-fundamentals · OpenAI
+https://developers.openai.com/cookbook/examples/multimodal/image-gen-models-prompting-guide · Flux
+https://docs.bfl.ml/guides/prompting_summary · Midjourney https://docs.midjourney.com/hc/en-us/articles/32859204029709-Parameter-List
+
+---
+
+## 2. Video prompt
+
+The motion prompt turns "pan a poster" into "a living collage". Use the **5-axis** structure
+(this is the structure from the reference cr7 Omni prompt — all five axes matter, especially
+**feel** and **color**, which set mood and palette movement):
+
+```
+[GOAL] Animate this still into a mixed-media collage MOTION GRAPHIC. Keep it flat 2D paper,
+       NOT 3D, no photoreal.
+
+[AXIS 1 · CAMERA]   one smooth continuous move for this shot: {slow push-in | lateral
+                    parallax pan | slow rise}.
+[AXIS 2 · MOVEMENT] layered paper cut-outs drift with visible drop-shadow parallax; elements
+                    and geometric scraps bob/settle gently on the beat; halftone dots pulse;
+                    torn edges and tape flutter; a breathing quality.
+[AXIS 3 · AESTHETIC]preserve the torn-paper / tape / halftone / newspaper / paper-stencil
+                    textures exactly; keep the bold flat background.
+[AXIS 4 · FEEL]     {emotional tone of this beat} — e.g. tender / triumphant / cinematic
+                    editorial, "a page from a scrapbook".
+[AXIS 5 · COLOR]    {this beat's palette}, high contrast; if part of an arc, name where it
+                    sits (aged sepia → bold pop → champion gold).
+
+[CONSTRAINTS] keep the layout, the seal and ALL on-screen text perfectly stable and legible;
+              ONE smooth continuous move — absolutely NO sudden zoom snaps, NO jump-cuts, NO
+              teleporting/re-framing inside the shot; no new objects, no morphing, no drift.
+```
+
+### Techniques
+- **The MOVEMENT axis is the lever** that makes Omni move *layers* (parallax) instead of
+  sliding the whole frame. Name the layered paper motion explicitly.
+- **FEEL and COLOR are not decoration** — they steer the model's pacing and grade. A "tender,
+  sepia" beat animates slower and warmer than a "triumphant, gold" beat. Don't drop them.
+- **The CONSTRAINTS axis prevents the common breaks**: text wobble, 3D drift, and the big one
+  — internal jump-cuts.
+- **Never write "snap / punch-in / slam / quick zoom".** Omni over-reacts and generates a
+  jump *inside* the shot that reads as a one-frame flash. Ask for ONE smooth continuous move.
+- **Don't rely on the video model for text** — it's already baked in the keyframe; just tell
+  the model to keep it stable.
+- **One move per shot.** For richer editing, cut between multiple short shots (wide + detail)
+  rather than asking one clip to do a complex timeline.
+
+### The full axis vocabulary (the 5 axes above, expanded with the STABILITY axes)
+The core 5 axes set mood and motion; the extra axes below (⭐⭐) are what actually control
+STABILITY — they fix the loop / text-wobble / morph failures. Pick phrasing per axis.
+
+| Axis | Controls | Vocab / phrasing |
+|---|---|---|
+| **Motion amplitude** ⭐⭐ | THE anti-morph/anti-text-warp lever | `very subtle` · `minimal` · `moderate` · "~5% movement" · avoid `intense/large/explosive` near text |
+| **Camera move** | how the camera travels | **safe for flat paper:** static/locked-off · slow push-in/pull-out · slow pan/tilt · subtle parallax truck. **Bold (bend 2D toward fake 3D, use with `constraints: loose` + re-roll):** orbit · crane · dolly-zoom · roll · 3D arc |
+| **Shot size / angle** | framing | full poster in frame (default) · slow push to a detail · **eye-level straight-on (default)** · overhead (reads as paper on a table) |
+| **Element motion** | what moves inside | **safe paper-native verbs:** drift · sway · ripple · flutter · slide · pivot (rigid) · bob · pulse · shimmer · settle · parallax between layers. **Bold (loose + re-roll):** warp · transform · morph · vortex · explode |
+| **Speed / easing** | tempo | slow · gentle · continuous · ease-in-ease-out · (risky: quick/snap/whip) |
+| **Lighting-over-time** | best "safe motion" for flat art | soft light sweep across the surface · gentle shadow drift · subtle flicker/glow pulse |
+| **Dimensional lock** ⭐ | keep it flat | "flat 2D, camera parallel to the poster, no 3D rotation, no perspective change; paper layers parallax only, elements slide/pivot as rigid flat paper, do not bend or morph" |
+| **Stability anchors** ⭐⭐ | protect text/layout | "the printed headline, logo and layout stay sharp, legible and perfectly stable — do not redraw, distort or move the lettering" |
+| **Shot structure** | cuts / loop | "single continuous shot, no cuts, no scene changes" · one-way: add a **motion endpoint** ("…then settles into place") · seamless loop: say "looping video" (Luma) |
+
+### Best-practice rules that fix our bugs (all from official guides)
+1. **Describe motion, not the picture.** The still already has subject/scene/text/style —
+   restating them (esp. the text) makes the model re-synthesize and warp them. (Runway, Veo, Kling.)
+2. **One camera move + one action per shot.** Multiple simultaneous moves = instability/morph.
+   (Sora, Seedance: "specify only 1 type of camera movement… increases image instability".)
+3. **Keep amplitude small; motion physically plausible.** (Kling, Seedance: "slow, gentle,
+   coherent subtle movements… avoid high-burst, large-dynamic actions".)
+4. **Positive phrasing only for Omni/Veo/Runway** — "no/don't" backfires ("may result in the
+   opposite"). **Kling & Seedance DO support negative prompts.** Know your model.
+5. **Text:** don't ask the video model to render text; anchor it as stable; keep motion away
+   from the text region; **for critical text, overlay in post.** (Cross-source.)
+6. **Anti-loop:** give a one-way move a settle endpoint, or say "single continuous"; short
+   clips shouldn't over-script per-second beats. (Kling, Runway Gen-4.)
+7. **Flat-collage:** name the style ("flat 2D paper cutout animation, rigid paper layers")
+   and lock dimensionality → steers the model away from 3D morphing. (Storyblocks + rules above.)
+
+**One-line video structure** (I2V, adapted): `[SHOT SIZE+ANGLE] + [CAMERA MOVE + AMPLITUDE] +
+[ELEMENT MOTION + SPEED/EASING] + [LIGHTING-OVER-TIME] + [AESTHETIC/TEXTURE + DIMENSIONAL LOCK] +
+[FEEL] + [COLOR] + [STABILITY ANCHORS] + [SHOT STRUCTURE/LOOP]`.
+Sources: Runway https://help.runwayml.com/hc/en-us/articles/39789879462419 · Kling I2V
+https://kling.ai/quickstart/image-to-video-guide · Seedance https://docs.byteplus.com/en/docs/ModelArk/2222480 ·
+Veo https://cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1 ·
+Sora https://developers.openai.com/cookbook/examples/sora/sora2_prompting_guide · StudioBinder camera
+glossary https://www.studiobinder.com/blog/different-types-of-camera-movements-in-film/
+
+---
+
+## 3. Layering
+
+Common question: *"can I feed a background + separate component images to the video model to
+get dramatic component motion?"* In practice, no — Omni/Kling `reference-to-video` is
+**generative**, not a layer compositor: it reinterprets the refs and invents its own motion,
+so you get *less* control, not more. For controlled per-element choreography, use the local
+engine (`references/local-engine.md`).
+
+But there's a real lever within the standard path: **the more clearly layered your keyframe
+is, the more layered motion the video model can produce.** Distinct cut-outs with edges and
+shadows → the model can drift them at different depths (parallax) → "living collage". A flat,
+blended image → only a whole-frame pan is possible. So push the *layering* in the image
+prompt (§1) if you want livelier auto-motion.
+
+---
+
+## 4. Real people
+
+Real-person keyframes are fine to *generate* (use web-search grounding or a reference photo
+with an edit model to anchor the face). The catch is *animation*: Google (Omni) and ByteDance
+(Seedance) refuse recognizable celebrities / brand logos ("prohibited contents" /
+"digital-rights"). Two ways through:
+- **Kling O3 pro** allows real people — set it as `video_model` (simplest).
+- **Local engine** — animating cut-outs frame-by-frame never touches a video model's content
+  filter, and gives full control. Best when you also want dramatic element choreography.
+
+---
+
+## 4b. C-roll anchor locks (photo → poster, validated 2026-07-17)
+
+C-roll's whole trick is one photographic sticker that never gets redrawn while the paper
+world is generated around it. Three lock templates, each earned by a failed generation
+(`croll_keyframes.py` bakes them in — reproduced here for hand-run prompts):
+
+**FACE LOCK (portrait).** "Her/his face and hair from the attached photo are cut out as a
+PHOTOGRAPHIC sticker with a torn white paper border — keep the facial identity, features and
+the exact expression from the photo pixel-faithful; do not redraw, repaint or stylize the
+face; NO halftone dots, print texture or ink treatment on the face or hair. All poses and
+gestures are expressed by the body only. From the neck down the body is a hand-drawn
+paper-doll illustration jointed like a vintage paper puppet, FULLY CLOTHED in {outfit}."
+- *Poses go to the body only*: asking the model for a wink or a smile redraws the face.
+- *Scope halftone to the background* or the print dots bleed onto skin.
+- *Lock the clothing* or the paper-doll body drifts (one run produced a bare mannequin).
+
+**PRODUCT LOCK.** "{The product} from the attached photo is cut out as a PHOTOGRAPHIC
+sticker with a clean scissor-cut edge and a soft real paper drop shadow — keep its exact
+shape, materials, surface reflections and every word of its label typography pixel-faithful.
+Do not redraw, restyle or repaint the subject or its label. Re-style ONLY the world around
+it as printed paper collage."
+
+**ANCHOR FREEZE (the video stage).** Image-edit keeps label typography intact, but the
+image-to-video stage can quietly re-letter it (observed: "PARFUM" → "PAREUM") or re-time a
+face. Every C-roll motion prompt therefore carries a freeze line — "the photographic
+sticker (and every letter of its label) is a frozen layer, pixel-identical to the still for
+the entire duration" — written into beats.json as `anchor_freeze` and injected by
+`clips.py`. Extract a frame per clip and re-check the letters anyway.
+
+Note the permission split (same spirit as A-roll's face rule): edit models will *carry* a
+real face/product verbatim but Omni refuses to *repaint* one — a halftone-textured face was
+rejected at the video stage regardless of phrasing, and Kling accepts it but drifts the
+identity. Photographic-sticker treatment is the reliable lane.
+
+---
+
+## 5. Theme presets — combine the dimensions
+
+A **theme preset** = one pick from each image dimension (§1) + a motion preset (§2), on top of
+the common Vox constraints. This is how we offer "different theme options" without
+hand-writing each prompt. The library (`styles.THEME_PRESETS`):
+
+| Preset | Era/movement | Palette | Type style | Print finish | Motion preset | Fits topics |
+|---|---|---|---|---|---|---|
+| `american-retro` | 1950s US ad/pulp | bold retro primaries | wood-type / bold slab | halftone, aged | punchy | ads, sports, business, money |
+| `swiss-modern` | Swiss/Intl Typographic | 2-color + red accent | Helvetica/Akzidenz grotesk | clean flat, subtle grain | calm | tech, finance, explainers |
+| `punk-zine` | 90s punk/DIY | B&W + 1 spot color | ransom-note cut letters | photocopy, misregistration | punchy/max | rebellion, music, counterculture |
+| `soviet-constructivist` | Russian Constructivism | red/black/cream | bold condensed diagonal | letterpress, newsprint | punchy | politics, revolution, industry |
+| `wpa-propaganda` | 1930s WPA poster | muted 3-color | stencil / gothic | screenprint grain | calm | history, labor, public health |
+| `70s-groovy` | 1970s | mustard/rust/avocado | bulbous display serif | riso grain | punchy | culture, food, nostalgia |
+| `chinese-ink` | Chinese woodblock/ink | ink + vermilion | Chinese brush + red seal | rice-paper, seal | calm/punchy | Chinese history/culture |
+| `atomic-age` | 1950s futurism | teal/orange/cream | atomic script | halftone | punchy | science, space, future |
+| `newsprint-editorial` | mid-century front-page news feature | cream/deep red/mustard/charcoal | bold condensed newsprint headline | aged paper, heavy halftone | punchy | news, AI/tech explainers, editorial features |
+| `gilded-deco` | 1920s art-deco luxury advertisement | aged cream/champagne gold/charcoal | elegant didone serif, wide tracking | gold foil, fine halftone | calm | luxury goods, perfume, watches, heritage brands |
+
+**How to use:** the agent reads the topic → suggests 3–4 fitting presets (or composes a new one
+by mixing the banks in §1–§2) → `style_bakeoff.py` renders one beat in each → the user picks. The
+picked preset's fields drop into the image prompt (via `collage_style` + palette/type/finish) and
+its `motion_style` into the video prompt. The common Vox constraints and stability anchors are
+always on.

package/skills/vox-director/references/voices.md

@@ -0,0 +1,59 @@
+# Voice roster — `xai/tts-v1` (pick a `voice_id` per film)
+
+Set `voice.voice_id` in beats.json. **Pick by the film's LANGUAGE first, then match gender/tone
+to the topic** — don't just leave the default.
+
+- **Multilingual** voices (`ara eve leo rex sal`) speak ANY language — safe for English/Chinese/mixed.
+- **Native** voices are optimized for their own language (more natural accent) and auto-cascade the
+  `language` field.
+- Skill default: **`leo`** (male, multilingual, documentary-ish). Override per film.
+
+## Multilingual (any language)
+| id | name | gender |
+|---|---|---|
+| `leo` | Leo | M — default |
+| `rex` | Rex | M |
+| `sal` | Sal | M |
+| `ara` | Ara | F |
+| `eve` | Eve | F |
+
+## Native voices by language  (name · gender · id)
+- **en** — Daniel · M · `96819d0bd28d` · James · M · `78a495fdbb39` · Grace · F · `f8cf5c2c78d4` · Claire · F · `79f3a8b96d43`
+- **zh-CN** — Jian · M · `jpi39icg` · Hao · F · `d18jlf6v` · Xia · F · `33g9t0jl`
+- **ja** — Ren · M · `b1a7441b97a1` · Sakura · F · `d0cb9ff07d95`
+- **ko** — Jun-seo · M · `bf9fe5b5f981` · Min-jun · M · `b5ae17439907` · Ji-yeon · F · `23be42535a45` · Seo-yeon · F · `a0401c9101f8`
+- **es** — Manuel · M · `yis75yfp` · Javier · M · `ekhwx401` · Andres · M · `0hhfxxqq` · Diego · `jupvcf34`
+- **fr** — Remi · M · `0p0rt7o1` · Hugo · `hbxkrnwm` · Camille · F · `69smp8rm`
+- **de** — Moritz · M · `41321eb41295` · Niklas · M · `40f31906b23d` · Clara · F · `458705c07139` · Lena · F · `3a7889066fa2`
+- **it** — Enzo · M · `x7avnu1k` · Matteo · M · `bcs7l2c3` · Alessandro · M · `h27ltdnz` · Luca · F · `hqxr4yub`
+- **pt** — Mateus · M · `abfbdf26f115` · Rafael · M · `3d030bc92a87` · Beatriz · F · `6da5baee46d0`
+- **ru** — Dmitri · M · `wy0m9l5w` · Andrei · M · `dr8gqysu` · Pavel · M · `26w6ihxi` · Irina · F · `om17cury`
+- **hi** — Karan · M · `89q2pnko` · Ananya · F · `73xd5dum`
+- **ar** — Khalid · M · `70013edeb8e8` · Tariq · M · `23468361b4ef` · Layla · F · `35c8d7f60dc8`
+- **tr** — Emre · M · `670a0c3ac005` · Kaan · M · `182a91893636` · Aylin · F · `d634b6da3d3b`
+- **vi** — Duc · M · `fc7de6afcf6c` · Minh · M · `7a9ee820b342` · Mai · F · `0895a5b8ce5c`
+- **th** — Aroon · M · `4ff93971bfdc` · Krit · M · `908c4626660f`
+- **nl** — Thijs · M · `a13662ba951c` · Ruben · M · `244e27b39200` · Femke · F · `58d27475085e` · Noor · F · `247783ebdd51`
+- **pl** — Jakub · M · `2badb5f46b1e` · Mateusz · M · `37329fd8895a` · Aleksandra · F · `1b12d5daee6b` · Katarzyna · F · `97fabd54445f`
+- **sv-SE** — Axel · M · `e22152e06fd8` · Erik · M · `1f046a033914` · Saga · F · `490ea3be50b1`
+- **da** — Kasper · M · `0ih5oi34` · Lars · M · `gwnexu6y` · Ida · F · `97zmdc6s`
+- **fi** — Eero · M · `83c6f4fea98e` · Valtteri · M · `dfe7b9e7d217` · Elina · F · `34fd4dce1ba3` · Helmi · F · `c3a2c594479e`
+
+## How to pick (per scenario)
+1. **Language** — match the film's `language`. For a non-English film, prefer that language's native
+   voice for the best accent (e.g. Chinese history → `Jian`/`Hao`); or use a multilingual voice and
+   set `language` explicitly.
+2. **Gender + energy to the topic** — documentary/authoritative → `leo`/`rex`; warm/inviting → `sal`/`ara`;
+   bright/female lead → `eve` or native `Grace`.
+3. Keep ONE voice for the whole film (consistency). Set it once in `voice.voice_id`.
+
+Example: `"voice": {"voice_id": "grace", "language": "en", "speed": 1.0}` → wait, use the id:
+`"voice": {"voice_id": "f8cf5c2c78d4", "language": "en", "speed": 1.0}` (Grace, native English female).
+
+## Voice cloning (seed-audio)
+
+To narrate in a real person's own voice, set `"voice": {"clone_ref": "path/to/sample.mp3",
+"language": "en", "persona": "YouTube tutorial creator"}` — narration switches from xai/tts-v1
+to `bytedance/seed-audio-1.0` with the sample pinned as @audio1 (template in `audio.py`;
+timing validated beat-stable). A clean 20–60s solo-voice sample works best. `persona` tunes
+delivery (e.g. "calm documentary narrator", "luxury brand voice-over").