rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/grammar.ts

@@ -1,9 +1,12 @@
+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'
-export const TITLE_STYLES: readonly TitleStyle[] = ['logo', 'big', 'caption', 'corner', 'line']
+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',
@@ -23,30 +26,71 @@ export const CUT_KINDS = [
     'pixel',
 ] as const
 export type CutKind = (typeof CUT_KINDS)[number]
-export const CORE_FILMS = ['clip', 'image', 'card', 'run', 'url'] as const
+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 */
-    | { 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' }
+    /** 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) */
@@ -72,6 +116,8 @@ export interface Title {
     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 {
@@ -159,6 +205,8 @@ export interface Shot {
     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 */
@@ -177,7 +225,8 @@ export interface Mark {
     at: number
 }
 
-/** a part of the timeline in bars: its shots land on its start, and the stitch caches it as one piece */
+/** 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
@@ -186,10 +235,48 @@ export interface Section {
     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
@@ -200,7 +287,9 @@ export interface Trailer {
     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 */
+    /** 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
@@ -216,9 +305,12 @@ export interface TrailerError {
 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 */
+/** 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
@@ -229,6 +321,11 @@ export function tokens(line: string): { words: Word[] } | { error: string } {
             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' }
@@ -356,7 +453,27 @@ const filmWords = (verbs: readonly FilmVerb[] | null): string =>
 
 /** 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 {
+/** 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)
@@ -369,7 +486,23 @@ function filmLine(ws: Word[], line: number, verbs: readonly FilmVerb[] | null):
     }
     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 }
+    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 {
@@ -392,8 +525,8 @@ function coreFilm(kind: string, ws: Word[], line: number): Film {
         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 } : {}) }
+            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])
@@ -408,6 +541,25 @@ function coreFilm(kind: string, ws: Word[], line: number): Film {
                 ...(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}`)
 }
@@ -442,45 +594,64 @@ function musicLine(rest: Word[], n: number, opening = false): Music {
     }
 }
 
-/** 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
+ * 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 scoreBlocks(text: string): { lines: string[]; errors: TrailerError[] } {
+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]!
-        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') })
+        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] = ''
-        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
+            // 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
-            if (close) break
         }
+        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, errors }
+    return { lines, code, plays, errors }
 }
 
 export interface ParseOptions {
@@ -489,16 +660,37 @@ export interface ParseOptions {
 }
 
 /** 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: '', size: [1920, 1080], fps: 30, music: null, duck: -10, duckSfx: null, fadeIn: 0, shots: [], sections: [], timelineAt: null, vertical: null, base: 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
-    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 => {
@@ -507,13 +699,27 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
         return 0
     }
     clock = null
-    const pre = scoreBlocks(text)
+    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
@@ -524,25 +730,8 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
             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)
@@ -552,17 +741,44 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     meter: (w, k) => num(k, w, 1, 16),
                     grid: (w, k) => num(k, w, 1, 32),
                 })
-                const base = last?.clock ?? scoreClock
+                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: [] }
+                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}$`))
@@ -573,13 +789,28 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                 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.some((s) => s !== open && s.name === name)) bad(`shot ${name} is already a shot of this file`)
+                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>)`)
@@ -653,21 +884,81 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                         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, section, shot)`)
+                        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`)
-                    s.film = filmLine(rest, n, verbs)
+                    {
+                        // 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])
@@ -699,6 +990,25 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     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 })
@@ -728,6 +1038,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                 }
                 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': {
@@ -777,7 +1088,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     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)`)
+                    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
@@ -790,14 +1101,39 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
     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))
     }
-    errors.push(...structure(t))
+    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) }
 }
 
@@ -862,10 +1198,12 @@ function structure(t: Trailer): TrailerError[] {
         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) {
-            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` })
+            // 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` })
@@ -885,6 +1223,38 @@ function structure(t: Trailer): TrailerError[] {
     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[] = []
@@ -905,9 +1275,14 @@ export function total(t: Pick<Trailer, 'shots'>): number {
 
 /** 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 }[] {
+export function musicCues(t: Pick<Trailer, 'music' | 'shots' | 'score' | 'timelineAt'>): { 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 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)) }))