rvlib-shipkit 2.1.0 → 2.2.0

package/src/trailer/grammar.ts

@@ -0,0 +1,915 @@
+// 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'
+export const TITLE_STYLES: readonly TitleStyle[] = ['logo', 'big', 'caption', 'corner', 'line']
+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'] as const
+
+/** the most frames a second a cut runs at */
+export const FPS_MAX = 60
+const DEFAULT_CUT_S = 0.5
+
+/** 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'
+    description?: string
+}
+
+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 */
+    | { kind: 'run'; line: number; cmd: string; still?: true }
+    /** a film row of the project CLI, its words as written: `<cli> <argv> --out <file> [--seconds <n>]` */
+    | { kind: 'cli'; line: number; argv: string[]; output: 'still' | 'clip' }
+    /** 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 }
+
+/** 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
+}
+
+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
+}
+
+/** 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 */
+export interface Section {
+    line: number
+    name: string
+    clock: Clock | null
+    /** where it starts on the timeline, seconds */
+    at: number
+    seconds: number
+    marks: Mark[]
+}
+
+export interface Trailer {
+    name: string
+    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[]
+    /** where the timeline of the sections 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
+}
+
+/** a line's words: a quoted run is one word (quoted), `#` outside quotes ends the line */
+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)
+            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 */
+function filmLine(ws: Word[], line: number, verbs: readonly FilmVerb[] | null): Film {
+    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`)
+    return { kind: 'cli', line, argv, output: v.film }
+}
+
+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), {}, ['still'])
+            return { kind, line, cmd, ...(p.still ? { still: true as const } : {}) }
+        }
+        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 } : {}),
+            }
+        }
+    }
+    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,
+    }
+}
+
+/** words of the full trailer language a repo adds through its own words, not the core's */
+const NOT_CORE: Record<string, string> = {
+    score: 'a score the repo synthesizes',
+    track: 'a voice of a score',
+    drums: 'a score\'s drum letters',
+    code: 'a score\'s code block',
+    play: 'what a score track plays',
+    progress: 'a progress bar title',
+    footage: 'a footage block a grid reads',
+}
+const notCore = (w: string): string => `${w} is ${NOT_CORE[w]}: a word of the full trailer language the core does not read yet`
+
+/**
+ * the score's TypeScript (a margin `code` line and its indented block, a `play` line and the deeper lines that continue
+ * it) blanked before the words are read, each block reported once at its first line: every line keeps its number
+ */
+export function scoreBlocks(text: string): { lines: string[]; errors: TrailerError[] } {
+    const lines = text.split('\n')
+    const errors: TrailerError[] = []
+    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]!
+        const code = /^code\s*(#.*)?$/.test(l)
+        const play = /^(\s*)play(\s|$)/.exec(l)
+        if ((!code && !play) || off(l)) continue
+        errors.push({ line: i + 1, message: notCore(code ? 'code' : 'play') })
+        lines[i] = ''
+        const base = code ? 0 : play![1]!.length
+        for (let j = i + 1; j < lines.length; j++) {
+            const b = lines[j]!
+            const close = !code && indent(b) === base && /^[)\]}]/.test(b.trimStart())
+            if (b.trim() !== '' && !off(b) && indent(b) <= base && !close) break
+            lines[j] = ''
+            i = j
+            if (close) break
+        }
+    }
+    return { lines, 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 */
+export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Trailer; errors: TrailerError[] } {
+    const verbs = o.verbs ?? null
+    const t: Trailer = { name: '', size: [1920, 1080], fps: 30, music: null, duck: -10, duckSfx: null, fadeIn: 0, shots: [], sections: [], 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
+    let scoreClock: Clock | null = null
+    let skipping = false
+    /** 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 = scoreBlocks(text)
+    errors.push(...pre.errors)
+    const lines = pre.lines
+    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 })
+            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)
+        }
+        // a footage block's own lines belong to it: skipped with it, its one error at its line
+        if (skipping && !['shot', 'footage', 'section'].includes(head.text)) continue
+        skipping = false
+        try {
+            if (head.quoted) bad(`a line starts with a word, got "${head.text}"`)
+            if (head.text === 'footage') skipping = true
+            if (head.text in NOT_CORE) {
+                // a score's clock still counts the sections' bars, so one error stands for the score, not one per section
+                if (head.text === 'score') {
+                    const v = (k: string): number | undefined => {
+                        const i = rest.findIndex((w) => w.text === k)
+                        const x = i >= 0 ? Number(rest[i + 1]?.text) : Number.NaN
+                        return Number.isFinite(x) ? x : undefined
+                    }
+                    const bpm = v('tempo')
+                    if (bpm) scoreClock = { bpm, meter: v('meter') ?? 4, grid: v('grid') ?? 4 }
+                }
+                bad(notCore(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 ?? scoreClock
+                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: [] }
+                t.sections.push(current)
+                pending = { line: n, name, at }
+                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 === '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.some((s) => s !== open && s.name === name)) bad(`shot ${name} is already a shot 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 '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
+                    default:
+                        bad(`unknown word ${head.text} before the first shot (trailer, size, fps, music, duck, fade-in, vertical, base, section, shot)`)
+                }
+                continue
+            }
+            const s: Shot = shot
+            switch (head.text) {
+                case 'film':
+                    if (s.film) bad(`shot ${s.name} already films on line ${s.film.line}: one film line a shot`)
+                    s.film = filmLine(rest, n, verbs)
+                    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 '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}`)
+                    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, 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
+    errors.push(...landShots(t))
+    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))
+    }
+    errors.push(...structure(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)` })
+        // 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) {
+            if (ti.at >= s.length) 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
+}
+
+/** 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'>): { cue: Music; at: number; end: number }[] {
+    const st = starts(t)
+    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 }] : []))].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)
+}