# Output spec

## Deliverables

| File | Format | Size | Notes |
|---|---|---|---|
| `teaser.json` | JSON | | The filled shot list: locks, prompts, keyframe and clip paths, trims. |
| `keyframes/NN-role.jpg` | JPEG | 864 × 1536 (9:16) or 1536 × 864 (16:9); 1152 × 2048 / 2048 × 1152 for 1080p | One approved still per shot; multiples of 16, never below the video size. |
| `clips/NN-role-final-1.mp4` | MP4 H.264 | 720 × 1280 at 720p | One Seedance 2.5 clip per shot, 4 s (5 s for 4-shot teasers), 24 fps, ambient audio. |
| `<place>-teaser.mp4` | MP4 H.264, yuv420p, 24 fps, +faststart | 720 × 1280 (9:16) or 1280 × 720 (16:9) | 15–20 s, text-free, one grade, 0.5 s fade-out. Silent unless the user asks for the clips' ambience or gives licensed music. |
| `<place>-teaser-4x5.mp4` (optional) | MP4 | 720 × 900 | Centre crop for feed posts (`--crop 4:5`). |
| `<place>-teaser.mp4.edl.json` | JSON | | Edit list: shot starts, trims and joins. |

Default settings (these produced the preview): GPT Image 2 `quality: "high"`, 864 × 1536, JPEG, the approved aerial as the place reference; drafts on `bytedance/seedance-2.0/mini/image-to-video` 480p; finals on `bytedance/seedance-2.5/image-to-video` 720p, `duration` "4", `generate_audio: true`, `bitrate_mode: "high"`, `codec: "H264"`; assembly with grade `blue-hour`, grain 6, bloom 0.12, vignette 0.3, fade-out 0.5 s, `--max-mb 7.5` for the preview (CRF 20 for the full-quality file).

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

| Step | 4 shots (5 s each) | 5 shots (4 s each) | 6 shots (4 s each) |
|---|---|---|---|
| Keyframes (first $0.25, then ~$0.27 with references) | $1.06 | $1.33 | $1.60 |
| Drafts (Seedance 2.0 mini 480p, $0.0721/s) | $1.44 | $1.44 | $1.73 |
| Finals (Seedance 2.5 720p, $0.473/s) | $9.46 | $9.46 | $11.35 |
| Without re-rolls | $11.96 | $12.23 | $14.68 |
| **Quote** (plus up to $3.50 for a re-roll or two) | **about $11–16** | **about $12–16** | **about $14–19** |

`build-requests.mjs --stage estimate` prints this for the real shot list; quote its total and get one yes before the first paid call. The Vael Lodge sample cost $12.24 (no re-rolls). 1080p finals are $1.164/s (about $23 for five 4 s shots).

## Checklist

Technical (`scripts/check-teaser.mjs`, exit code 0):
1. 15–20 s (or the length asked); 9:16 or 16:9 as briefed; 720p; H.264 yuv420p; 24 fps; +faststart.
2. No black frames except the final fade; no brightness jumps outside planned cuts.
3. Preview for the web: ≤ 8 MB, no audio track (`--max-mb 8 --muted`).

By eye (contact sheet and a full watch):
4. One place: the building, materials and landscape match in every shot (and match the user's photos for a real place).
5. People, if any, stay the same; faces away; no extra or duplicated people in windows or backgrounds; hands natural.
6. No text, signs, logos or watermarks anywhere.
7. Something moves in every shot; no frozen weather, no looping fire.
8. One grade; no shot brighter, greener or sharper than the others.
9. Nothing essential in the top 12% or bottom 20% of a 9:16 frame.
10. For a real place: nothing shown that the place does not have.
11. Tasteful (`references/prompt-patterns.md`, Tasteful framing): people dressed or seen from behind or the side, wardrobe in place in every clip.
12. Thumbnail or cover frame: the aerial or the hero shot, never a frame of people in swimwear or robes.
13. Sound (if any): owned or licensed music only, ambience listened to before it ships.

If a check fails: max 3 attempts per shot, change one thing per attempt and say which, compare each attempt with its keyframe, then deliver the best and say plainly what still differs.

## Sound

The teaser is delivered silent by default, because reel apps add music from their own licensed libraries and many viewers watch muted.
- Music: only tracks the user owns or licensed (a stock library licence, their composer, or a royalty-free source whose licence covers advertising). Never ripped or scraped tracks, never sound-alikes of known songs.
- `--music track.mp3` loops the track if it is short, trims it to the teaser, fades in over 0.5 s and out over the last 1.5 s, at `--music-volume` (default 0.8); with `--audio clips` as well, the ambience drops to 55% under it.
- `--audio clips` keeps the Seedance ambience (wind, fire, steam, water). It is model-made: listen to the whole teaser and cut it if you hear voices, music or sounds that do not match the picture.
- Instagram Reels, TikTok and YouTube Shorts apply their own music rules (licensed libraries, business-account limits, claims on uploaded tracks). For those, export silent and add music in the app.

## Known imperfections in the sample

- Hero shot: the camera pushes past a lantern in the snow; the clip is trimmed at 3.6 s, before the lantern fills the bottom of the frame.
- Fireplace shot: firelight flicker is real motion; the flash check passed on the sample, but on other fire shots use `check-teaser.mjs --ignore <seconds>` after looking at the moment.