Skip to content
Get started

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(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

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

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.

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.

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 (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).
  • "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.

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.

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] },
},
});

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.

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), 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.

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" },
}),
],
});

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.

Was this page helpful?