# SDK: Videos

> A video is the default export of a module listed in allyhub.yaml as kind: video (project.md): video({ …, parts }), its parts in order, each with its speech (or a length) and its layers. Here: video(), formats, part(), layers and their stacking, transitions, the look, the camera filming the picture, post.

Source: https://allyhub.com/docs/reference/sdk/video · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

```ts file=launch/film.ts

  format: "16x9",
  script: "./film.{locale}.yaml",
  parts: ({ s }) => [
    part({ key: "intro", dur: 3 }),
    part({ key: "pitch", speech: say(s("launch.film.pitch.say")) }),
  ],
});
```

## `video()`

`video(opts)` returns its fields as written, with where it was written, so another piece can spread it into its own ([Another format](#another-format-reusing-a-piece)).

Every piece, a video or a deck, has:

| Field | Type | Default | What it is |
| --- | --- | --- | --- |
| `id` | string | the item's id: its file without its extension, from the project's root | A stable identity ([project.md](https://allyhub.com/docs/reference/sdk/project.md)) |
| `title` | string, or by language | the script's `title` (`<prefix>.title`), else the file name | The name people see |
| `format` | `FormatEntry` | `allyhub.config.ts` `defaults.format`, else `"16x9"` | What it is rendered as: one format ([Formats](#formats)) |
| `matrix` | `Matrix` | the project's languages | Dimensions and slots: which combos are made ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)) |
| `meta` | `Record<string, unknown>` | none | Any key-values, plain data |

A video adds:

| Field | Type | Default | What it is |
| --- | --- | --- | --- |
| `parts` | `(ctx) => PartSpec[]`, or a promise | required | The parts, in order |
| `script` | string | none | Its script, from the module's folder, `{locale}` once in its name for each language (`./film.{locale}.yaml` is `film.en.yaml`, `film.zh-cn.yaml`); without it, it has no words of its own ([project.md](https://allyhub.com/docs/reference/sdk/project.md#scripts)) |
| `covers` | `(ctx) => PartSpec[]` | none | Parts without speech, each drawn at its `still` for the cover image (`allyhub render --type cover`); their layers mount on elements of their own |
| `fps` | number or string | 30 | A whole number from 1 to 120, or an NTSC rate: `23.976`, `29.97`, `47.952`, `59.94`, `119.88`, or `"24000/1001"` … |
| `transparent` | boolean | false | No background: mov, webm and png keep the alpha; mp4 and gif show black where nothing is drawn |
| `look` | string | `"clean"` | The look's name ([The look](#the-look)) |
| `defaults` | `{ part?: { dur?, lead?, tail? } }` | the project's, over `PART_DEFAULTS` | This video's part defaults |
| `music` | media, or `MusicOptions` | none | [sound.md](https://allyhub.com/docs/reference/sdk/sound.md) |
| `mix` | `MixOptions` | `MIX_DEFAULTS` | The stems' loudness, the music's ducking and fades ([sound.md](https://allyhub.com/docs/reference/sdk/sound.md)) |
| `master` | LUFS, `{ lufs, truePeak }`, or `false` | −14 LUFS; −3 dBTP | What the sound is mastered to ([sound.md](https://allyhub.com/docs/reference/sdk/sound.md)) |
| `mic` | a setup's name, its options, or `false` | `"studio"` | How the speech was recorded ([sound.md](https://allyhub.com/docs/reference/sdk/sound.md)) |
| `capture` | `CaptureOptions` | none | A camera filming the picture ([The camera](#the-camera-filming-the-picture)) |
| `post` | `{ filter?, lut? }` | none | An ffmpeg filter chain and a `.cube` LUT over the frames ([Post](#post)) |
| `motionBlur` | `{ samples, shutter? }` | none | [Motion blur](#motion-blur) |
| `maxDuration` | seconds | none | The longest a combo may last; longer is AK-X006 |
| `deliverable` | boolean | true | `false`: only shown inside another video. Rendered only when named; the check leaves out the facts about watching it as a film |
| `loadLimit` | seconds | 10 (`LOAD_LIMIT`) | How long loading may take; longer is AK-P002 |
| `seekLimit` | seconds | 30 (`SEEK_LIMIT`) | How long one moment may take to draw; longer is AK-P003. Loading waits for its layers' work at most 4 times as long |

### The parts function's `ctx`

`parts`, `covers` (and a deck's `pages`) get a `PieceContext`:

| Name | What it is |
| --- | --- |
| `ctx.combo` | This combo: one value per dimension and, with slots, its structure and one candidate per slot (`{ lang: "en", hook: "price" }`) |
| `ctx.s` | The combo's text: `s(key, hint?)`, `s.list(prefix)`, `s.with(key, inputs)` ([project.md](https://allyhub.com/docs/reference/sdk/project.md)) |
| `ctx.asset(path)` | Media at a path made at run time, relative to the piece's file; fixed paths are imports |
| `ctx.data(path)` | A data file (CSV rows, YAML, JSON) at a path made at run time, parsed: cast it, `ctx.data(path) as Plan[]` |
| `ctx.pool(slot)` | The file a pool slot picked in this combo, as a path `footage()` and `ctx.asset()` take ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)) |
| `ctx.look` | The look |

### Another format: reusing a piece

A piece has one format. Another format is another item that imports what it shares:

```ts file=launch/vertical/film.ts

// Its id is launch/vertical/film.
```

A path written as a string (a take's, footage's, a sound's, `music`, `post.lut`) is relative to the module that wrote it, also once spread into another piece; a field the new piece writes again is relative to the new piece.

## Formats

| Format | Pixels | Covered edges |
| --- | --- | --- |
| `16x9`, `9x16`, `1x1`, `4x5` | 1920 × 1080, 1080 × 1920, 1080 × 1080, 1080 × 1350 | the preset's (`PRESETS`) |
| `WIDTHxHEIGHT` | each side 64 to 8192, even for a video | none |
| `a4`, `letter` (slides only) | at 150 dpi | none |

Every preset's numbers: [defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md). Any other format is AK-G001.

A format can change its covered edges with a `FormatSpec`; its name stays the format's own (combos and file names use it):

```ts fragment
format: { format: "9x16", safe: { bottom: 520 } }
```

`safe` is whole pixels per edge; edges not given keep the format's.

A layer reads `ctx.format` (the name) and `ctx.dims`: `{ width, height, orient, safe }`, `orient` `"landscape"`, `"portrait"` or `"square"`, `safe` the covered edges in pixels. Lay out by `ctx.dims` or `layout(ctx)` ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md#the-content-box)), not by the name: a custom `WxH` or a changed `safe` has none of its own.

## Parts

`part(opts)` makes a part of a video, or a page of a deck.

```ts

  key: "demo",
  title: "Demo",
  speech: take("./vo/en.mp3").range("Paste your link", "and you're done"),
  lead: 0.3,
  tail: 0.5,
  still: "done",
  transition: { type: "push", direction: "up", dur: 0.5 },
  overlap: { before: 0.4 },
});

```

| Option | Type | Default | What it is |
| --- | --- | --- | --- |
| `key` | string | required | Unique in the video (a repeat is AK-K001), stable across combos. A part whose key is a slot's name fills that slot |
| `title` | string | its largest text at its still that not every part shows | Its name for people: the timeline, a note |
| `slot` | string | its key, when that is a slot's name | The slot it fills, when the piece has slots ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)) |
| `speech` | `take(…)`, `say(…)` | none: silent | What it says ([speech.md](https://allyhub.com/docs/reference/sdk/speech.md)) |
| `dur` | seconds | 4 (`defaults.part.dur`) | The length of a part without speech; ignored with speech |
| `lead`, `tail` | seconds | 0.2, 0.3 (`defaults.part`) | Before the first word, after the last |
| `layers` | `LayerSpec[]` | none | What it shows, back to front ([Layers](#layers)) |
| `still` | word reference, seconds, or `(dur) => seconds` | 0.4 s before its end | The moment drawn for a cover, a sheet, a page |
| `transition` | a type's name or `TransitionSpec` | a cut | How it comes in from the part before ([Transitions](#transitions)) |
| `overlap` | `{ before?, after? }`, seconds, 0 to 10 | none | J and L cuts: `before` seconds of its speech play under the previous part's picture, `after` under the next part's |
| `anchors` | `{ name: seconds \| [from, to] }` | none | Named moments of the part, from its start ([speech.md](https://allyhub.com/docs/reference/sdk/speech.md)) |
| `sounds` | `SoundSpec[]` | none | Sound effects ([sound.md](https://allyhub.com/docs/reference/sdk/sound.md)) |
| `mic` | as the video's | the video's | How this part's speech was recorded |
| `speechGainDb` | dB, −40 to 24 | 0 | Its speech turned up or down after it is recorded |
| `post` | `{ filter }` | none | The part's own grade ([Post](#post)) |
| `tags` | string[] | none | Labels the matrix's rules read ([batches.md](https://allyhub.com/docs/reference/sdk/batches.md)) |

`part()` throws for a value it cannot use (an empty key, an `overlap` or a gain out of range, a bad transition, anchor, `mic` or `post`), and for a take played at another speed in a part that shows the take's own picture.

**A part's length.** A part with speech lasts `lead` + its speech (its first word to its last) + `tail`; its picture is shorter by its `overlap`. A part without speech lasts `dur`; with `music.snap` it ends on the music's beat ([sound.md](https://allyhub.com/docs/reference/sdk/sound.md)). Parts follow each other on the frame grid. Lengths are worked out from the speech each time: change a take and the parts follow.

Part defaults, from the weakest: `PART_DEFAULTS`, `allyhub.config.ts`'s `defaults.part`, the video's `defaults.part`, the part's own.

## Layers

A part's layers are drawn back to front in the order listed, footage and graphics alike: a graphic layer listed before a footage layer is under it, one between two is between them. Footage layers are `footage()` ([footage.md](https://allyhub.com/docs/reference/sdk/footage.md)); graphic layers are made by a component or `custom()` ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md)).

Every layer takes:

| Option | Type | Default | What it is |
| --- | --- | --- | --- |
| `at` | word reference or seconds | 0 | When it starts, from the part's start |
| `until` | word reference or seconds | the part's end | When it stops |
| `dur` | seconds | | Its length from `at`, when there is no `until` |
| `z` (graphic layers) | `"front"`, `"behind-person"`, `"overlay"` | `"front"` | Where it stacks |

A word reference is a word the part says (`"inbox"`, `"inbox@2"`, `"inbox+0.2"`), an anchor (`"@press"`), or seconds ([speech.md](https://allyhub.com/docs/reference/sdk/speech.md)).

**Stacking (`z`).**

- `"front"`: at its place in the list.
- `"behind-person"`: drawn right over the part's own footage (the `footage()` without a file) wherever it is listed, and under that take's speaker, who is cut out with the take's person matte ([footage.md](https://allyhub.com/docs/reference/sdk/footage.md)).
- `"overlay"`: over the finished picture, as an app lays captions and stickers over a filmed video: over every other layer, and not marked by `capture`, `motionBlur`, `post` or the LUT. In a transition's window each part's overlays move and fade with its picture.

## Transitions

Parts join with cuts. A part comes in with a transition only when it says so: `transition: "fade"`, or a type with its options.

| Type | What happens | Its own options |
| --- | --- | --- |
| `fade` | A crossfade | |
| `dip` | The part before fades to a colour, this part fades in from it | `color`: a CSS colour; default the look's background |
| `slide` | This part travels in over the part before, which stays | `direction`: `"left"` (default), `"right"`, `"up"`, `"down"` |
| `push` | This part pushes the part before out, both travelling | `direction` |
| `wipe` | An edge travels across and uncovers this part; neither picture moves | `direction` |
| `zoom` | The part before grows to `scale` while this part fades in, settling from `from` | `scale` (over 1, up to 4; default 1.2), `from` (0.1 to 4; default `scale`; under 1 it grows in instead) |
| `custom` | The channels given directly | `out`, `in`, `color` |

Every type takes `dur` (over 0, up to 10 s; default 0.4), `ease` (`"linear"`, `"in"`, `"out"`, `"in-out"`; default `"linear"` for fade, dip and custom, `"in-out"` for the others) and `split` (0 to 1, the share of the window before the join; default 0.5). Defaults: `TRANSITION_DEFAULTS`.

- Parts keep their lengths and places: the window lies across the join. Outside its own time a part's graphics hold its first or last frame and its footage runs on in its file.
- The incoming part's clock starts at the join, inside the window: an entrance timed from 0 plays during the transition. A layer reads the window as `ctx.enter` (and the next one as `ctx.exit`); the starter components' entrances wait for its end unless told not to.
- The whole picture transitions, footage and graphics together. In a `transparent` video a fade adds the two pictures, weighted.
- Sound is not changed: place a sound on the join with `sounds`.
- The first part's transition is ignored, and so is a deck's.

A `custom` transition gives `out` (the part before) and `in` (this part, over it) as `{ x, y, scale, opacity, clip: { left, right, top, bottom } }`, and `color: { value?, opacity }`, a colour between them. Each channel is a number (held), `[from, to]`, or keys `[{ p, v }]` over the progress `p` (0 to 1, in order, linear between keys, after `ease`). `x` and `y` are shares of the frame's width and height (−4 to 4), `scale` is about the frame's centre (0.01 to 8), `opacity` and `clip` are 0 to 1. Channels not given rest.

```ts

  key: "custom",
  dur: 2,
  transition: {
    type: "custom",
    dur: 0.6,
    ease: "out",
    out: { x: [0, -0.3], opacity: [1, 0] },
    in: { x: [1, 0] },
  },
});
```

## The look

A look is the variables layers draw with: `ctx.look`, and the same as CSS variables on the stage.

| Token | CSS variable |
| --- | --- |
| `color.bg`, `fg`, `accent`, `muted`, `surface` | `--ak-color-bg`, `--ak-color-fg` … |
| `font.display`, `body`, `mono`, `emoji` | `--ak-font-display` … |
| `motion.beat`, seconds per beat | `--ak-motion-beat` |
| `sfx`: sounds by name | |

The built-in look is `clean` (`CLEAN_LOOK`; its values in [defaults.md](https://allyhub.com/docs/reference/sdk/defaults.md)). `allyhub.config.ts`'s `look` (`{ color?, font?, motion?, sfx? }`, each field optional) is laid over it for every video and deck in the project, under the same name ([project.md](https://allyhub.com/docs/reference/sdk/project.md)). `sfx` names audio files relative to the project's root; every look also has the synthesized `whoosh`, `tick` and `pop`, unless it gives a file of the same name. `clean`'s `font.mono` is the computer's own monospace: bring a font for code.

## The camera filming the picture

`capture` is what a camera filming the picture does to it, before `post`. Each mark is drawn only when given; `{}` takes that mark's defaults (`CAPTURE_DEFAULTS`). Lengths are px at 1080 lines.

| Field | What it is | Range |
| --- | --- | --- |
| `bloom: { threshold, radius, strength }` | Light above `threshold` blurred by `radius` and added at `strength` | 0–0.99, 0–200, 0–1 |
| `aberration` | Red and blue drawn apart at the corners by this many px, less toward the centre | 0–20 |
| `soften` | The lens's softness, a Gaussian blur's sigma | 0–20 |
| `vignette` | How much darker the corners are | 0–0.99 |
| `exposure: { drift, period }` | The exposure breathing as a phone meters: stops, over seconds | drift 0–2, period over 0 |
| `grain: { amount, size, shadows, highlights, chroma, chromaSize, static }` | `amount`: its deviation at middle grey (share of full scale); `size`: its softness; × `shadows` at black, × `highlights` at white, drawn smaller near either end so nothing clips; `chroma`: each channel's own noise, softer by `chromaSize`; `static`: the same grain every frame | amount 0–0.166 |
| `sharpen` | The phone's sharpening: unsharp masking's amount | 0–5 |

Each frame's marks are a function of its frame number in the film: a still is the render's frame, and nothing starts again at a cut. `allyhub frames compare` measures grain and edge softness against a reference's frame.

## Post

`post: { filter?, lut? }` runs over the frames after the camera's marks: one ffmpeg filter chain, then a 3D LUT (`.cube`) at a path relative to the module that wrote it.

- One chain: no `;`, no `[labels]`, no filter that reads or writes files.
- It gets the picture opaque as 8-bit planar RGB (`gbrp`), its `t` the film's time, and what it gives back is made opaque `gbrp` again.
- Use `t`, not `n`: `n` counts from each segment's first frame. A chain whose frames depend on where a segment starts (`n`, a seed drawn per frame, neighbouring frames) is AK-D002; one that does not run is AK-M001.

A part's `post: { filter }` is the same contract on that part's picture alone, before the camera's marks and the video's `post`: a clip's white balance or exposure.

```ts

  format: "9x16",
  capture: { grain: {}, vignette: 0.2, soften: 1 },
  post: { filter: "eq=contrast=1.05:saturation=1.1", lut: "./grade.cube" },
  motionBlur: { samples: 4 },
  parts: () => [
    part({
      key: "hook",
      dur: 3,
      post: { filter: "colortemperature=temperature=4800" },
    }),
  ],
});
```

## Motion blur

`motionBlur: { samples, shutter? }`: each frame blends `samples` (2 to 16) moments of the graphic layers across `shutter` of the frame's time (over 0, up to 1; default 0.5, a 180° shutter). Footage is not blurred again. `z: "overlay"` layers are not blurred.
