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.
import { part, say, video } from "@allyhub/sdk";
export default video({ format: "16x9", script: "./film.{locale}.yaml", parts: ({ s }) => [ part({ key: "intro", dur: 3 }), part({ key: "pitch", speech: say(s("launch.film.pitch.say")) }), ],});video()
Section titled “video()”video(opts) returns its fields as written, with where it was written, so another piece can spread it into its own (Another format).
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) |
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) |
matrix |
Matrix |
the project’s languages | Dimensions and slots: which combos are made (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) |
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) |
defaults |
{ part?: { dur?, lead?, tail? } } |
the project’s, over PART_DEFAULTS |
This video’s part defaults |
music |
media, or MusicOptions |
none | sound.md |
mix |
MixOptions |
MIX_DEFAULTS |
The stems’ loudness, the music’s ducking and fades (sound.md) |
master |
LUFS, { lufs, truePeak }, or false |
−14 LUFS; −3 dBTP | What the sound is mastered to (sound.md) |
mic |
a setup’s name, its options, or false |
"studio" |
How the speech was recorded (sound.md) |
capture |
CaptureOptions |
none | A camera filming the picture (The camera) |
post |
{ filter?, lut? } |
none | An ffmpeg filter chain and a .cube LUT over the frames (Post) |
motionBlur |
{ samples, shutter? } |
none | 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
Section titled “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) |
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) |
ctx.look |
The look |
Another format: reusing a piece
Section titled “Another format: reusing a piece”A piece has one format. Another format is another item that imports what it shares:
import { video } from "@allyhub/sdk";import film from "../film.ts";
// Its id is launch/vertical/film.export default video({ ...film, format: "9x16" });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
Section titled “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. 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):
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), not by the name: a custom WxH or a changed safe has none of its own.
part(opts) makes a part of a video, or a page of a deck.
import { part, take } from "@allyhub/sdk";
export const demo = part({ 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 },});
export const end = part({ key: "end", dur: 3, transition: "fade" });| 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) |
speech |
take(…), say(…) |
none: silent | What it says (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) |
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) |
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) |
sounds |
SoundSpec[] |
none | Sound effects (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) |
tags |
string[] | none | Labels the matrix’s rules read (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). 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
Section titled “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); graphic layers are made by a component or custom() (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).
Stacking (z).
"front": at its place in the list."behind-person": drawn right over the part’s own footage (thefootage()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)."overlay": over the finished picture, as an app lays captions and stickers over a filmed video: over every other layer, and not marked bycapture,motionBlur,postor the LUT. In a transition’s window each part’s overlays move and fade with its picture.
Transitions
Section titled “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 asctx.exit); the starter components’ entrances wait for its end unless told not to. - The whole picture transitions, footage and graphics together. In a
transparentvideo 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.
import { part } from "@allyhub/sdk";
export const slideIn = part({ 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
Section titled “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). 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). 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
Section titled “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: { 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), itstthe film’s time, and what it gives back is made opaquegbrpagain. - Use
t, notn:ncounts 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.
import { part, video } from "@allyhub/sdk";
export default video({ 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
Section titled “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.