rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/grammar.ts

@@ -0,0 +1,1290 @@
+import { type LineWord, type Moment, slotText, type Typed, typedFilm, type Words } from './words.ts'
+
+// the trailer language, its core words: one text file → the shots, their films, titles, sounds and cuts. Pure: no
+// file, no process; a film word that is not a core kind is looked up in the project CLI's film rows the caller
+// passes in. Every error carries its line, all at once, and a file with one error never builds
+
+export type TitleStyle = 'logo' | 'big' | 'caption' | 'corner' | 'line' | 'short' | 'progress'
+/** the styles a title line names; `progress` is its own line's */
+export const TITLE_STYLES: readonly TitleStyle[] = ['logo', 'big', 'caption', 'corner', 'line', 'short']
+export const CUT_KINDS = [
+    'hard',
+    'fade',
+    'dip-black',
+    'dip-white',
+    'slide-left',
+    'slide-right',
+    'slide-up',
+    'slide-down',
+    'whip-left',
+    'whip-right',
+    'wipe-left',
+    'wipe-right',
+    'wipe-up',
+    'wipe-down',
+    'circle',
+    'pixel',
+] as const
+export type CutKind = (typeof CUT_KINDS)[number]
+export const CORE_FILMS = ['clip', 'image', 'card', 'run', 'url', 'grid', 'split'] as const
+
+/** the most frames a second a cut runs at */
+export const FPS_MAX = 60
+const DEFAULT_CUT_S = 0.5
+
+/** how long a take films: what the shot shows rounded up to 2 s (`steps`, the default), exactly that (`exact`), or as
+ *  long as it plays (`own`: no --seconds, the key holds none) */
+export type TakeLength = 'steps' | 'exact' | 'own'
+
+/** a film row of the project CLI: a still writes one image at `--out`, a clip a video of `--seconds` */
+export interface FilmVerb {
+    path: string[]
+    film: 'still' | 'clip'
+    /** the words the row takes and their types (words.ts): every word checked at its line, values handed plain */
+    words?: Words
+    /** the paths the row's takes film: their world, over the unit's `stamp` */
+    stamp?: string[]
+    /** the row's take version: a bump films every take of the row again */
+    version?: number | string
+    /** `own`: the row films as long as it plays */
+    length?: 'own'
+    description?: string
+}
+
+/** a grid holds at most this many cells, 3 by 3 */
+export const GRID_MAX = 9
+/** a growing grid eases out over this long before each settle */
+export const GROW_S = 1
+/** a split's seams lean this far from upright by default: two panes top left and bottom right, three slanted columns */
+export const SPLIT_ANGLE: Readonly<Record<number, number>> = { 2: 56, 3: 14 }
+/** a split's panes slide in this long by default */
+export const SPLIT_SLIDE = 0.3
+
+export type Film =
+    | { kind: 'clip'; line: number; path: string }
+    | { kind: 'image'; line: number; path: string }
+    | { kind: 'card'; line: number }
+    /** any command that writes the take at `{out}`; `still`: it writes an image, held for the shot; `reads`: the files
+     *  the command reads, their content part of the take's key */
+    | { kind: 'run'; line: number; cmd: string; still?: true; reads?: string[] }
+    /** a film row of the project CLI, its words as written: `<cli> <argv> --out <file> [--seconds <n>]`; its row's take
+     *  version and length when the row has them */
+    | {
+          kind: 'cli'
+          line: number
+          argv: string[]
+          output: 'still' | 'clip'
+          version?: number | string
+          length?: 'own'
+          /** the row declares its words: argv holds them plain */
+          typed?: true
+          /** argv slots that are files as written: the build finds them and keys their content */
+          files?: number[]
+          /** the paths the row's takes film */
+          stamp?: string[]
+      }
+    /** a page of the repo's dev url (a route) or any http url, through the house shot service; `viewport` its css
+     *  size, `wait` before it films; `still`: a png, else a clip of the page's largest canvas */
+    | { kind: 'url'; line: number; route: string; viewport?: [number, number]; wait?: number; still?: true }
+    /** other shots' or footage blocks' takes tiled, each cell playing live; `pop`: cell i pops in at i times it; `grow`:
+     *  nine cells growing out of the first, settled on the 2 by 2 block then the whole at these seconds */
+    | { kind: 'grid'; line: number; cells: string[]; pop: number; grow?: [number, number] }
+    /** two or three takes side by side, cut by slanted seams `angle` degrees from upright, each pane sliding in */
+    | { kind: 'split'; line: number; cells: string[]; angle: number; slide: number }
+
+/** the vertical short: a lockup over every frame, a watermark in a bottom corner, then the outro and the end card,
+ *  each drawn from the brand's `trailer.vertical` data (vertical.ts) */
+export interface Vertical {
+    line: number
+    /** the watermark's corner, over the brand's own */
+    mark?: 'left' | 'right'
+    /** what follows the short: the end card (the default), a clip then the end card, or nothing */
+    outro: 'card' | 'none' | { clip: string }
+}
+
+/** the size a vertical short films at when the file names none */
+export const VERTICAL_SIZE: [number, number] = [1080, 1920]
+
+export interface Title {
+    line: number
+    text: string
+    at: number
+    /** null: to the shot's end */
+    for: number | null
+    style: TitleStyle
+    /** where a caption sits: the bottom by default */
+    place?: 'top' | 'bottom'
+    /** knocked off the frame from this second of its shot: it tips and flies out */
+    knock?: number
+    /** a `progress` line's step: the i-th of n notches filled under its name */
+    step?: { i: number; n: number }
+}
+
+export interface Sfx {
+    line: number
+    /** a file, or an id the repo's sound resolver knows */
+    id: string
+    at: number
+    volume: number
+}
+
+export interface Voice {
+    line: number
+    /** a line the repo's voice resolver finds by its text, or a recorded file */
+    text?: string
+    file?: string
+    at: number
+    volume: number
+}
+
+export interface Shake {
+    line: number
+    at: number
+    for: number
+    strength: number
+}
+
+export interface Flash {
+    line: number
+    at: number
+    for: number
+}
+
+export interface Cut {
+    line: number
+    kind: CutKind
+    seconds: number
+}
+
+/** a section as its first shot sees it: the shot starts when the timeline reaches `at` */
+export interface SectionRef {
+    line: number
+    name: string
+    at: number
+}
+
+export interface Music {
+    line: number
+    /** a file, `none`, or an id the repo's sound resolver knows */
+    song: string
+    take?: string
+    from: number
+    fadeIn: number
+    fadeOut: number
+    volume: number
+}
+
+export interface Shot {
+    line: number
+    name: string
+    length: number
+    /** the shot opens this section: the shot before it is fitted so it lands on its start */
+    section?: SectionRef
+    /** `starts on`: the moment it lands on, a section or a mark, and a time from it */
+    lands?: { line: number; on: string; offset: number }
+    /** the length the file wrote, when a section fitted this shot to another */
+    written?: number
+    film: Film | null
+    titles: Title[]
+    sfx: Sfx[]
+    voices: Voice[]
+    cut: Cut
+    /** seconds of footage skipped at its start */
+    from: number
+    /** a slow push in to this zoom over the shot */
+    push: number | null
+    /** the footage cropped about its middle by this factor */
+    frame: number | null
+    /** the shot's dark tones lifted by this gamma, 1 to 2 */
+    lift?: number
+    /** the point the crop is taken about, 0 to 1 across and down the footage; absent: its middle */
+    frameAt?: [number, number]
+    shakes: Shake[]
+    flashes: Flash[]
+    /** the music changes as the shot starts: a crossfade over its fade-in, `none` for silence */
+    music: Music | null
+    /** its own line failed: nothing else is checked against it */
+    broken?: true
+    /** a `footage` block: filmed, never cut in */
+    offcut?: true
+}
+
+/** the tempo a line counts bars and beats in */
+export interface Clock {
+    bpm: number
+    /** beats in a bar */
+    meter: number
+    /** rows a beat is written in */
+    grid: number
+}
+
+export interface Mark {
+    line: number
+    name: string
+    /** seconds from its section's start */
+    at: number
+}
+
+/** a part of the timeline in bars: its shots land on its start, and the stitch caches it as one piece. Under a
+ *  score, it is also a part of the music: what each track plays over it */
+export interface Section {
+    line: number
+    name: string
+    clock: Clock | null
+    /** where it starts on the timeline, seconds */
+    at: number
+    seconds: number
+    marks: Mark[]
+    /** `defaults <words>`: what every declared film line of the section starts from */
+    defaults?: Word[]
+    /** its drum letters over the score's */
+    drums: Record<string, string>
+    plays: Play[]
+}
+
+/** `play <track> <expression>`: what a track plays over its section, TypeScript; `*` a record of tracks */
+export interface Play {
+    line: number
+    track: string
+    expr: string
+}
+
+/** the cut's own music, written in the file (score/score.ts compiles it, score/synth.ts renders it) */
+export interface Score {
+    line: number
+    /** the first section's clock: the score line's own */
+    clock: Clock
+    reverb?: { seconds: number; mix: number }
+    fadeIn: number
+    volume: number
+    tracks: { line: number; name: string; instrument: string; volume: number }[]
+    /** drum letter → instrument, every section */
+    drums: Record<string, string>
+    /** the `code` block, its lines at their own line numbers (the others blank) */
+    code: { line: number; text: string } | null
+    /** `stop at <time>`: the score and its room cut dead there, seconds from the first section's start */
+    stop?: { line: number; at: number }
+}
+
+/** the voices a score holds at most */
+export const TRACKS_MAX = 16
+/** the music a score starts with: the render's lead, so its first note is never cut */
+export const SCORE_LEAD = 0.05
+/** the score in the cut's music cues */
+export const SCORE = '@score'
+
+export interface Trailer {
+    name: string
+    /** `footage` blocks: filmed like shots, never cut in; a grid or a split reads them */
+    footage: Shot[]
+    size: [number, number]
+    fps: number
+    music: Music | null
+    /** dB the music drops under a voice line, negative */
+    duck: number
+    /** dB the music drops under each sfx, negative; null: none */
+    duckSfx: number | null
+    fadeIn: number
+    shots: Shot[]
+    sections: Section[]
+    /** the cut's own music; null: none */
+    score: Score | null
+    /** where the timeline of the sections (and the score) starts on the cut: the first landed shot's start less its moment */
+    timelineAt: number | null
+    /** the cut is a vertical short (`vertical`), finished with the brand's lockup, watermark and end card */
+    vertical: Vertical | null
+    /** the global process whose url a `film url` route resolves against (`base <id>`); null: the repo's one */
+    base: string | null
+}
+
+export interface TrailerError {
+    line: number
+    message: string
+}
+
+interface Word {
+    text: string
+    quoted: boolean
+    /** an option line's word keeps its own line */
+    line?: number
+}
+
+/** a line's words: a quoted run is one word (quoted), `#` outside quotes ends the line. Only double quotes quote, as in
+ *  the full language, so a word opening on a single quote is refused: it would reach a command with the quotes inside */
+export function tokens(line: string): { words: Word[] } | { error: string } {
+    const words: Word[] = []
+    let i = 0
+    while (i < line.length) {
+        const c = line[i]!
+        if (c === ' ' || c === '\t') {
+            i++
+            continue
+        }
+        if (c === '#') break
+        if (c === "'") {
+            const end = line.indexOf("'", i + 1)
+            const word = end < 0 ? line.slice(i).split(/[\s#]/)[0]! : line.slice(i, end + 1)
+            return { error: `${word} opens on a single quote: the language quotes with double quotes only, write "${word.slice(1, end < 0 ? undefined : -1)}"` }
+        }
+        if (c === '"') {
+            const end = line.indexOf('"', i + 1)
+            if (end < 0) return { error: 'a quote is not closed' }
+            words.push({ text: line.slice(i + 1, end), quoted: true })
+            i = end + 1
+            continue
+        }
+        let j = i
+        while (j < line.length && line[j] !== ' ' && line[j] !== '\t' && line[j] !== '"' && line[j] !== '#') j++
+        words.push({ text: line.slice(i, j), quoted: false })
+        i = j
+    }
+    return { words }
+}
+
+class LineError extends Error {}
+const bad = (message: string): never => {
+    throw new LineError(message)
+}
+
+/** the clock the line being read counts bars and beats in: each section's, from its line on */
+let clock: Clock | null = null
+
+/** `1.5s`, `400ms`, `m:ss(.f)`, and at a clock `2bars`, `1beat`, as seconds; terms add up with `+` (`1bar+0.5beat`) */
+export function parseTime(s: string, c: Clock | null = null): number | null {
+    let total = 0
+    for (const term of s.split('+')) {
+        let m = /^(\d+(?:\.\d+)?)s$/.exec(term)
+        if (m) total += Number(m[1])
+        else if ((m = /^(\d+)ms$/.exec(term))) total += Number(m[1]) / 1000
+        else if ((m = /^(\d+):([0-5]\d(?:\.\d+)?)$/.exec(term))) total += Number(m[1]) * 60 + Number(m[2])
+        else if ((m = /^(\d+(?:\.\d+)?)(bars?|beats?)$/.exec(term)) && c) total += (Number(m[1]) * (m[2]!.startsWith('bar') ? c.meter : 1) * 60) / c.bpm
+        else return null
+    }
+    return total
+}
+
+const TIMES = '1.5s, 400ms, 0:04, 2bars, 1beat, 1bar+2beats'
+const time = (what: string, w: Word | undefined): number => {
+    if (!w || w.quoted) return bad(`${what} wants a time (${TIMES})`)
+    const v = parseTime(w.text, clock)
+    if (v !== null) return v
+    if (/bar|beat/.test(w.text) && !clock) return bad(`${what}: ${w.text} counts bars and beats, which need a tempo (section <name> <length> tempo <bpm>)`)
+    return bad(`${what} wants a time (${TIMES}), got ${w.text}`)
+}
+
+/** a section's or a mark's name as an `at` reads it: words of a letter and more, joined by `-` */
+const MOMENT = '[a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*'
+
+/** a moment named on the timeline, and a time from it */
+interface MarkAt {
+    mark: string
+    offset: number
+}
+
+/** an `at`: a time, or a section or mark with an offset (`drop`, `drop-1beat`, `title+0.5s`) */
+const when = (w: Word | undefined, k: string): number | MarkAt => {
+    const m = w && !w.quoted ? new RegExp(`^(${MOMENT})(?:([+-])(\\d.*))?$`).exec(w.text) : null
+    if (!m) return time(k, w)
+    const off = m[3] === undefined ? 0 : (parseTime(m[3], clock) ?? bad(`${k}: ${m[3]} after ${m[1]} is no time (${TIMES})`))
+    return { mark: m[1]!, offset: m[2] === '-' ? -off : off }
+}
+const num = (what: string, w: Word | undefined, lo: number, hi: number): number => {
+    const n = w && !w.quoted ? Number(w.text) : Number.NaN
+    if (!Number.isFinite(n) || n < lo || n > hi) return bad(`${what} wants a number from ${lo} to ${hi}${w ? `, got ${w.text}` : ''}`)
+    return n
+}
+const word = (what: string, w: Word | undefined, re = /^[a-z0-9][a-z0-9:_.,=+-]*$/i): string => {
+    if (!w || w.quoted || !re.test(w.text)) return bad(`${what} wants a word${w ? `, got ${w.quoted ? `"${w.text}"` : w.text}` : ''}`)
+    return w.text
+}
+const quoted = (what: string, w: Word | undefined): string => {
+    if (!w || !w.quoted) return bad(`${what} wants a quoted text${w ? `, got ${w.text}` : ''}`)
+    if (w.text.trim() === '') return bad(`${what}: the text is empty`)
+    return w.text
+}
+/** a file path or an id, bare or quoted */
+const pathWord = (what: string, w: Word | undefined): string => {
+    if (!w || w.text.trim() === '' || (!w.quoted && /\s/.test(w.text))) return bad(`${what} wants a file${w ? `, got ${w.text}` : ''}`)
+    return w.text
+}
+
+/** `WxH` in pixels, each side from `lo` to `hi` */
+const sizeWord = (what: string, w: Word | undefined, lo: number, hi: number): [number, number] => {
+    const m = w && !w.quoted ? /^(\d+)x(\d+)$/.exec(w.text) : null
+    const [x, y] = [Number(m?.[1]), Number(m?.[2])]
+    if (!m || x < lo || y < lo || x > hi || y > hi) return bad(`${what} wants WxH, from ${lo} to ${hi} a side${w ? `, got ${w.text}` : ''}`)
+    return [x, y]
+}
+
+/** the `key value` pairs after a line's fixed words; `flags` take no value */
+function pairs(
+    what: string,
+    rest: Word[],
+    valued: Record<string, (w: Word | undefined, key: string) => unknown>,
+    flags: readonly string[] = [],
+): Record<string, unknown> {
+    const out: Record<string, unknown> = {}
+    for (let i = 0; i < rest.length; i++) {
+        const k = rest[i]!
+        if (k.quoted) bad(`${what}: a quoted text "${k.text}" where a word was expected`)
+        if (k.text in out) bad(`${what}: ${k.text} given twice`)
+        if (flags.includes(k.text)) {
+            out[k.text] = true
+            continue
+        }
+        const f = valued[k.text]
+        if (!f) bad(`${what}: unknown word ${k.text} (${what} takes ${[...Object.keys(valued), ...flags].join(', ') || 'nothing more'})`)
+        out[k.text] = f!(rest[++i], `${what} ${k.text}`)
+    }
+    return out
+}
+
+/** the film row a line's words start with: the longest row path at their head */
+export function verbOf(words: readonly string[], verbs: readonly FilmVerb[]): FilmVerb | null {
+    let best: FilmVerb | null = null
+    for (const v of verbs)
+        if (v.path.length <= words.length && v.path.every((p, i) => words[i] === p) && v.path.length > (best?.path.length ?? 0)) best = v
+    return best
+}
+
+/** what a film line may start with in this repo, for its errors */
+const filmWords = (verbs: readonly FilmVerb[] | null): string =>
+    `${CORE_FILMS.join(', ')}${verbs === null ? '; no project CLI answers `<cli> commands --json` (the `cli` script of package.json)' : verbs.length === 0 ? '; the project CLI has no film row' : `, or a film row of the project CLI: ${verbs.map((v) => v.path.join(' ')).join(', ')}`}`
+
+/** a film line: a core kind when its words fit that kind's form (`clip <video file>`), else a film row of the project
+ *  CLI (its `clip <scene>` row), else the core kind's error */
+/** what a film line of a declared row reads past its words: its section's defaults, the header's presets, a time */
+interface FilmContext {
+    defaults: Word[]
+    presets: ReadonlyMap<string, Word[]>
+    time: (text: string) => Moment | null
+    /** a slot that waits on a moment, resolved once the shots have landed */
+    later: (f: Extract<Film, { kind: 'cli' }>, slot: Typed['times'][number]) => void
+    errors: TrailerError[]
+}
+
+/** a film line's words with every `+<preset>` put in place */
+function expandPresets(ws: Word[], line: number, presets: ReadonlyMap<string, Word[]>): Word[] {
+    return ws.flatMap((w) => {
+        if (w.quoted || !/^\+[a-z][a-z0-9-]*$/.test(w.text)) return [w]
+        const p = presets.get(w.text.slice(1)) ?? bad(`film: no preset ${w.text.slice(1)} (preset <name> <words> in the header${presets.size ? `: ${[...presets.keys()].join(', ')}` : ''})`)
+        return p.map((x) => ({ ...x, line: w.line ?? line }))
+    })
+}
+
+function filmLine(raw: Word[], line: number, verbs: readonly FilmVerb[] | null, c?: FilmContext): Film {
+    const ws = c ? expandPresets(raw, line, c.presets) : raw
+    const kind = ws[0] && !ws[0].quoted ? ws[0].text : ''
+    const argv = ws.map((w) => w.text)
+    const v = verbs && verbOf(argv, verbs)
+    if ((CORE_FILMS as readonly string[]).includes(kind)) {
+        try {
+            return coreFilm(kind, ws, line)
+        } catch (e) {
+            if (!(e instanceof LineError) || !v) throw e
+        }
+    }
+    if (!v) return bad(`film: unknown kind ${kind || '(none)'} (${filmWords(verbs)})`)
+    if (argv.some((a) => a === '--out' || a.startsWith('--out=') || a === '--seconds' || a.startsWith('--seconds='))) bad(`film ${v.path.join(' ')}: the trailer gives --out and --seconds itself`)
+    const marks = { ...(v.version !== undefined ? { version: v.version } : {}), ...(v.length ? { length: v.length } : {}), ...(v.stamp ? { stamp: v.stamp } : {}) }
+    if (!v.words || !c) return { kind: 'cli', line, argv, output: v.film, ...marks }
+    const at = (w: Word): LineWord => ({ text: w.text, quoted: w.quoted, line: w.line ?? line })
+    const typed = typedFilm(v.path, v.words, ws.slice(v.path.length).map(at), c.defaults.map(at), c.time)
+    c.errors.push(...typed.errors)
+    const f: Extract<Film, { kind: 'cli' }> = { kind: 'cli', line, argv: typed.argv, output: v.film, typed: true, ...(typed.files.length ? { files: typed.files } : {}), ...marks }
+    for (const slot of typed.times) c.later(f, slot)
+    return f
+}
+
+/** a list of `min` to `max` different shot or footage names */
+function cellList(what: string, w: Word | undefined, min: number, max: number): string[] {
+    const list = word(what, w, /^[a-z0-9][a-z0-9-]*(?:,[a-z0-9][a-z0-9-]*)*$/)
+    const cells = list.split(',')
+    if (cells.length < min || cells.length > max) bad(`${what}: ${min} to ${max} cells, got ${cells.length}`)
+    if (new Set(cells).size !== cells.length) bad(`${what}: a cell named twice in ${list}`)
+    return cells
+}
+
+function coreFilm(kind: string, ws: Word[], line: number): Film {
+    switch (kind) {
+        case 'clip': {
+            const path = pathWord('film clip', ws[1])
+            if (!/\.(mp4|webm|mov|mkv)$/i.test(path)) bad(`film clip wants a video file (.mp4, .webm, .mov, .mkv), got ${path}`)
+            pairs(`film clip ${path}`, ws.slice(2), {})
+            return { kind, line, path }
+        }
+        case 'image': {
+            const path = pathWord('film image', ws[1])
+            if (!/\.(png|jpe?g|webp)$/i.test(path)) bad(`film image wants an image file (.png, .jpg, .webp), got ${path}`)
+            pairs(`film image ${path}`, ws.slice(2), {})
+            return { kind, line, path }
+        }
+        case 'card':
+            pairs('film card', ws.slice(1), {})
+            return { kind, line }
+        case 'run': {
+            const cmd = quoted('film run', ws[1])
+            if (!cmd.includes('{out}')) bad('film run wants {out} in its command: the file the command writes the take to')
+            const p = pairs('film run', ws.slice(2), { reads: (w, k) => pathWord(k, w).split(',') }, ['still'])
+            return { kind, line, cmd, ...(p.still ? { still: true as const } : {}), ...(p.reads ? { reads: p.reads as string[] } : {}) }
+        }
+        case 'url': {
+            const route = pathWord('film url', ws[1])
+            if (!/^(\/|https?:\/\/)/.test(route)) bad(`film url wants a route of the dev url (/pricing) or an http url, got ${route}`)
+            const p = pairs(`film url ${route}`, ws.slice(2), { viewport: (w, k) => sizeWord(k, w, 16, 7680), wait: at }, ['still'])
+            return {
+                kind,
+                line,
+                route,
+                ...(p.viewport ? { viewport: p.viewport as [number, number] } : {}),
+                ...(p.wait !== undefined ? { wait: p.wait as number } : {}),
+                ...(p.still ? { still: true as const } : {}),
+            }
+        }
+        case 'grid': {
+            const cells = cellList('film grid', ws[1], 1, GRID_MAX)
+            const p = pairs(`film grid ${cells.join(',')}`, ws.slice(2), {
+                pop: at,
+                grow: (w, k) => {
+                    const t = word(k, w, /^\d+(?:\.\d+)?s,\d+(?:\.\d+)?s$/)
+                    const v = t.split(',').map((x) => Number(x.slice(0, -1)))
+                    return v[0]! >= GROW_S && v[1]! >= v[0]! + GROW_S ? v : bad(`${k} wants two settles at least ${GROW_S}s apart, the first at ${GROW_S}s or later, got ${t}`)
+                },
+            })
+            if (p.grow && cells.length !== 9) bad(`film grid … grow: it grows out of one cell into four, then nine: it wants nine cells, got ${cells.length}`)
+            if (p.grow && p.pop) bad('film grid: grow or pop, not both')
+            return { kind, line, cells, pop: (p.pop as number) ?? 0, ...(p.grow ? { grow: p.grow as [number, number] } : {}) }
+        }
+        case 'split': {
+            const cells = cellList('film split', ws[1], 2, 3)
+            const p = pairs(`film split ${cells.join(',')}`, ws.slice(2), { angle: (w, k) => num(k, w, 0, 70), slide: at })
+            return { kind, line, cells, angle: (p.angle as number) ?? SPLIT_ANGLE[cells.length] ?? 0, slide: (p.slide as number) ?? SPLIT_SLIDE }
+        }
+    }
+    return bad(`film: unknown kind ${kind}`)
+}
+
+const volume = (w: Word | undefined, k: string) => num(k, w, 0, 4)
+const at = (w: Word | undefined, k: string) => time(k, w)
+
+/** a music cue that is silence */
+export const NO_MUSIC = 'none'
+
+/** the cut's opening cue fades in this long when it starts inside its song and names no fade-in */
+export const OPENING_FADE_IN = 0.25
+
+/** `music <file|id|none> [take k] [from t] [fade-in t] [fade-out t] [volume v]`; `opening`: the cut's own */
+function musicLine(rest: Word[], n: number, opening = false): Music {
+    const song = pathWord('music', rest[0])
+    const p = pairs(`music ${song}`, rest.slice(1), {
+        take: (w, k) => word(k, w, /^[a-z0-9][a-z0-9-]*$/),
+        from: at,
+        'fade-in': at,
+        'fade-out': at,
+        volume,
+    })
+    return {
+        line: n,
+        song,
+        ...(p.take ? { take: p.take as string } : {}),
+        from: (p.from as number) ?? 0,
+        fadeIn: (p['fade-in'] as number | undefined) ?? (opening && ((p.from as number | undefined) ?? 0) > 0 ? OPENING_FADE_IN : 0),
+        fadeOut: (p['fade-out'] as number) ?? 0,
+        volume: (p.volume as number) ?? 1,
+    }
+}
+
+/**
+ * the lines the language reads as TypeScript, taken out before the words are read (their lines blank, so every line
+ * keeps its number): the `code` block (its indented lines under a margin `code` line) and each `play` line with the
+ * deeper indented lines that continue it. A line whose first mark is `#` is off in both.
+ */
+export function scoreLines(text: string): { lines: string[]; code: Score['code']; plays: (Play & { section: number })[]; errors: TrailerError[] } {
+    const lines = text.split('\n')
+    const errors: TrailerError[] = []
+    const plays: (Play & { section: number })[] = []
+    let code: Score['code'] = null
+    let section = -1
+    const indent = (l: string): number => l.length - l.trimStart().length
+    const off = (l: string): boolean => l.trimStart().startsWith('#')
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i]!
+        if (/^section\s/.test(l)) section++
+        if (/^code\s*(#.*)?$/.test(l)) {
+            const head = i + 1
+            if (code) errors.push({ line: head, message: `code is already written on line ${code.line}: one code block a file` })
+            const body: string[] = Array.from({ length: head }, () => '')
+            lines[i] = ''
+            for (let j = i + 1; j < lines.length; j++) {
+                const b = lines[j]!
+                if (b.trim() !== '' && !off(b) && indent(b) === 0) break
+                body.push(off(b) ? '' : b.replace(/^( {2}|\t)/, ''))
+                lines[j] = ''
+                i = j
+            }
+            code ??= { line: head, text: body.join('\n') }
+            continue
+        }
+        const m = /^(\s*)play(?:\s+(\S+))?(?:\s+(.*))?$/.exec(l)
+        if (!m || off(l)) continue
+        const at = i + 1
+        const parts = [m[3] ?? '']
+        lines[i] = ''
+        for (let j = i + 1; j < lines.length; j++) {
+            const b = lines[j]!
+            // deeper lines continue the expression; a closing bracket at the play's own indent ends it, and is its
+            const close = indent(b) === (m[1] ?? '').length && /^[)\]}]/.test(b.trimStart())
+            if (b.trim() !== '' && !off(b) && indent(b) <= (m[1] ?? '').length && !close) break
+            if (!off(b)) parts.push(b)
+            if (close) {
+                lines[j] = ''
+                i = j
+                break
+            }
+            lines[j] = ''
+            i = j
+        }
+        const track = m[2] ?? ''
+        const expr = parts.join('\n').trim()
+        if (!/^(\*|[a-zA-Z][a-zA-Z0-9]*)$/.test(track)) errors.push({ line: at, message: `play wants a track and what it plays: play <track> <expression>${track ? `, got ${track}` : ''}` })
+        else if (expr === '') errors.push({ line: at, message: `play ${track}: nothing to play` })
+        else if (section < 0) errors.push({ line: at, message: `play ${track}: a play belongs to a section, write it under one` })
+        else plays.push({ line: at, track, expr, section })
+    }
+    return { lines, code, plays, errors }
+}
+
+export interface ParseOptions {
+    /** the project CLI's film rows; null when the repo has no project CLI */
+    verbs?: readonly FilmVerb[] | null
+}
+
+/** the file as a trailer, and every error with its line */
+/** a film line's option lines: the lines under it indented deeper, each `key value`, taken out before the words are
+ *  read (their lines blank, so every line keeps its number) and kept by the film line's number */
+export function filmOptionLines(lines: string[]): Map<number, { line: number; text: string }[]> {
+    const out = new Map<number, { line: number; text: string }[]>()
+    const indent = (l: string): number => l.length - l.trimStart().length
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^(\s*)film(\s|$)/.exec(lines[i]!)
+        if (!m) continue
+        const head = i + 1
+        const own: { line: number; text: string }[] = []
+        for (let j = i + 1; j < lines.length; j++) {
+            const l = lines[j]!
+            if (l.trim() === '' || l.trimStart().startsWith('#')) continue
+            if (indent(l) <= m[1]!.length) break
+            own.push({ line: j + 1, text: l })
+            lines[j] = ''
+            i = j
+        }
+        if (own.length) out.set(head, own)
+    }
+    return out
+}
+
+export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Trailer; errors: TrailerError[] } {
+    const verbs = o.verbs ?? null
+    const t: Trailer = { name: '', footage: [], size: [1920, 1080], fps: 30, music: null, duck: -10, duckSfx: null, fadeIn: 0, shots: [], sections: [], score: null, timelineAt: null, vertical: null, base: null }
+    const errors: TrailerError[] = []
+    const seen = new Set<string>()
+    let shot: Shot | null = null
+    let pending: SectionRef | null = null
+    let current: Section | null = null
+    /** the `at`s that name a mark, set once every shot has landed */
+    const refs: { line: number; shot: Shot; ref: MarkAt; set: (at: number) => void }[] = []
+    const landAt = (v: unknown, line: number, s: Shot, set: (at: number) => void): number => {
+        if (typeof v !== 'object' || v === null) return (v as number | undefined) ?? 0
+        refs.push({ line, shot: s, ref: v as MarkAt, set })
+        return 0
+    }
+    clock = null
+    const pre = scoreLines(text)
+    errors.push(...pre.errors)
+    const lines = pre.lines
+    const options = filmOptionLines(lines)
+    const presets = new Map<string, Word[]>()
+    /** the film slots that wait on a moment: resolved once the shots have landed, each plus its shot's `from` */
+    const slots: { shot: Shot; film: Extract<Film, { kind: 'cli' }>; slot: Typed['times'][number] }[] = []
+    /** a time as a declared word reads it, at the clock of its line; null when it is none */
+    const momentWord = (w: string): Moment | null => {
+        const m = new RegExp(`^(${MOMENT})(?:([+-])(\\d.*))?$`).exec(w)
+        // a bare number is seconds, as a cue of a take counts them
+        if (!m) return /^\d+(\.\d+)?$/.test(w) ? Number(w) : parseTime(w, clock)
+        const off = m[3] === undefined ? 0 : parseTime(m[3], clock)
+        return off === null ? null : { mark: m[1]!, offset: m[2] === '-' ? -off : off }
+    }
+    for (let n = 1; n <= lines.length; n++) {
+        const tk = tokens(lines[n - 1]!)
+        if ('error' in tk) {
+            errors.push({ line: n, message: tk.error })
+            // its own line failed: the shot is not also told it films nothing
+            if (shot && /^\s*film(\s|$)/.test(lines[n - 1]!)) shot.broken = true
+            continue
+        }
+        const ws = tk.words
+        if (ws.length === 0) continue
+        const head = ws[0]!
+        const rest = ws.slice(1)
+        const once = (key: string): void => {
+            if (seen.has(key)) bad(`${key} given twice`)
+            seen.add(key)
+        }
+        try {
+            if (head.quoted) bad(`a line starts with a word, got "${head.text}"`)
+            if (head.text === 'section') {
+                const name = word('section', rest[0], /^[a-z0-9][a-z0-9-]*$/)
+                const last = t.sections.at(-1)
+                if (t.sections.some((x) => x.name === name)) bad(`section ${name} is already a section of this file`)
+                const p = pairs(`section ${name}`, rest.slice(2), {
+                    tempo: (w, k) => num(k, w, 20, 400),
+                    meter: (w, k) => num(k, w, 1, 16),
+                    grid: (w, k) => num(k, w, 1, 32),
+                })
+                const base = last?.clock ?? t.score?.clock ?? null
+                if (!base && !p.tempo && (p.meter || p.grid)) bad(`section ${name}: meter and grid count in a tempo, give it tempo <bpm>`)
+                clock = p.tempo || base ? { ...(base ?? { bpm: 120, meter: 4, grid: 4 }), ...(p.tempo ? { bpm: p.tempo as number } : {}), ...(p.meter ? { meter: p.meter as number } : {}), ...(p.grid ? { grid: p.grid as number } : {}) } : null
+                const seconds = +time(`section ${name}`, rest[1]).toFixed(6)
+                if (seconds <= 0) bad(`section ${name}: its length must be above 0`)
+                const at = last ? +(last.at + last.seconds).toFixed(6) : 0
+                current = { line: n, name, clock, at, seconds, marks: [], drums: {}, plays: [] }
+                t.sections.push(current)
+                pending = { line: n, name, at }
+                continue
+            }
+            if (head.text === 'drums') {
+                const into = current?.drums ?? (shot === null && t.score ? t.score.drums : bad('drums names the score\'s drum letters: write it after the score line, or under a section'))
+                if (rest.length === 0) bad('drums wants <letter>=<instrument> …')
+                for (const w of rest) {
+                    const m = !w.quoted ? /^([A-Za-z])=([a-zA-Z][a-zA-Z0-9]*)$/.exec(w.text) : null
+                    if (!m) bad(`drums wants <letter>=<instrument>, got ${w.text}`)
+                    into[m![1]!] = m![2]!
+                }
+                continue
+            }
+            if (head.text === 'stop') {
+                const sec = current ?? bad('a stop is a moment of a section: write it under one')
+                const sc = t.score ?? bad('stop cuts the score dead: write score tempo <bpm> in the header')
+                if (sc.stop) bad(`the score already stops on line ${sc.stop.line}`)
+                if (rest[0]?.text !== 'at' || rest.length !== 2) bad('stop wants at <time>, from its section\'s start')
+                const at = time('stop', rest[1])
+                if (at > sec.seconds) bad(`stop at ${+at.toFixed(3)} s is past section ${sec.name}'s ${+sec.seconds.toFixed(3)} s`)
+                sc.stop = { line: n, at: +(sec.at + at).toFixed(6) }
+                continue
+            }
+            if (head.text === 'defaults') {
+                const sec = current ?? bad('defaults are the film words of a section: write it under one')
+                if (sec.defaults) bad(`section ${sec.name} already has its defaults`)
+                if (rest.length === 0) bad('defaults wants film words: defaults <word> <value> …')
+                sec.defaults = rest.map((w) => ({ ...w, line: n }))
+                continue
+            }
+            if (head.text === 'mark') {
+                const sec = current ?? bad('a mark is a moment of a section: write it under one')
+                const name = word('mark', rest[0], new RegExp(`^${MOMENT}$`))
+                if (rest[1]?.text !== 'at' || rest.length !== 3) bad(`mark ${name} wants at <time>, from its section's start`)
+                if (t.sections.some((x) => x.name === name || x.marks.some((m) => m.name === name))) bad(`mark ${name}: ${name} already names a section or a mark`)
+                const at = time(`mark ${name}`, rest[2])
+                if (at >= sec.seconds) bad(`mark ${name} at ${+at.toFixed(3)} s is past section ${sec.name}'s ${+sec.seconds.toFixed(3)} s`)
+                sec.marks.push({ line: n, name, at })
+                continue
+            }
+            if (head.text === 'footage') {
+                // a block filmed like a shot and never cut in: only a grid or a split reads it
+                const open: Shot = { line: n, name: rest[0]?.text ?? '', length: 0, film: null, titles: [], sfx: [], voices: [], cut: { line: n, kind: 'hard', seconds: 0 }, from: 0, push: null, frame: null, shakes: [], flashes: [], music: null, broken: true, offcut: true }
+                shot = open
+                t.footage.push(open)
+                const name = word('footage', rest[0], /^[a-z0-9][a-z0-9-]*$/)
+                if ([...t.shots, ...t.footage].some((s) => s !== open && s.name === name)) bad(`footage ${name}: ${name} is already a shot or footage of this file`)
+                const length = time(`footage ${name}`, rest[1])
+                if (length <= 0) bad(`footage ${name}: its length must be above 0`)
+                if (rest.length > 2) bad(`footage ${name} ${rest[1]?.text}: unknown word ${rest[2]?.text} (a footage line is footage <name> <length>)`)
+                open.name = name
+                open.length = length
+                delete open.broken
+                continue
+            }
+            if (head.text === 'shot') {
+                // a bad shot line still opens a shot, so its own lines never read as the header's or the shot before's
+                const open: Shot = { line: n, name: rest[0]?.text ?? '', length: 0, film: null, titles: [], sfx: [], voices: [], cut: { line: n, kind: 'hard', seconds: 0 }, from: 0, push: null, frame: null, shakes: [], flashes: [], music: null, broken: true }
+                shot = open
+                t.shots.push(open)
+                const name = word('shot', rest[0], /^[a-z0-9][a-z0-9-]*$/)
+                if ([...t.shots, ...t.footage].some((s) => s !== open && s.name === name)) bad(`shot ${name} is already a shot or footage of this file`)
+                const length = time(`shot ${name}`, rest[1])
+                if (length <= 0) bad(`shot ${name}: its length must be above 0`)
+                if (rest.length > 2) bad(`shot ${name} ${rest[1]?.text}: unknown word ${rest[2]?.text} (a shot line is shot <name> <length>)`)
+                open.name = name
+                open.length = length
+                if (pending) open.section = pending
+                pending = null
+                delete open.broken
+                continue
+            }
+            if (shot === null) {
+                switch (head.text) {
+                    case 'trailer':
+                        once('trailer')
+                        t.name = word('trailer', rest[0], /^[a-z0-9][a-z0-9-]*$/)
+                        if (rest.length > 1) bad(`trailer ${t.name}: unknown word ${rest[1]?.text}`)
+                        break
+                    case 'size': {
+                        once('size')
+                        const m = rest[0] && !rest[0].quoted ? /^(\d+)x(\d+)$/.exec(rest[0].text) : null
+                        const w = Number(m?.[1])
+                        const h = Number(m?.[2])
+                        if (!m || w < 160 || h < 90 || w > 3840 || h > 3840 || w % 2 || h % 2)
+                            bad(`size wants WxH, even, from 160x90 to 3840x3840${rest[0] ? `, got ${rest[0].text}` : ''}`)
+                        t.size = [w, h]
+                        break
+                    }
+                    case 'fps':
+                        once('fps')
+                        t.fps = num('fps', rest[0], 1, FPS_MAX)
+                        if (!Number.isInteger(t.fps)) bad(`fps wants a whole number, got ${rest[0]?.text}`)
+                        break
+                    case 'music':
+                        once('music')
+                        t.music = musicLine(rest, n, true)
+                        if (t.music.song === NO_MUSIC) bad('music none is a shot\'s cue, the header names the song the cut opens on')
+                        break
+                    case 'duck': {
+                        once('duck')
+                        const drop = (w: Word | undefined, what: string): number => {
+                            const m = w && !w.quoted ? /^(-?\d+(?:\.\d+)?)(?:dB)?$/.exec(w.text) : null
+                            const db = Number(m?.[1])
+                            if (!m || db > 0 || db < -40) bad(`${what} wants a drop in dB from -40 to 0 (-10dB)${w ? `, got ${w.text}` : ''}`)
+                            return db
+                        }
+                        t.duck = drop(rest[0], 'duck')
+                        if (rest.length > 1) {
+                            if (rest[1]!.text !== 'sfx' || rest.length !== 3) bad(`duck takes its drop, then sfx and the drop under each sfx (duck -10dB sfx -5dB), got ${rest.slice(1).map((w) => w.text).join(' ')}`)
+                            t.duckSfx = drop(rest[2], 'duck sfx')
+                        }
+                        break
+                    }
+                    case 'fade-in':
+                        once('fade-in')
+                        t.fadeIn = time('fade-in', rest[0])
+                        break
+                    case 'vertical': {
+                        once('vertical')
+                        const p = pairs('vertical', rest, {
+                            mark: (w, k) => {
+                                const c = word(k, w)
+                                return c === 'left' || c === 'right' ? c : bad(`${k} wants left|right, got ${c}`)
+                            },
+                            outro: (w, k) => {
+                                const o = pathWord(k, w)
+                                if (o === 'card' || o === 'none') return o
+                                if (!/\.(mp4|webm|mov|mkv)$/i.test(o)) bad(`${k} wants card, none or a video file, got ${o}`)
+                                return { clip: o }
+                            },
+                        })
+                        t.vertical = { line: n, outro: (p.outro as Vertical['outro'] | undefined) ?? 'card', ...(p.mark ? { mark: p.mark as 'left' | 'right' } : {}) }
+                        break
+                    }
+                    case 'preset': {
+                        const name = word('preset', rest[0], /^[a-z][a-z0-9-]*$/)
+                        if (presets.has(name)) bad(`preset ${name} is already a preset of this file`)
+                        const words = rest.slice(1)[0]?.text === '=' && !rest[1]!.quoted ? rest.slice(2) : rest.slice(1)
+                        if (words.length === 0) bad(`preset ${name} wants film words: preset ${name} <word> <value> …`)
+                        presets.set(name, words.map((w) => ({ ...w, line: n })))
+                        break
+                    }
+                    case 'base':
+                        once('base')
+                        t.base = word('base', rest[0], /^[a-z0-9][a-z0-9-]*$/)
+                        if (rest.length > 1) bad(`base ${t.base}: unknown word ${rest[1]?.text} (base <the id of a global process of this repo>)`)
+                        break
+                    case 'score': {
+                        once('score')
+                        if (t.sections.length > 0) bad('score opens the music the sections play: write it before the first section')
+                        const sc: Score = { line: n, clock: { bpm: 120, meter: 4, grid: 4 }, fadeIn: 0, volume: 1, tracks: [], drums: {}, code: pre.code }
+                        // reverb takes two values, so the words are read here rather than by pairs
+                        const p: Record<string, number> = {}
+                        for (let i = 0; i < rest.length; i++) {
+                            const k = rest[i]!.text
+                            if (rest[i]!.quoted || !['tempo', 'meter', 'grid', 'reverb', 'fade-in', 'volume'].includes(k))
+                                bad(`score: unknown word ${k} (score takes tempo, meter, grid, reverb, fade-in, volume)`)
+                            if (k in p) bad(`score: ${k} given twice`)
+                            if (k === 'reverb') {
+                                sc.reverb = { seconds: num('score reverb <seconds> <mix>', rest[i + 1], 0.1, 10), mix: num('score reverb <seconds> <mix>', rest[i + 2], 0, 1) }
+                                p[k] = 1
+                                i += 2
+                            } else if (k === 'fade-in') p[k] = time('score fade-in', rest[++i])
+                            else p[k] = num(`score ${k}`, rest[++i], k === 'tempo' ? 20 : k === 'volume' ? 0 : 1, k === 'tempo' ? 400 : k === 'grid' ? 32 : k === 'volume' ? 4 : 16)
+                        }
+                        if (p.tempo === undefined) bad('score wants its tempo: score tempo <bpm>')
+                        sc.clock = { bpm: p.tempo!, meter: p.meter ?? 4, grid: p.grid ?? 4 }
+                        sc.fadeIn = p['fade-in'] ?? 0
+                        sc.volume = p.volume ?? 1
+                        t.score = sc
+                        clock = sc.clock
+                        break
+                    }
+                    case 'track': {
+                        const sc = t.score ?? bad('a track is a voice of the score: write score tempo <bpm> first')
+                        const name = word('track', rest[0], /^[a-zA-Z][a-zA-Z0-9]*$/)
+                        const instrument = word(`track ${name}`, rest[1], /^[a-zA-Z][a-zA-Z0-9]*$/)
+                        if (sc.tracks.some((x) => x.name === name)) bad(`track ${name} is already a track of the score`)
+                        if (sc.tracks.length >= TRACKS_MAX) bad(`track ${name}: the score holds ${TRACKS_MAX} tracks at most`)
+                        const p = pairs(`track ${name}`, rest.slice(2), { volume })
+                        sc.tracks.push({ line: n, name, instrument, volume: (p.volume as number) ?? 1 })
+                        break
+                    }
+                    default:
+                        bad(`unknown word ${head.text} before the first shot (trailer, size, fps, music, duck, fade-in, vertical, base, preset, score, track, drums, section, defaults, shot)`)
+                }
+                continue
+            }
+            const s: Shot = shot
+            if (s.offcut && !['film', 'from', 'frame'].includes(head.text)) bad(`footage ${s.name} is never cut in: it takes film, from and frame, never ${head.text}`)
+            switch (head.text) {
+                case 'film':
+                    if (s.film) bad(`shot ${s.name} already films on line ${s.film.line}: one film line a shot`)
+                    {
+                        // its option lines, each word keeping its own line
+                        const more: Word[] = []
+                        for (const o of options.get(n) ?? []) {
+                            const tk = tokens(o.text)
+                            if ('error' in tk) errors.push({ line: o.line, message: tk.error })
+                            else more.push(...tk.words.map((w) => ({ ...w, line: o.line })))
+                        }
+                        s.film = filmLine([...rest.map((w) => ({ ...w, line: n })), ...more], n, verbs, {
+                            defaults: s.offcut ? [] : (current?.defaults ?? []),
+                            presets,
+                            time: momentWord,
+                            later: (film, slot) => slots.push({ shot: s, film, slot }),
+                            errors,
+                        })
+                    }
+                    break
+                case 'title': {
+                    const text = quoted('title', rest[0])
+                    const p = pairs('title', rest.slice(1), {
+                        at: when,
+                        for: at,
+                        style: (w, k) => {
+                            const st = word(k, w)
+                            return (TITLE_STYLES as readonly string[]).includes(st) ? st : bad(`${k} wants ${TITLE_STYLES.join('|')}, got ${st}`)
+                        },
+                        place: (w, k) => {
+                            const pl = word(k, w)
+                            return pl === 'top' || pl === 'bottom' ? pl : bad(`${k} wants top|bottom, got ${pl}`)
+                        },
+                        knock: at,
+                    })
+                    const ti: Title = {
+                        line: n,
+                        text,
+                        at: 0,
+                        for: (p.for as number) ?? null,
+                        style: (p.style as TitleStyle) ?? 'caption',
+                        ...(p.place ? { place: p.place as 'top' | 'bottom' } : {}),
+                        ...(p.knock !== undefined ? { knock: p.knock as number } : {}),
+                    }
+                    ti.at = landAt(p.at, n, s, (v) => (ti.at = v))
+                    if (ti.knock !== undefined && (ti.knock <= ti.at || (ti.for !== null && ti.knock >= ti.at + ti.for)))
+                        bad(`title knock ${ti.knock}s: inside the title's own span, after its at`)
+                    s.titles.push(ti)
+                    break
+                }
+                case 'progress': {
+                    const names = quoted('progress', rest[0]).split('|').map((x) => x.trim())
+                    if (names.length < 2 || names.some((x) => x === '')) bad('progress wants two or more step names, "<a>|<b>|…"')
+                    const p = pairs('progress', rest.slice(1), {
+                        at: when,
+                        every: at,
+                        place: (w, k) => {
+                            const pl = word(k, w)
+                            return pl === 'top' || pl === 'bottom' ? pl : bad(`${k} wants top|bottom, got ${pl}`)
+                        },
+                    })
+                    const every = (p.every as number | undefined) ?? bad('progress wants every <time>: how long each step stands')
+                    names.forEach((text, k) => {
+                        const ti: Title = { line: n, text, at: 0, for: every, style: 'progress', step: { i: k + 1, n: names.length }, ...(p.place ? { place: p.place as 'top' | 'bottom' } : {}) }
+                        ti.at = landAt(p.at, n, s, (v) => (ti.at = v + k * every)) + k * every
+                        s.titles.push(ti)
+                    })
+                    break
+                }
+                case 'sfx': {
+                    const id = pathWord('sfx', rest[0])
+                    const p = pairs(`sfx ${id}`, rest.slice(1), { at: when, volume })
+                    const x: Sfx = { line: n, id, at: 0, volume: (p.volume as number) ?? 1 }
+                    x.at = landAt(p.at, n, s, (v) => (x.at = v))
+                    s.sfx.push(x)
+                    break
+                }
+                case 'voice': {
+                    const fileForm = rest[0] && !rest[0].quoted && rest[0].text === 'file'
+                    const src = fileForm ? { file: pathWord('voice file', rest[1]) } : { text: quoted('voice', rest[0]) }
+                    const p = pairs('voice', rest.slice(fileForm ? 2 : 1), { at: when, volume })
+                    const v: Voice = { line: n, ...src, at: 0, volume: (p.volume as number) ?? 1 }
+                    v.at = landAt(p.at, n, s, (x) => (v.at = x))
+                    s.voices.push(v)
+                    break
+                }
+                case 'cut': {
+                    if (s.cut.line !== s.line) bad(`shot ${s.name} already cuts on line ${s.cut.line}`)
+                    const k = word('cut', rest[0])
+                    if (!(CUT_KINDS as readonly string[]).includes(k)) bad(`cut: unknown kind ${k} (${CUT_KINDS.join(', ')})`)
+                    const seconds = k === 'hard' ? 0 : rest[1] ? time(`cut ${k}`, rest[1]) : DEFAULT_CUT_S
+                    if (k === 'hard' && rest[1]) bad('cut hard takes no time')
+                    if (rest.length > 2) bad(`cut ${k}: unknown word ${rest[2]?.text}`)
+                    s.cut = { line: n, kind: k as CutKind, seconds }
+                    break
+                }
+                case 'music':
+                    if (s.music) bad(`shot ${s.name} already changes the music on line ${s.music.line}`)
+                    if (t.score && t.sections.length > 0) bad('music: the score plays from its first section on; a song plays only before it')
+                    s.music = musicLine(rest, n)
+                    break
+                case 'starts': {
+                    if (s.lands) bad(`shot ${s.name} already lands on line ${s.lands.line}`)
+                    if (rest[0]?.text !== 'on' || !rest[1] || rest.length > 3) bad('starts wants on <section|mark> [+|-<time>]')
+                    const on = word('starts on', rest[1], /^[a-z0-9][a-z0-9-]*$/)
+                    const o2 = rest[2] && !rest[2].quoted ? /^([+-])(.+)$/.exec(rest[2].text) : null
+                    if (rest[2] && !o2) bad(`starts on ${on}: the time from it is signed, +0.5s or -1beat, got ${rest[2].text}`)
+                    const off = o2 ? time(`starts on ${on}`, { text: o2[2]!, quoted: false }) : 0
+                    s.lands = { line: n, on, offset: o2?.[1] === '-' ? -off : off }
+                    break
+                }
+                case 'from':
+                    s.from = time('from', rest[0])
+                    if (rest.length > 1) bad(`from: unknown word ${rest[1]?.text}`)
+                    break
+                case 'push':
+                    s.push = num('push', rest[0], 1, 3)
+                    if (rest.length > 1) bad(`push: unknown word ${rest[1]?.text}`)
+                    break
+                case 'lift':
+                    s.lift = num('lift', rest[0], 1, 2)
+                    if (rest.length > 1) bad(`lift: unknown word ${rest[1]?.text}`)
+                    break
+                case 'frame':
+                    if (s.frame !== null) bad(`shot ${s.name} already frames its footage`)
+                    s.frame = num('frame', rest[0], 1, 3)
+                    if (rest[1]?.text === 'at' && !rest[1].quoted) {
+                        const m = /^(\d*\.?\d+),(\d*\.?\d+)$/.exec(rest[2] && !rest[2].quoted ? rest[2].text : '')
+                        if (!m || Number(m[1]) > 1 || Number(m[2]) > 1) bad(`frame at wants a point <x>,<y>, each 0 to 1 across and down the frame${rest[2] ? `, got ${rest[2].text}` : ''}`)
+                        else s.frameAt = [Number(m[1]), Number(m[2])]
+                        if (rest.length > 3) bad(`frame: unknown word ${rest[3]?.text}`)
+                    } else if (rest.length > 1) bad(`frame: unknown word ${rest[1]?.text}`)
+                    break
+                case 'shake': {
+                    const p = pairs('shake', rest, { at: when, for: at, strength: (w, k) => num(k, w, 0.2, 3) })
+                    const x: Shake = { line: n, at: 0, for: (p.for as number) ?? 0.4, strength: (p.strength as number) ?? 1 }
+                    x.at = landAt(p.at, n, s, (v) => (x.at = v))
+                    s.shakes.push(x)
+                    break
+                }
+                case 'flash': {
+                    const p = pairs('flash', rest, { at: when, for: at })
+                    const x: Flash = { line: n, at: 0, for: (p.for as number) ?? 0.25 }
+                    x.at = landAt(p.at, n, s, (v) => (x.at = v))
+                    s.flashes.push(x)
+                    break
+                }
+                default:
+                    bad(`unknown word ${head.text} in shot ${s.name} (film, title, progress, sfx, voice, music, starts, cut, from, push, frame, lift, shake, flash, shot)`)
+            }
+        } catch (e) {
+            if (!(e instanceof LineError)) throw e
+            errors.push({ line: n, message: e.message })
+            if (shot && head.text === 'film') shot.broken = true
+        }
+    }
+    if (!seen.has('trailer')) errors.push({ line: 1, message: 'the file names its trailer first: trailer <name>' })
+    if (t.shots.length === 0) errors.push({ line: lines.length, message: 'no shot: a trailer has at least one shot <name> <length>' })
+    if (t.vertical && !seen.has('size')) t.size = [...VERTICAL_SIZE]
+    else if (t.vertical && t.size[0] >= t.size[1]) errors.push({ line: t.vertical.line, message: `vertical: a short is filmed upright, its size taller than wide (1080x1920), not ${t.size.join('x')}` })
+    clock = null
+    for (const pl of pre.plays) {
+        const sec = t.sections[pl.section]
+        if (!sec) continue
+        if (!t.score) errors.push({ line: pl.line, message: `play ${pl.track}: a play is the score's: write score tempo <bpm> in the header` })
+        else if (pl.track !== '*' && !t.score.tracks.some((x) => x.name === pl.track))
+            errors.push({ line: pl.line, message: `play ${pl.track}: no track ${pl.track} (${t.score.tracks.map((x) => x.name).join(', ') || 'the score has no track: track <name> <instrument>'})` })
+        else if (sec.plays.some((x) => x.track === pl.track)) errors.push({ line: pl.line, message: `play ${pl.track}: section ${sec.name} already plays it` })
+        else sec.plays.push({ line: pl.line, track: pl.track, expr: pl.expr })
+    }
+    if (pre.code && !t.score) errors.push({ line: pre.code.line, message: 'code is the score\'s: write score tempo <bpm> in the header' })
+    if (t.score && t.sections.length === 0) errors.push({ line: t.score.line, message: 'the score has no section: section <name> <length> under the header, its plays under it' })
+    errors.push(...landShots(t))
+    if (t.score && t.sections.length > 0 && t.timelineAt === null && !t.shots.some((s) => s.broken))
+        errors.push({ line: t.score.line, message: 'no shot lands on a section, so the score never plays: put a shot under a section, or starts on <section>' })
+    for (const r of refs) {
+        const i = t.shots.indexOf(r.shot)
+        const m = momentOf(t, r.ref.mark)
+        if (m === null || t.timelineAt === null) errors.push({ line: r.line, message: `at ${r.ref.mark}: no section or mark ${r.ref.mark} in this file` })
+        else r.set(+(t.timelineAt + m + r.ref.offset - (starts(t)[i] ?? 0)).toFixed(4))
+    }
+    for (const p of slots) {
+        const i = t.shots.indexOf(p.shot)
+        const parts = p.slot.parts.map((x) => {
+            if (typeof x.at === 'number') return { name: x.name, seconds: x.at + p.shot.from }
+            const m = momentOf(t, x.at.mark)
+            if (i < 0) errors.push({ line: x.line, message: `film: ${x.at.mark} is a moment of the cut, and footage ${p.shot.name} is never cut in: write seconds` })
+            else if (m === null || t.timelineAt === null) errors.push({ line: x.line, message: `film: no section or mark ${x.at.mark} in this file` })
+            else return { name: x.name, seconds: +(t.timelineAt + m + x.at.offset - (starts(t)[i] ?? 0) + p.shot.from).toFixed(4) }
+            return { name: x.name, seconds: 0 }
+        })
+        p.film.argv[p.slot.index] = slotText(parts)
+    }
+    errors.push(...structure(t), ...grids(t))
+    return { trailer: t, errors: errors.sort((a, b) => a.line - b.line) }
+}
+
+/** the least a fitted shot keeps past its cut out */
+const FIT_MIN_S = 0.3
+
+/** a section's start, or a mark's moment, in the timeline's seconds; null when no section or mark has that name */
+function momentOf(t: Pick<Trailer, 'sections'>, name: string): number | null {
+    for (const sec of t.sections) {
+        if (sec.name === name) return sec.at
+        const m = sec.marks.find((x) => x.name === name)
+        if (m) return sec.at + m.at
+    }
+    return null
+}
+
+/**
+ * every shot that lands on the timeline starts at its moment: the first one sets where the timeline starts on the cut,
+ * and the shot before each later one takes the length that lands it (fitted). An edit inside a section moves nothing
+ * past the next landed shot
+ */
+function landShots(t: Trailer): TrailerError[] {
+    const out: TrailerError[] = []
+    t.shots.forEach((s, i) => {
+        if (s.broken) return
+        const land = s.lands ?? (s.section ? { line: s.section.line, on: s.section.name, offset: 0 } : null)
+        if (!land) return
+        const moment = momentOf(t, land.on)
+        if (moment === null) {
+            out.push({ line: land.line, message: `starts on ${land.on}: no section or mark ${land.on} in this file` })
+            return
+        }
+        const st = starts(t)
+        if (t.timelineAt === null) {
+            t.timelineAt = +((st[i] ?? 0) - moment - land.offset).toFixed(4)
+            return
+        }
+        const prev = t.shots[i - 1]
+        if (!prev || prev.broken) {
+            out.push({ line: land.line, message: `shot ${s.name}: no shot before it to fit` })
+            return
+        }
+        const length = prev.length + (t.timelineAt + moment + land.offset - (st[i] ?? 0))
+        if (length - prev.cut.seconds < FIT_MIN_S) {
+            out.push({ line: land.line, message: `shot ${s.name} lands on ${land.on}: shot ${prev.name} would last ${+length.toFixed(2)} s, too short; the shots before run ${+(prev.length - length).toFixed(2)} s long` })
+            return
+        }
+        prev.written ??= prev.length
+        prev.length = +length.toFixed(4)
+    })
+    return out
+}
+
+/** a film that is one picture held for the shot */
+export const isStill = (f: Film | null): boolean =>
+    f?.kind === 'card' || f?.kind === 'image' || ((f?.kind === 'run' || f?.kind === 'url') && f.still === true) || (f?.kind === 'cli' && f.output === 'still')
+
+/** what the lines say together: a film per shot, titles inside their shot, cuts shorter than what they join */
+function structure(t: Trailer): TrailerError[] {
+    const out: TrailerError[] = []
+    t.shots.forEach((s, i) => {
+        if (s.broken) return
+        if (!s.film) out.push({ line: s.line, message: `shot ${s.name} films nothing: give it a film line` })
+        if (isStill(s.film) && s.from > 0) out.push({ line: s.line, message: `shot ${s.name}: its film is a still image, no footage to skip (from)` })
+        if ((s.film?.kind === 'grid' || s.film?.kind === 'split') && s.from > 0) out.push({ line: s.line, message: `shot ${s.name}: a ${s.film.kind} has no footage of its own to skip; each cell's from skips its own` })
+        // a title may run on over the shots after its own (a caption over a montage), never past the cut's end
+        const left = total(t) - (starts(t)[i] ?? 0)
+        for (const ti of s.titles) {
+            // a progress line's later steps run on over the next shots, as a `for` past its shot does
+            if (ti.at >= s.length && !(ti.step && ti.step.i > 1)) out.push({ line: ti.line, message: `title at ${ti.at} s starts past shot ${s.name}'s ${s.length} s` })
+            else if (ti.for !== null && ti.at + ti.for > left + 1e-9) out.push({ line: ti.line, message: `title ends ${+(ti.at + ti.for - left).toFixed(2)} s past the cut's end` })
+        }
+        for (const x of [...s.sfx, ...s.voices]) if (x.at >= s.length) out.push({ line: x.line, message: `${'id' in x ? 'sfx' : 'voice'} at ${x.at} s starts past shot ${s.name}'s ${s.length} s` })
+        for (const x of [...s.shakes, ...s.flashes]) if (x.at >= s.length) out.push({ line: x.line, message: `${'strength' in x ? 'shake' : 'flash'} at ${x.at} s starts past shot ${s.name}'s ${s.length} s` })
+        const next = t.shots[i + 1]
+        if (s.cut.seconds > 0) {
+            if (s.cut.seconds >= s.length) out.push({ line: s.cut.line, message: `cut ${s.cut.kind} ${s.cut.seconds} s is as long as shot ${s.name} or longer` })
+            else if (next && !next.broken && s.cut.seconds >= next.length) out.push({ line: s.cut.line, message: `cut ${s.cut.kind} ${s.cut.seconds} s is as long as the next shot ${next.name} or longer` })
+            if (!next && !['fade', 'dip-black', 'dip-white'].includes(s.cut.kind)) out.push({ line: s.cut.line, message: `the last shot ends on fade, dip-black or dip-white, never ${s.cut.kind}` })
+        }
+        const prev = t.shots[i - 1]
+        if (prev && next && prev.cut.seconds < s.length && s.cut.seconds < s.length && prev.cut.seconds + s.cut.seconds >= s.length)
+            out.push({ line: s.line, message: `shot ${s.name} is all cut: the cuts in and out (${prev.cut.seconds} s + ${s.cut.seconds} s) leave nothing of its ${s.length} s` })
+    })
+    const music = t.music
+    if (music && music.fadeIn + music.fadeOut > total(t)) out.push({ line: music.line, message: `music fades for longer than the cut's ${total(t).toFixed(2)} s` })
+    return out
+}
+
+/** the shots and footage blocks a grid's or a split's cells name */
+export function gridCells(t: Pick<Trailer, 'shots' | 'footage'>, cells: readonly string[]): (Shot | undefined)[] {
+    return cells.map((c) => [...t.footage, ...t.shots].find((s) => s.name === c))
+}
+
+/** a cell plays filmed footage: a take that is a clip, never a grid, a split, a card, an image or a still */
+export const isCellFilm = (f: Film | null): boolean => (f?.kind === 'run' || f?.kind === 'url' || f?.kind === 'cli') && !isStill(f)
+
+/** what a grid or a split names, and what a footage block films */
+function grids(t: Trailer): TrailerError[] {
+    const out: TrailerError[] = []
+    for (const s of [...t.shots, ...t.footage]) {
+        if (s.broken || (s.film?.kind !== 'grid' && s.film?.kind !== 'split')) continue
+        const f = s.film
+        if (s.offcut) {
+            out.push({ line: f.line, message: `footage ${s.name}: a ${f.kind} is laid by the stitch, never a footage block` })
+            continue
+        }
+        gridCells(t, f.cells).forEach((c, i) => {
+            const name = f.cells[i]
+            if (!c) out.push({ line: f.line, message: `film ${f.kind}: no shot or footage ${name} in this file` })
+            else if (c.film && !isCellFilm(c.film)) out.push({ line: f.line, message: `film ${f.kind}: ${name} is a ${c.film.kind === 'cli' || c.film.kind === 'run' || c.film.kind === 'url' ? 'still' : c.film.kind}, a cell plays filmed footage` })
+        })
+    }
+    for (const s of t.footage) {
+        if (s.broken) continue
+        if (!s.film) out.push({ line: s.line, message: `footage ${s.name} films nothing: give it a film line` })
+        else if (s.film.kind !== 'grid' && s.film.kind !== 'split' && !isCellFilm(s.film)) out.push({ line: s.film.line, message: `footage ${s.name}: a ${s.film.kind === 'cli' || s.film.kind === 'run' || s.film.kind === 'url' ? 'still' : s.film.kind} is no footage a grid plays` })
+    }
+    return out
+}
+
+/** each shot's start on the cut: a cut overlaps the two shots it joins */
+export function starts(t: Pick<Trailer, 'shots'>): number[] {
+    const out: number[] = []
+    let at = 0
+    for (const s of t.shots) {
+        out.push(at)
+        at += s.length - s.cut.seconds
+    }
+    return out
+}
+
+/** the cut's length: the last shot's ending is inside its own length */
+export function total(t: Pick<Trailer, 'shots'>): number {
+    const last = t.shots.at(-1)
+    if (!last) return 0
+    return (starts(t).at(-1) ?? 0) + last.length
+}
+
+/** the music of the cut, cue by cue: each its start on the cut and its end, a crossfade into the next over the next's
+ *  fade-in; a `none` cue is silence and carries no song */
+export function musicCues(t: Pick<Trailer, 'music' | 'shots' | 'score' | 'timelineAt'>): { cue: Music; at: number; end: number }[] {
+    const st = starts(t)
+    const sc = t.score
+    const raw: { cue: Music; at: number }[] = [
+        ...(t.music ? [{ cue: t.music, at: 0 }] : []),
+        ...t.shots.flatMap((s, i) => (s.music ? [{ cue: s.music, at: st[i] ?? 0 }] : [])),
+        ...(sc && t.timelineAt !== null ? [{ cue: { line: sc.line, song: SCORE, from: SCORE_LEAD, fadeIn: sc.fadeIn, fadeOut: 0, volume: sc.volume }, at: t.timelineAt }] : []),
+    ].sort((a, b) => a.at - b.at)
+    const T = total(t)
+    return raw
+        .map((r, i) => ({ ...r, end: Math.min(T, (raw[i + 1]?.at ?? T) + (raw[i + 1]?.cue.fadeIn ?? 0)) }))
+        .filter((r) => r.cue.song !== NO_MUSIC && r.end > r.at)
+}