# Styles and edits


# Styles and edits

## The idea

Viral and on-brand short-form video is mostly *structure*: how soon the first cut lands, how long each
shot holds, whether cuts hit the beat, what job each shot does, how captions look and move. A **style**
captures that structure from a reference video. An **edit** rebuilds it from your own footage.

## What gets measured, and what gets interpreted

| Measured from the file (exact) | Interpreted by a vision model (descriptive) |
|---|---|
| Every hard cut, to the frame | Each shot's role: `hook`, `context`, `demo`, `detail`, `reaction`, `payoff`, `cta`, `broll` |
| Shot lengths and pacing (cuts per minute, first cut) | What is on screen, camera movement, speed ramps |
| Motion level per shot | Burned-in text, and how captions look: position, case, weight, colour, highlight, words at a time |
| Tempo, beat grid, share of cuts that land on a beat | Transition into each shot: cut, dissolve, whip, zoom, flash, slide |
| Loudness (LUFS) | Hook duration and technique; colour grade; a written summary |

Vision models sample about one frame per second, so they cannot place a cut precisely — they are never
asked to. They only describe shots whose boundaries were already measured. With `semantic: false`, or
if the model is unavailable, you still get the full measured analysis.

## The style spec

`GET /v1/styles/{id}` returns the full spec. Abridged:

```json
{
  "aspect": "9:16", "duration": 17.77,
  "shots": [
    { "index": 0, "start": 0.0, "end": 0.37, "duration": 0.37, "role": "hook", "motion": 1.0,
      "transition_in": "cut", "speed": 1.0, "camera": "screen-recording",
      "description": "Finished dish shown first", "on_screen_text": "Dinner in 10 minutes" }
  ],
  "pacing": { "shot_count": 7, "median_shot": 0.73, "cuts_per_minute": 20.3, "first_cut": 0.37 },
  "music": { "present": true, "bpm": 99.4, "cuts_on_beat_ratio": 0.71, "beats": [0.46, 1.06, …] },
  "loudness_lufs": -13.6,
  "captions": { "present": true, "position": "upper", "case": "sentence", "words_per_chunk": 3,
                "weight": "black", "color": "#FFFFFF", "highlight_color": "#FFD60A", "outline": true },
  "hook": { "duration": 0.37, "technique": "result first" },
  "summary": "…", "semantic": true, "model": "google/gemini-3.8-flash"
}
```

A style keeps numbers and descriptions only — never the reference's pixels or audio — so you can delete
the reference afterwards and keep using the style.

## How an edit is built

1. **Slots.** Each shot in the style becomes a slot with the same length, role, speed and transition,
   scaled if you ask for a different `duration`.
2. **Beat snap.** If you supply music and the reference cuts on the beat, every cut moves to the nearest
   beat of *your* track (never more than 0.6 s), keeping the reference's rhythm.
3. **Footage.** Each slot gets a window of one of your clips. With the vision model, it picks the moment
   that fits the slot's role — the strongest moment for the hook, payoff moments for payoff slots —
   and avoids repeating footage. Without it, a motion-and-detail heuristic matches each slot's energy.
4. **Layout.** Footage that matches the output shape fills the frame. Footage that doesn't (a phone
   recording, a landscape clip in a vertical edit) is never cropped — it sits over a blurred copy of
   itself. When there are captions, it moves below a clear caption band so text never covers the content.
5. **Captions** follow the style's look, timed in chunks of its words-per-screen. With a highlight
   colour, the active word lights up in turn. Lines come from `captions`, or are written from your
   `brief` in the reference's voice.
6. **Audio.** Your music (trimmed, faded out) with your clips' sound ducked underneath, or your clips'
   own sound alone, normalized to −14 LUFS for social platforms.
7. **QA.** The exact file you receive is checked for length, size, black frames, frozen picture, and
   silent or badly levelled audio. A failing render fails the job and refunds it.

## Steering an edit

- **Captions** — pass them explicitly for full control; the first line is the hook and should make a promise.
- **Length** — `duration` rescales every slot proportionally.
- **Shape** — `aspect` renders 9:16, 4:5, 1:1, 4:3 or 16:9 from the same style.
- **Several variants** — run several edits from one style with different captions, music or clips;
  analysis is paid once.
- **The plan** — every edit returns `plan.json`: the clip, in-point, length and transition of each slot.

## Good inputs

- References: 10–90 seconds; the clearer the structure, the better the style.
- Clips: more raw footage than the edit needs (2–3× its length), in focus, with clear subjects.
- Formats: anything common — mp4, mov, webm, mkv; mp3, wav, m4a for music.