# Reveal craft

A product reveal is three beats in 6 to 8 seconds:

1. **Darkness or stillness (0 to 1.2 s).** The frame fades up from black (done locally by `scripts/finish.mjs`, so the model never has to invent the product in the dark).
2. **Discovery (1 to 6 s).** Light travels across the product and finds its form while the camera moves slowly. This is where the product earns the shot.
3. **Hero hold (last 1.5 s).** The light settles, the camera eases to a stop, then a short fade out.

Everything is generated from one approved hero keyframe, so the product in the video starts exactly as the keyframe shows it.

## Choosing the mood

| Product | Mood | Notes |
|---|---|---|
| Tech, audio, black or dark products, watches, jewellery, fragrance | `dark-luxe` | Rim light keeps black-on-black readable; haze makes the light visible |
| Skincare, perfume, glass bottles, amber or clear packaging, drinks in glass | `glass-glow` (or `bright-clean`) | A strong backlight through the glass and two edge strip lights on a dark gradient; keep labels large |
| Home, kitchen, wellness, white or pale products | `bright-clean` | Soft window light; a pale grey gradient keeps white products from vanishing |
| Sneakers, toys, snacks, drinks cans, accessories, anything playful | `colour-pop` with `--colour` | Pick a colour that contrasts with the product (a blue product on tangerine, a red can on teal) |
| Food and drink | `bright-clean` or `colour-pop` | Avoid dark-luxe for most food; it reads heavy |

## Choosing the camera move

| Move | Risk to the product | Use for |
|---|---|---|
| `push-in` (default) | Low | Everything without small printed text. Tested in the final video: shape, buttons and ports held for 8 s |
| `locked` (default with `--label-text`) | Lowest | Products with printed text or fine logos; only the light moves. Tested as a 480p draft: product held |
| `rise` | Medium | Tall products (bottles, shoes, perfume) where a low-to-high move flatters the silhouette. Tested as a 480p draft: product held, the rise is gentle |
| `orbit` | High | Only simple, symmetric shapes (cans, round bottles, round watches). Tested on headphones: the headband stretched and an ear cup changed shape |

Slow is premium. Every move in `assets/reveal-presets.json` says "very slowly" on purpose; fast moves make the model invent the sides it has never seen.

## Framing by product size

`--size` picks how much of the frame the product fills (`sizes` in `assets/reveal-presets.json`):

| Size | 16:9 | 9:16 | For |
|---|---|---|---|
| `standard` (default) | about 40 percent of the width | about 65 percent of the width | Most products: headphones, bags, gadgets, boxes |
| `tall` | about 70 percent of the height | about 55 percent of the height | Bottles, perfume, shoes standing up, pouches |
| `tiny` | about 50 percent of the width, macro look | about 75 percent of the width | Rings, earrings, earbuds, lipstick |

These are what the prompt asks for; the model lands near them, not on them. In the preview keyframe the headphones came out at about 38 percent of the frame width, and the push-in brings them to about 44 percent by 3 s.

## Product types and what goes wrong

- **Printed labels and small text.** The biggest risk. In testing, a bottle label reading HALDEN became "AMSER" and "ANGER" in a 480p Seedance 2.0 mini draft (with a moving camera). Always pass `--label-text "EXACT TEXT"`; `build-video-input.mjs` then locks the camera unless you choose a move, and warns if you do. Keep `locked` (or at most `push-in`), keep the product large (a third of the frame height or more), make the final on Seedance 2.5 at 720p or higher, and read the label in the first, middle and last frames.
- **Unbranded products.** Pass `--unbranded`; otherwise glamorous sets tempt the model to add a logo.
- **Black on black.** The dark-luxe set includes a rim light and an amber edge light so the outline stays readable. If the product still disappears, use `bright-clean`.
- **White on white.** The bright-clean set has a soft shadow and a grey gradient. If edges vanish, use `colour-pop` with a pale colour.
- **Glass and liquids.** Use `glass-glow`: the backlight makes the glass and liquid glow and the edge lights draw the outline, so clear and amber glass don't vanish into the dark. Refraction changes as light moves; that is fine. Liquid level must stay the same; say it in `--product` ("amber serum filled to the shoulder"). Tested as a draft keyframe: the bottle and its HALDEN label held.
- **Chrome, gloss and metal.** Reflections should move with the light. Watch for the reflection turning into a glowing line, which reads like an LED. The template says the product has no lights of its own; keep that.
- **Products with lights or screens.** If it really has an LED or a screen, say what it shows in `--product` ("screen off, black glass", "one small white status light"); otherwise the model invents content.
- **Sets and multipacks.** State the count ("exactly three bottles in a row") and check it in every frame.
- **Soft goods (bags, clothing).** Fabric may shift; that is acceptable if the shape and print hold. Use `locked` for prints.
- **Very small products (rings, earbuds).** Use `--size tiny`: a macro framing with the product at about 50 percent of the frame width (75 percent in 9:16) and a shallow depth of field. Tiny products lose detail at 720p; consider `--resolution 1080p`. Not yet tested.
- **Tall products (bottles, perfume, shoes standing up, pouches).** Use `--size tall`: the framing is set by height (about 70 percent of the frame height in 16:9) instead of width. Tested as draft keyframes on a dropper bottle and a coffee pouch.
- **Large products (furniture, bikes).** A plinth looks wrong. Edit the mood's `scene` in a copy of the presets to a room or a floor, and use `push-in` only.

## The input photo

- One clear photo with the whole product in frame, sharp, at least 1000 px, in neutral light. A phone photo on a bed or a counter is fine; the keyframe step removes the background.
- The side that matters faces the camera. The keyframe keeps the photo's camera angle; the model can't reliably show a side it has never seen.
- If the label is curved or angled away, ask for a straight-on photo before spending anything.

## Prompt patterns that worked, and ones that didn't

Worked (all in the templates):
- "one continuous take", "no cuts", "no people, no hands, no new text".
- "The product never moves and keeps exactly its shape, proportions, colours and details".
- "A broad, soft sheen of white light glides slowly across the product ... like a softbox passing by".
- "It has no lights of its own; every highlight on it is a soft reflection."

Didn't work (tested):
- "A narrow band of light sweeps across" made a thin glowing line on the ear cup that looked like a built-in LED ring.
- A dark first frame plus a lit last frame (`end_image_url`) on Seedance 2.0 mini: the reveal happened in half a second, the clip then stood still, and the last frame did not match the end image. Do the fade from black locally instead.
- An orbit on a complex product (see above).

## 16:9 and 9:16

Make each aspect from its own keyframe (`--aspect 9:16` builds an 864 x 1536 keyframe with room for a title above and captions below). Never crop a 16:9 clip to 9:16: 720 px tall becomes 405 px wide and would need upscaling.

## Failure modes and fixes (one change per attempt)

| Problem | Fix |
|---|---|
| The keyframe changed the product (shape, colour, buttons, label) | Re-run the keyframe with a more exact `--product` line and `--label-text`; at the third failure try `fal-ai/nano-banana-pro/edit` (about $0.15; `aspect_ratio` and `resolution: "2K"` instead of `image_size` and `quality`) |
| Label text changes in the video | Switch to `--move locked`, keep `--label-text`, make sure the final is Seedance 2.5 at 720p or 1080p |
| The product morphs or grows parts | Use `push-in` or `locked`, shorten to `--duration 6` |
| Nothing happens for most of the clip | Use `rise` or a stronger light move in a copy of the presets; don't use `end_image_url` |
| A glowing line or dot that looks like an LED | Keep the "no lights of its own" line; if it persists, use `bright-clean` |
| Flicker or haze pumping | Use `bright-clean`, or `--move locked` |
| Too dark on small screens | Raise exposure later with a grade, or use `bright-clean` |
| Still failing after 3 attempts | Return the best clip and say exactly what differs. The alternative video model is `fal-ai/kling-video/v3/turbo/pro/image-to-video` (about $0.14 per second; fields `prompt`, `image_url`, `duration` "3" to "15"; no `resolution`, `aspect_ratio`, `end_image_url` or `generate_audio`) |