Asset Pipeline

---
name: asset-pipeline
description: Atelier's native asset tools — image→webp compression, video→webp frame sequences, scrollytelling scaffolding, and AI video generation (Gemini Omni Flash / Veo 3.1) with a graceful no-credentials fallback. Load when handling images, video, storytelling sections, or media generation.
---

# Asset Pipeline

## Tools

- `python <plugin>/mcp/assets/assets.py webp <image> [quality]` — any raster →
  webp beside it (Pillow). Run on EVERY raster an agent adds to `public/`.
- `python <plugin>/mcp/assets/assets.py frames <video> [fps]` — mp4 → webp
  frame sequence (needs ffmpeg; missing → tell the user the one-line install,
  continue with other work).
- `python <plugin>/mcp/assets/assets.py cut <image> [tol=32]` — flat background →
  transparent webp (samples the corner color; raise tol for gradients/noise).
- All record `asset_manifest` rows. Serve only webp to browsers.

## Transparency & icons (no model can do this — we do)

NO image model (Gemini, Imagen, DALL·E) outputs a real alpha channel. The
recipe: generate the mark on a FLAT background (the logo prompt below already
forces this), then `assets.py cut` strips it locally — free, offline, zero
credentials. Photos / complex subjects: `pip install rembg`, then
`rembg i in.png out.png` (local U2Net model, also key-free).

## Scrollytelling recipe (the storytelling primitive)

1. Storyboard scroll beats first: entry, 2–4 transitions, resolution, and the
   content pinned beside each beat. Motion supports the story; it is not a
   decorative loop.
2. Get one continuous 5–8 second source clip (user-provided in
   `workspace/references/video/`, or generate below). Locked camera direction,
   constant motion, and no cuts produce clean bidirectional scrubbing.
3. `assets.py frames video.mp4 24` → `video_frames/frame_0001.webp …`.
   Produce desktop and mobile crops when composition cannot safely center-crop.
4. Copy frames to `public/frames/<name>/`; use `templates/ScrollScrub.tsx`.
   It loads a small window around scroll position, favors scroll direction,
   evicts distant frames, caps DPR, and draws cover-fit through one canvas.
5. Ship a meaningful poster. Reduced-motion, save-data, low-memory devices,
   failed decoding, and no JavaScript receive that poster and the complete
   narrative as ordinary semantic HTML.
6. Keep headings, copy, links, and calls to action outside canvas/WebGL so they
   remain selectable, accessible, indexable, and stable before frames arrive.
7. Design-law still applies: one cinematic sequence per page. Run web-quality
   checks for overflow, reduced motion, accessibility, metadata, and SEO.

Frame delivery is progressive. Load frame zero immediately, then a bounded
forward/backward chunk near the target. Never create every `Image` at mount for
a long sequence. Use immutable, content-hashed frame URLs with long cache
headers; do not lazy-load the poster or first frame. Decode before draw, render
at most once per animation frame, and recalculate canvas size through
`ResizeObserver`, not layout reads on every scroll event.

## AI video generation — the ladder (never exit on missing credentials)

**Omni** = `gemini-omni-flash-preview`, Google's text→video model (Veo 3.1 is the
fallback family). Don't hand-roll the REST calls — the ladder is implemented:

```
python <plugin>/mcp/assets/video.py "a slow orbit around a matte black cube"
# or: from video import generate; rung, detail = generate(subject, out="hero.mp4")
```

### Verify every generation — measure, don't eyeball

```
python <plugin>/mcp/assets/verify.py hero.mp4 "#10B981" --audio
```

Prints accent coverage % and mean audio dB, exits nonzero on failure. Run it on
every generated video before showing the user. Two real defects shipped because
nobody measured: a file with a valid AAC stream that was **silent** (mean −91 dB
— "has audio" is not "is audible"), and a Veo clip whose prompt demanded one
accent while the frame read **90% emerald** against the ≤10% budget. Rewriting
the colour rule three ways brought it to 1.8%, then 0.7% — but only measuring
proved it. Report the number, never an adjective.

### Audio — silence is a choice, not a default to inherit

Veo 3+ generates **synced audio natively** (its headline feature over Veo 2).
Two things must agree or you get silence:

```python
generate("a machine room", audio="low industrial hum, distant servos")
```

This sets `generateAudio: true` in the request **and** writes the soundscape into
the prompt. Setting only the prompt does nothing — the API param governs.

`audio=False` (the default) is correct **only** for scroll-scrubbed
scrollytelling, where the browser never plays the file. For a hero, demo, or
social video, **ask the user** — do not inherit silence from the scrollytelling
recipe below. That inheritance shipped silent Veo 3 output for exactly this reason.

`generate()` returns `(rung, detail)`. Rungs 1–2 wrote the mp4 and `detail` is the
model that served it. **Rung 3 means `detail` IS the paste-prompt** — that is a
success path, not a failure: show it to the user and keep working. An expired key
falls through to the next rung instead of raising.

| Rung | Needs | Model |
|------|-------|-------|
| 1. Public Gemini API | `GOOGLE_API_KEY` | `gemini-omni-flash-preview` (live since 2026-06-30); Veo 3.1 fallback |
| 2. Vertex AI | `GOOGLE_APPLICATION_CREDENTIALS` (service-account JSON path) + `GOOGLE_CLOUD_PROJECT` + `GOOGLE_CLOUD_LOCATION` | **`veo-3.1-generate-001`** (GA) is the correct primary target. `veo-3.1-generate-**preview**` is a *different, experimental* id that 404s on most projects — mistaking it for "3.1 unavailable" is why builds silently fell back. `veo-3.0-generate-001` was slated for discontinuation **2026-06-30**: last resort only. Omni is tried first only when `audio=False` — it is silent-only and speaks the `v1beta1 interactions` API, not `predictLongRunning`; probing it the Veo way 404s and misreads as "model missing". Always report which model served. |
| 3. **No credentials** | nothing | Emit the paste-prompt below for the user's Gemini app (Omni Flash powers it for subscribers). NOT an error — say "no token, continuing" and proceed. |
| 4. Nothing works | — | Ask the user to drop any mp4 into `workspace/references/video/`. |

Credentials live in the project `.env` (gitignored — verify), written at
bootstrap. Standard var names above (they match gcloud/Vertex conventions).
Never store keys in the SQLite store or any committed file.

## The paste-prompt (rung 3 — write it FOR the user, filled in)

> Generate a short video for a website scroll animation.
> **Audio:** none — silent scroll-scrubbed footage. *(For a hero/social video
> instead, replace this line with the soundscape you want.)*
> **Subject:** <one concrete scene — object, environment, mood>.
> **Style:** premium industrial minimalism; near-monochrome palette on a dark
> `#0A0A0B` background with a single <accent color> accent; soft studio
> lighting; no on-screen text, no logos, no people (unless specified).
> **Camera:** one continuous slow <push-in | orbit | pan>, locked horizon,
> absolutely no cuts.
> **Motion:** smooth, constant speed throughout — this will be scrubbed by
> scroll, so no speed ramps, no flicker.
> **Specs:** 5–8 seconds, 16:9, highest detail.

Tell the user: paste into the Gemini app, download the mp4, drop it in
`workspace/references/video/`, then run `Atelier build` to continue — the
pipeline handles frames automatically. If Gemini refuses, simplify the Subject
line (concrete object, neutral scene) and retry once.

## Image generation — pick the model by job (same credential ladder)

| Model ID | Speed / cost | Use for |
|----------|-------------|---------|
| `gemini-3.1-flash-lite-image` (Nano Banana 2 Lite) | sub-2s, cheapest, 1K max | **bulk + drafts**: storyboard frames, icon/variant batches, layout comps, anything iterated fast; supports multi-turn local edits |
| `gemini-3.1-flash-image` | fast, up to 4K, strong text rendering | **default** for final site imagery and logos |
| `gemini-3-pro-image` | slow, premium | complex hero compositions only |

`gemini-2.5-flash-image` is legacy — never use it in new work. For
storytelling, offer the user the Lite option explicitly: a 20–30 frame
storyboard costs ~$1 and lands in under a minute, then regenerate only the
keeper frames on the default model.

## Cloudflare Workers AI — sibling image route (verified, not a replacement)

Third image-gen option alongside the Gemini ladder above, when the project has
Cloudflare credentials (`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` — same
rule as Gemini: project `.env`, gitignored, never in the SQLite store or a
commit). Two distinct routes live under the SAME endpoint family — verify
which one before promising "free":

1. **Native Workers AI models (`@cf/...`) — free, runs on Cloudflare's own
   compute.** `POST /client/v4/accounts/{account}/ai/run/{model}` — these
   models take **`multipart/form-data`, even for a text-only prompt** (a JSON
   body 400s with a generic `AiError: Invalid input`, no matter how correct
   the JSON looks — this is the one gotcha that burns an agent's first two
   attempts). Verified working: `@cf/black-forest-labs/flux-2-klein-9b`
   returns a base64 JPEG synchronously, no billing required.
   ```bash
   curl --request POST \
     --url "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/black-forest-labs/flux-2-klein-9b" \
     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     --form "prompt=<subject>" --form "width=1024" --form "height=1024"
   # response: {"result":{"image":"<base64 JPEG>"}}
   ```
   No native alpha/transparency on this route — pipe the decoded output
   through the same `assets.py cut` step as Gemini output.
2. **BYOK-proxied models (`openai/gpt-image-2`, etc.) — billed, NOT free.**
   `POST /client/v4/accounts/{account}/ai/run` (model in the JSON body, not
   the URL) with `{"model":"openai/gpt-image-2","input":{...}}`. This one DOES
   support `background:"transparent"` + `output_format:"webp"` natively (skips
   the cut step entirely) — but it 402s with `"Insufficient balance; add money
   to your gateway or use BYOK"` (code 2021) on an unfunded account. Only use
   it once the user confirms the AI Gateway has credit or an OpenAI key is
   linked — never assume it's free because it lives under `/ai/run` next to
   the native models. Full `input` params: `prompt` (required), `size`
   (`1024x1024`/`1024x1536`/`1536x1024`/`auto`), `quality`
   (`low`/`medium`/`high`/`auto`), `background`
   (`transparent`/`opaque`/`auto`), `output_format` (`png`/`webp`/`jpeg`),
   `images` (array of base64/data-URI inputs, 1-16, for edits/composites).
3. **No Cloudflare credentials, or user prefers the ChatGPT UI directly** —
   same underlying model as route 2, so the same params apply as plain
   English in the prompt: state the size, "transparent background", and
   "export as PNG" explicitly; ChatGPT's UI has no size/quality controls, the
   model reads them from prose.

Route 1 is the default recommendation (free, no gate) for icon/tile-scale
batches; keep Gemini as the default for finals needing 4K or heavy text
rendering, since Cloudflare's native catalog doesn't match `gemini-3.1-flash-image`'s
resolution ceiling.

## Logo & brand-mark generation (same ladder, image models)

When a project needs a logo/mark: rung 1–2 call the Gemini image models
above with the same credentials (`GOOGLE_API_KEY`, or Vertex with
service-account creds); rung 3 emit the universal prompt below for ANY
platform (Gemini app, ChatGPT/DALL·E, Midjourney). Always generate light + dark variants, convert to webp, and
check crispness at 16px. The mark must obey design-law: flat vector look,
hairline geometry, near-monochrome + the project's ONE accent — never
gradients, 3D, or mascots.

**Universal logo prompt (fill the brackets, works on every platform):**

> Minimal geometric logo mark for "<NAME>", a premium <what it does> company.
> Concept: <one visual idea tied to what the company means — e.g. "a loop
> whose final segment resolves into a filled square: iteration reaching
> done">. Style: Swiss / International Typographic Style, flat vector, thin
> hairline strokes of consistent 1.5px optical weight like an architectural
> schematic, generous negative space; no gradients, no 3D, no shadows, no
> mascots, no extra glyphs. Colors: ink-black strokes on off-white #FAFAF8
> with exactly ONE small filled element in <ACCENT HEX>. Must stay crisp at
> 16px favicon size. Second variant: dark mode — off-white #F5F5F3 strokes on
> near-black #0A0A0B, same accent element. Optional lockup: wordmark
> "<NAME>" in a grotesk sans, weight 500–600, all caps, +6–8% letter-spacing.

If the output has clutter, append: "absolutely no background texture, no
reflections — mark and wordmark only," and retry once.
Host integration: read [the runtime contract](../../references/runtime.md) for plugin/project paths, host command names and capabilities. Explicit user instructions and repository conventions take precedence over these defaults.