# Optional: AI footage (Nano Banana stills, Veo clips)

Use only when the person wants cinematic filler (a cold open, a closing, short cut-aways). It
costs money and time, so every paid step waits for their go-ahead and their picks.

## Flow

```
1. Agree the look and the subjects (ask; don't assume)            free
2. Write prompts; generate stills with Nano Banana                cheap   → stills/
3. They sort the stills into a folder they like                   wait for it
4. Animate only the chosen ones with Veo                          paid    → clips/
5. They trim hallucinations out of the clips (or tell you where)  wait for it
6. Pick ~0.5–1 s of each clip, grade and convert to plates        free    → plates/
```

Never animate before they have picked, and never animate everything "to have options": a clip
costs real money and only about a second of it ends up in the film.

## Stills with Nano Banana (`scripts/gen-images.py`)

Needs `GEMINI_API_KEY` (Google AI Studio). `gemini-3-pro-image` (Nano Banana Pro) gives the most
detail; `--aspect 16:9 --size 2K` returns about 2752×1536. API images have no visible watermark.

Prompt shape that produced realistic, usable frames (dreamy, painterly output was rejected):

```
Wide 16:9 frame. A real <subject, concrete and physical>, <one detail that shows scale or texture>,
<light: time of day, direction>. True-to-life colors, plain natural light, nothing stylized or
dreamy. Shot on 35mm film with fine grain, like a scanned slide. Photorealistic photograph, not a
painting or 3D render. The photo fills the entire frame edge to edge with no border. No text,
logos or watermark.
```

- The full-bleed sentence matters: without it some frames come back as prints with white borders
  or film-frame edges. Anything with an edge left gets an `inset` crop later.
- Macro nature (seed heads, dew, bees, leaves), landscapes of growth (fields, orchards, terraces)
  and archival-style "progress" scenes (launches, control rooms, crowds) read as optimism; avoid
  purple-tinted sci-fi.
- Midjourney often looks better but has no API and must not be automated: write prompts for the
  person to paste. End the description with `::4` and keep `--no` to 5–7 items, or Midjourney
  rejects it ("sum of all prompt weights must be positive").

## Clips with Veo (`scripts/animate.py`)

| Model | Use | Notes |
|---|---|---|
| `veo-3.1-lite-generate-preview` | default for filler | cheapest; good nature motion; no `negativePrompt` |
| `veo-3.1-fast-generate-preview` | when Lite looks off | after a burst of requests it rate-limits to roughly one every few minutes (HTTP 429); the script waits and retries |
| `veo-3.1-generate-preview` | only if asked | several times the price of fast |

- 1080p only comes as 8-second clips (4 s is 720p). Output is 24 fps with an audio track you ignore.
- Motion prompt: say what moves, how, and that it moves *from the first second* (you will use the
  start). The script appends "keep the look of the image" and "no scratches, rings, flashes, light
  leaks or film damage". Never ask Veo for film grain or scratches; it draws rings. Add grain in
  the page.
- Expect hallucinations after 2–3 s (a second rocket appears, a trail flashes and falls). Review a
  strip of frames every 0.5 s per clip, note the clean window, and let the person trim or reject.
- Retakes: tighten the prompt with what must *not* happen ("there is only one rocket; it never
  turns, flashes or falls") and add a negative prompt where the model supports it.
- People may reject stills used as fake motion in the final film ("only video clips"); keep stills
  for review, animate what makes the cut.

## Plates (`scripts/prep-plates.py`)

`plates.json` lists each plate: clip, in-point, duration on screen (0.5 s per beat; the first cut
can hold 1 s), optional inset crop. The script writes graded 60 fps JPEG sequences (and slightly
oversized stills for a slow push). The page shows the right frame per render frame
(`k.plates(schedule)` in `film-kit.js`), adds animated grain and a 1 px gate weave, and pushes each
plate in by 3–7%. One grade for all plates makes footage from different generators read as one film.

Labels over footage: one word per cut, centred, white, inside viewfinder brackets that refit to
each word and punch on the cut (`k.viewfinder`). Mirror the device at the close.