# Output spec

## Deliverables

| File | Format | Size | Notes |
|---|---|---|---|
| `film.json` | JSON | | The filled shot list: locks, every prompt, keyframe and clip paths, trims. Lets anyone re-make or re-cut the film. |
| `bible.jpg` | JPEG | 1536 × 864 | Cast reference sheet (when the film has a person). |
| `keyframes/NN-role.jpg` | JPEG | 1536 × 864 (16:9) or 864 × 1536 (9:16); 2048 × 1152 / 1152 × 2048 for a 1080p film | One approved still per shot. Multiples of 16, always at or above the video size. |
| `clips/NN-role-final-1.mp4` | MP4 H.264 | 1280 × 720 (or 720 × 1280) at 720p | One Seedance 2.5 clip per shot, 4–6 s, 24 fps, AAC ambient audio. |
| `<brand>-film.mp4` | MP4 H.264, yuv420p, 24 fps, +faststart | 1280 × 720 (16:9) or 720 × 1280 (9:16) | The finished film: 30 or 45 s ±3 s including the end card. Audio: none, the clips' ambience, or the user's licensed music. |
| `<brand>-film-9x16.mp4` (optional) | MP4 | native centre crop, e.g. 404 × 720 from a 720p film | Only when asked; a crop is softer than a native vertical film. |
| `<brand>-film.mp4.edl.json` | JSON | | Edit list written by assemble-film.mjs: where each shot starts, its trims and the joins. |
| contact sheet | JPEG | 6 frames across, one per second | Written by check-film.mjs; for review, not a deliverable. |

Default settings (these produced the preview): GPT Image 2 `quality: "high"`, 1536 × 864, JPEG; drafts on `bytedance/seedance-2.0/mini/image-to-video` at 480p; finals on `bytedance/seedance-2.5/image-to-video` at 720p, `duration` "4"–"6", `generate_audio: true`, `bitrate_mode: "high"`, `codec: "H264"`; assembly with the shot list's grade, grain 6, bloom 0.08, vignette 0.35, dissolve 0.6 s, CRF 20 (or `--max-mb 7.5` for the web preview).

## Approximate cost (fal list prices, checked 2026-10-16)

| Step | 30 s film (7 shots, 34 s generated) | 45 s film (9 shots, 45 s generated) |
|---|---|---|
| Cast bible (GPT Image 2 high) | $0.25 | $0.25 |
| Keyframes (first $0.25, then ~$0.28 each with references) | $1.93 | $2.49 |
| Drafts (Seedance 2.0 mini 480p, $0.0721/s) | $2.45 | $3.24 |
| Finals (Seedance 2.5 720p, $0.473/s) | $16.08 | $21.29 |
| Without re-rolls | $20.71 | $27.27 |
| Usual re-rolls (a few stills, one to three shots) | +$2.50 to +$7.50 | +$2.50 to +$7.50 |
| **Quote** | **about $23–29** | **about $29–35** |

`build-requests.mjs --stage estimate` prints exactly this for the real shot list; quote its total and get one yes before the first paid call. The 9-shot sample cost $33.62 (stills $3.36 with three re-rolls, drafts $3.75, finals $26.51 with two silhouette re-rolls). 1080p finals cost $1.164/s, about 2.5 times as much.

## Checklist (run before calling the film done)

Technical (scripts/check-film.mjs, exit code 0):
1. Duration within the target ±3 s; 16:9 or 9:16 as briefed; 720p (or 1080p if ordered); H.264 yuv420p; 24 fps; +faststart.
2. No black frames except the end card; no brightness jumps outside planned cuts and dissolves.
3. For a web preview: ≤ 8 MB, ≤ 20 s, no audio track (`--max-mb 8 --muted`).

By eye, on the contact sheet and a full watch:
4. Same person, same hair and same wardrobe in every shot; same product, label unchanged.
5. No extra or duplicated people anywhere (check windows and backgrounds), no melted hands, faces or feet, no rubbery limbs.
6. No stray text, signs, logos or watermarks in the picture; title and end card spelled exactly as the user wrote them.
7. One grade throughout; no shot noticeably brighter, greener or sharper than its neighbours.
8. Cuts land on action; no shot ends on an odd gesture or a turn toward camera; dissolves only where time or place jumps.
9. Tasteful (`references/prompt-patterns.md`, Tasteful framing): wardrobe in place in every clip, nothing centred on hips or buttocks, swimwear only in full or side views, never sexualised; no minors.
10. Poster and thumbnail: choose the aerial, an arrival shot or the dusk shot. A silhouette or swimwear frame is never the poster or thumbnail, even when it is fine inside the film.
11. Sound (if any): licensed or owned music only, and the whole film listened to before it ships (Sound in `references/film-look.md`).

If a check fails: max 3 attempts per shot, change one thing per attempt (motion prompt, trim, or keyframe) and say which, view each result beside its keyframe, then deliver the best version and say plainly what still differs.

## Known imperfections in the sample film

Shipped knowingly; listed so nobody mistakes them for features to copy.
- Dusk shot (last shot before the end card): a bright "evening star" twinkles near the top edge from about 3 s into the clip and fades; it sits mostly under the fade to the end card.
- Golden-hour silhouette: all three Seedance attempts added a hands-at-chest gesture after about 2.3 s. The film uses attempt 1 trimmed to 0.1–2.2 s and slowed to 0.7× (motion-compensated), so the beat is short (about 3 s on screen). At full size the swimsuit line is visible, so it stays inside the film but is never used as a poster frame.
- Surfacing close-up: trimmed at 2.9 s and slowed to 0.85× because the hands start to hover after that.