# The brief and the budget

## Ask once, then run

Collect everything in one round, then produce without stopping until the priced storyboard needs its sign-off:

- Team and project (see the `scenario` skill), the product shot, and brand assets: logo file, brand colors, font file if exact type matters, any character or mascot reference.
- One objective: awareness, consideration, or conversion. Refuse to storyboard a brief carrying two: brand-building wants pure emotion and activation wants demo plus offer, and one asset cannot do both jobs (Binet and Field's IPA work is the citable basis). Offer two cuts from one board instead.
- The audience as a person with a current mindset, not a demographic. A useful test is the Get/Who/To/By line: get (audience) who (mindset) to (one observable behavior) by (the lever). If the line would survive pasted onto a competitor's brief, sharpen it.
- The single-minded proposition: the one reason to buy, in one sentence. Viewers catch one message; a list of benefits lands as none.
- The two dials below, platforms and ratios, mandatories (legal lines, claims that must appear, forbidden imagery), and a spend ceiling in creative units.

## The two dials

| Dial       | Levels                                                  | Meaning                                                                                                                                                                                                                                                   |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Creativity | `on-code` / `twist` (default) / `wild`                  | on-code plays the category's visual codes straight; twist opens inside the code and breaks one beat (the Kenzo World pattern); wild is concept-led and discards codes, which risks the category no longer reading as itself: flag that before proceeding. |
| Length     | `6s` bumper / `15s` short / `30s` full (60s on request) | 6s: 2 beats, 8 to 12 VO words. 15s: 4 to 6 beats, 30 to 35 words. 30s: 6 to 8 beats plus inserts, 60 to 70 words. Longer levels cost more in every stage.                                                                                                 |

## Objective to rulebook

| Objective     | Grammar                                                                                     | Default length | KPIs                                 | CTA                                            |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- | ------------------------------------ | ---------------------------------------------- |
| Awareness     | Brand film: world-building, emotion, brand codes visible early and throughout               | 15 to 30s      | Reach, view-through, hook rate       | Brand beat end card, soft CTA                  |
| Consideration | Demonstration: one provable claim, proven visually (the Epic Split pattern)                 | 15 to 30s      | Click-through, engagement, view rate | Benefit line plus CTA                          |
| Conversion    | Performance: hook in the first 3 seconds, product and text in frame one, offer made plainly | 6 to 15s       | Click-through, cost per action, ROAS | Explicit text CTA, end card, offer in captions |

Hook rate (3-second views over impressions) is the creative diagnostic to name: treat a quarter to a third of viewers surviving the hook as a healthy planning target, higher for retargeting than cold audiences. Expect few variants to win, which is why hooks get alternates and the rest of the board does not.

## Pricing the board

1. Shot count: performance cuts run one shot per 2 to 3 seconds; brand films run fewer, longer beats. Add 2 to 3 inserts.
2. Variants: 3 alternates for the hook shot, 1 take planned everywhere else.
3. Retry floors (planning assumptions, not industry averages): 3 generations per usable product-only shot, 5 to 10 for complex motion, liquids, or cloth, up to 20 when faces or hands are on screen. The floors are why the storyboard avoids humans unless the concept needs them.
4. Price it: `dry_run: true` on every planned `model_run` (the estimate rides in the dry-run response), multiply by the floors, add stills, audio, and assembly runs. Present the table, get the sign-off, then generate; when nobody can answer, the brief's spend ceiling stands in for the sign-off, so generate only while the priced board fits it.
5. Track with `usage`; the metric is cost per usable shot (spend over accepted clips). Same-day `usage` totals can lag aggregation, so ledger the per-job `cuCost` values as ground truth. Re-forecast after the first shot lands: the first scene is calibration.

The per-platform shipping checklist lives in [delivery.md](delivery.md).

# Delivery, audio, and pre-flight

## Masters and safe zones

Compose per ratio, never crop: a 9:16 master at 1080x1920 (TikTok, Reels, Stories, Shorts) and, when the brief needs it, a 16:9 master at 1920x1080 (YouTube in-stream, CTV). A 4:5 feed variant may center-crop from the 9:16 only if the storyboard planned for it.

Safe zone for 9:16 (as of 2026, platform UI eats the edges): keep the product hero, all text, and the CTA inside the central band, clearing roughly the top 14 percent, the bottom 35 percent, and 6 to 13 percent per side. One composition then passes every 9:16 placement. For 16:9 broadcast-style delivery, keep text inside a 10 percent title-safe margin.

Durations are placement-exact: bumpers exactly 6s; CTV slots exactly 15s or 30s (a 22-second cut is undeliverable there); skippable in-stream must land brand and proposition before the skip button at 5s. Feed cuts: 6 to 15s for conversion, 15 to 30s otherwise.

## Assembly

The cut, overlays, and captions are all model runs (contract in `scenario-video-assembly`): clips as video layers, the logo and every text card as image layers, the music as an audio layer. Render text cards deterministically with the `scenario-text-overlay` skill, canvas sized to the master: exact type, boxes positioned inside the safe zone. Legal and locale text must be verbatim, which is why it is never generated.

Keep every generated frame text-free so locale and legal variants are overlay swaps, not regenerations: German text runs about 30 percent longer than English, right-to-left locales mirror alignment and directional motion, and legal supers differ per market (WLTP-qualified range wording in the UK and EU, "EPA-estimated" in the US, retouching labels on altered bodies in France and Norway).

Captions: burned in for sound-off feeds, white sans-serif on a dark backing, 3 to 7 words per cue, inside the safe zone, and moved off the bottom edge when an overlay sits there (`model_schema_get` on the caption tool decides whether position is a field or the overlay must move instead).

Give overlays hard in and out points rather than fades, and QC the assembled master by extracting its frames and checking every overlay window: compositors have dropped mid-timeline image layers that carried fade parameters, and a fade can be simulated safely with two or three stacked copies of the layer at rising opacity.

## Audio

- Music is generated, not licensed by default: commercial tracks need sync licenses for paid media, and platform music libraries do not travel with the creative (TikTok's commercial library is TikTok-only), so a cross-platform campaign cannot rely on them. Generation contract: `scenario-audio`.
- Decide the cut grid first, then prompt the music at that tempo: one beat lasts 60/BPM seconds; cut calm sections on bars, payoffs on beats, and land the reveal and the end card on downbeats.
- Voiceover reads at 2 to 2.5 words per second: 8 to 12 words in 6s, 30 to 35 in 15s, 60 to 70 in 30s, finishing a beat before the end card. Count words before running text-to-speech. Stock or synthetic voices with commercial licenses only; cloning a real voice requires the owner's verified consent.
- Duck the bed 12 to 18 dB under speech with the compositor's per-layer volume. A 1.5 to 3 second sonic logo sits on the end card; on skippable formats repeat a short brand sound cue inside the first 5 seconds.
- Loudness: platforms normalize down, never up. Social masters sit near -14 LUFS integrated with -1 dBTP true peak; CTV requires -24 LKFS plus or minus 2 with -2 dBTP, so a CTV delivery is a separate audio pass. The compositor is not a loudness meter: name the conform step to the user instead of claiming compliance.
- CTV picture floor: 1920x1080, constant frame rate, bitrate well above social norms. AI clips usually need a video upscaler pass first (`recommend` with the upscale need in the user's own words).

## Pre-flight, before calling it shipped

1. Fidelity: every product and character clip passed the gate in [storyboard.md](storyboard.md).
2. Cumulative effect: review the assembled cut as a whole for sensuality, driving behavior, and body framing; ad review judges the sum of shots, not each shot.
3. Flashes: no more than 3 luminance flashes in any second and no saturated red flashing; broadcast and CTV clearance test this mechanically, and strobe hooks are the classic failure.
4. Sound-off pass: watch the master muted; the message must survive on picture and captions alone. Then watch it with sound.
5. Report: files per placement, actual spend against the approved board (`usage`), and cost per usable shot.

# Sibling skill dependencies

`scenario-video-ads` is a director layer: it plans the ad and delegates every mechanical stage to a sibling skill in this repository. Installing only this skill leaves those siblings missing, and each gap removes the procedures its stage depends on.

| Skill                     | What it carries for this pipeline                                 |
| ------------------------- | ----------------------------------------------------------------- |
| `scenario`                | Connection setup and the core generation loop every stage runs on |
| `scenario-image`          | Stage 4 stills, composed natively per delivery ratio              |
| `scenario-consistency`    | Stage 4 compositing of the real product photo into styled plates  |
| `scenario-video`          | Stage 5 image-to-video animation of approved stills               |
| `scenario-seedance`       | Stage 5 animation on Seedance models                              |
| `scenario-asset-analysis` | Stage 1 fidelity checklist and the stage 6 frame-extract gate     |
| `scenario-audio`          | Stage 7 music, voiceover, and sonic logo                          |
| `scenario-text-overlay`   | Stage 8 text cards rendered locally as image layers               |
| `scenario-video-assembly` | Stage 8 timeline cut and captions on Scenario tool models         |

Install a single missing sibling, or everything at once:

```bash
# one missing sibling
npx skills add scenario-labs/skills --skill <name>

# the full set
npx skills add scenario-labs/skills --skill '*'
```

When the user declines an install, or no one is there to answer, state which stage degrades and how (the procedures you would be guessing at) before improvising.

# Storyboard and cinematic grammar

## Concept first, anchored to the canon

Write a one-page concept before any panel: what happens, what turns, the closing image, and the named famous-ad pattern it adapts or subverts. When web access exists, read teardowns of the category's iconic ads before concepting; otherwise anchor to these verified patterns:

- Kenzo World (2016, dir. Spike Jonze): open inside the category cliche, then break it with one violent turn. The default move at `twist` creativity.
- Volvo Trucks "Epic Split" (2013): one claim, proven by one unforgettable demonstration. The consideration-objective default.
- Honda "Cog" (2003): product truth staged as spectacle, mechanism as story.
- Levi's "Launderette" (1985) and Jonathan Glazer's "Odyssey" (2002): one strong music choice carries the whole film.
- Old Spice "The Man Your Man Could Smell Like" (2010): direct-address comedy, gaze straight into the lens.
- Chanel No. 5 "The Film" (2004, dir. Baz Luhrmann) and Dior J'adore: the luxury dream-world register, and the source of its cliches.

Cliches to subvert knowingly rather than repeat: perfume (ballgown on a beach, whispered French, a lone figure in a desert), car (winding mountain road, wet neon asphalt at night, salt-flat donuts, spec-list voiceover), fashion (slow-motion fabric with no idea behind it). Discarding every code at `wild` is legitimate but flag the cost: a category stripped of all its codes stops reading as the category.

Show the concept to the user: it is the cheapest place to be wrong. When nobody can answer, record the chosen anchor and its one-line rationale, then continue.

## Beats and panels

- 6s: hero shot, brand beat. 15s: hook, build, product proof, brand beat plus CTA (4 to 6 panels). 30s: hook, world, turn, proof, payoff, brand beat (6 to 8 panels plus 2 to 3 inserts).
- The brand beat (logo, tagline, CTA) takes the last 2 to 3 seconds. Design the hero shot first: the product at its most desirable, then build beats around it.
- Each panel specifies: what the camera sees; the camera's side of the action line, held constant across the board so a rolling car or a reaching hand keeps its screen direction from cut to cut; one camera move with tempo; a lighting note; the conditioning mode (below); on-screen text, kept for the overlay pass with the frame's center band left clear; a sound note; the slot duration.
- Plan inserts deliberately: 2 to 3 cutaways give the edit cover, and clip-boundary artifacts disappear when cuts land on action or occlusion.
- Generation length is not edit rhythm. Generate 3 to 5 seconds for fidelity-critical product shots, 5 to 10 for coverage, a second or two over the slot as a trim handle, then cut faster in assembly.
- Cuts are hard and made in assembly unless the brief asks for one take or a seamless flow: then chain adjacent approved stills as first and last frame anchors where the schema takes them (shot N runs from still N to still N+1), so each join is a frame both sides share and reads as a camera move, not a cut. Anchor to approved stills only, never to a rendered last frame: it is generated product. The same anchors close the loop that auto-looping placements (TikTok, Reels, Shorts) reward: end the final shot on the opening frame.

## Camera, light, people

| Intent               | Move                   |
| -------------------- | ---------------------- |
| Desire, reveal       | slow orbit             |
| Intimacy, focus      | slow push-in           |
| Authenticity         | subtle handheld        |
| Authority, packshot  | locked-off static      |
| Scale                | crane up, tilt up      |
| Craft detail         | macro extreme close-up |
| Context, consequence | pull-back reveal       |

One move per clip, tempo stated, movement first in the prompt: "slow push-in over 4 seconds". Default the tempo to slow: it hides what the model cannot render cleanly, where speed exposes it. Handheld takes a degree the way other moves take a tempo ("subtle handheld drift"), never bare "handheld". Reliable across video models: push-in, dolly, pan, tilt, tracking, pull-back, handheld. Budget retries for: orbit, crane, rack focus, whip pan. Some schemas expose a camera enum; `model_schema_get` decides whether the move is a parameter or a prompt clause.

Lighting is locked at the still stage, so it belongs in the image prompt: dark-field for glass and liquid (bright edges on a dark ground), backlight for transparency and sheer fabric, steep side light to rake texture, large soft sources for paint and polished metal, rim light for separation, golden hour for car bodywork.

People, when the concept needs them: gaze directed at the product pulls the viewer's attention to it; a gaze into the lens is for direct address and CTAs only. Hands hold the product in a natural use grip and never cover the label. Faces and hands fail first in generation and carry the 20x retry floor, so prefer silhouettes, over-shoulder framing, and product-only sensory shots.

## Vertical presets

- Perfume: sensuality lives in the product, not on a body. Macro bottle hero, atomizer mist, liquid macro, fabric floating detached from any body, liminal wide. Sound: intimate orchestral, whispered sign-off. Policy: no undressing, sheer fabric on skin, or lingering body close-ups; ad review judges the cut's cumulative effect.
- Car: low front three-quarter hero, rolling shot with background blur, light sweeping over bodywork, interior detail, drone over an empty road. Sound: engine and surface carry the emotion, no spec list. Policy: speed is never the message, nothing that reads as a public-road stunt, seatbelts visible, numeric claims (range, fuel economy) only as market-qualified overlay supers.
- Fabric and fashion: the material dictates the cut. Macro weave under raking light, backlit sheers, drape billowing in slow motion, hem lift on a turn; structured tailoring cuts fast, soft drape holds long. Policy: no before-and-after or body-transformation framing, no second-person body copy; some markets require retouching labels when a body is altered, so surface it rather than deciding silently.
- Game: spectacle the genre earns, characters held by a reference sheet (see `scenario-consistency`), world reveal, capture-style framing free of invented UI. Policy: footage must not misrepresent gameplay; label dramatizations.

## Prompting image-to-video

Each shot prompt is self-contained: the model knows nothing of adjacent shots. Movement first, then the subject's state, then atmosphere. For any shot that must END on the pristine product (a landing, a settle, a return to the packshot), generate the opposite motion from the product photo as the first frame and reverse the clip (`search` query `"video reverse"` surfaces the tool): the final frame is then the untouched photo by construction. State product stillness positively, once: "the bottle rests fixed in place". Negative commands ("do not morph") do nothing and can trip filters. Put the hardest detail first. Conditioning: pass the approved still as the first frame when the shot must open on it; use reference images when only identity, world, and palette must hold (the trade is the subject of `scenario-seedance`). Where the schema offers an audio toggle such as `generateAudio`, set it false: the soundtrack is built in assembly.

## The fidelity gate

Every clip showing the product or a character passes this before it may enter the edit:

1. Extract frames: `model_scenario-video-to-image-seq` is Scenario's single deterministic video-to-frames tool, so the id is a constant; take first, middle, last, plus any frame where the subject is largest.
2. One `asset_analyze` call (batching contract in `scenario-asset-analysis`): the approved reference first, then the frames, with an instruction of the shape: "Play spot the difference. Against image 1, list every visible difference in label text and placement, logo geometry, cap and silhouette shape, material and tint, palette. Per image: pass or fail, then the differences."
3. A brand-critical difference fails the clip. Regenerate from the same approved still with a tightened stillness clause, or demote the shot to an insert where the subject is smaller. Never anchor the next attempt to the drifted output.

Build the checklist once at brief time with `asset_analyze` on the product shot, with an instruction naming the fields to inventory (label text and typography, cap, bands, silhouette and proportions, materials, palette). `asset_describe` is the wrong tool for this: it returns a reusable style synthesis for prompts, not a detail inventory.

Proportions are the check that feature lists miss: a composite can keep every named feature (color, light signature, wheels, label) while quietly re-proportioning the product, and "silhouette consistent" passes it. Make the checklist carry measured ratios (length to height, cabin to body, wheel size relative to body, label size relative to face), state them in the still prompts, and have the gate compare those ratios against the reference rather than judging plausibility.