rvlib-shipkit 2.3.0 → 2.4.0

package/src/trailer/grammar.ts

@@ -1,3 +1,4 @@
+import { MOVES, type Move, type MoveKind } from './motion.ts'
 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
@@ -7,26 +8,57 @@ import { type LineWord, type Moment, slotText, type Typed, typedFilm, type Words
 export type TitleStyle = 'logo' | 'big' | 'caption' | 'corner' | 'line' | 'short' | 'progress'
 /** the styles a title line names; `progress` is its own line's */
 export const TITLE_STYLES: readonly TitleStyle[] = ['logo', 'big', 'caption', 'corner', 'line', 'short']
-export const CUT_KINDS = [
-    'hard',
-    'fade',
-    'dip-black',
-    'dip-white',
-    'slide-left',
-    'slide-right',
-    'slide-up',
-    'slide-down',
-    'whip-left',
-    'whip-right',
-    'wipe-left',
-    'wipe-right',
-    'wipe-up',
-    'wipe-down',
-    'circle',
-    'pixel',
-] as const
-export type CutKind = (typeof CUT_KINDS)[number]
-export const CORE_FILMS = ['clip', 'image', 'card', 'run', 'url', 'grid', 'split'] as const
+/** the ways a cut moves, as its words spell them: `slide-left` moves the picture left */
+const DIRS = ['left', 'right', 'up', 'down'] as const
+/** every cut, its word and what draws it: an ffmpeg xfade transition by name, or `drawn` by the core (graph.ts) */
+export const CUTS = {
+    hard: null,
+    fade: 'fade',
+    'fade-fast': 'fadefast',
+    'fade-slow': 'fadeslow',
+    dissolve: 'dissolve',
+    grays: 'fadegrays',
+    blur: 'hblur',
+    'dip-black': 'fadeblack',
+    'dip-white': 'fadewhite',
+    ...Object.fromEntries(DIRS.flatMap((d) => [
+        [`slide-${d}`, `slide${d}`],
+        [`cover-${d}`, `cover${d}`],
+        [`reveal-${d}`, `reveal${d}`],
+        [`wipe-${d}`, `wipe${d}`],
+        [`smooth-${d}`, `smooth${d}`],
+        [`slice-${d}`, { left: 'hlslice', right: 'hrslice', up: 'vuslice', down: 'vdslice' }[d]],
+        [`wind-${d}`, { left: 'hlwind', right: 'hrwind', up: 'vuwind', down: 'vdwind' }[d]],
+        [`whip-${d}`, 'drawn'],
+    ])),
+    'squeeze-h': 'squeezeh',
+    'squeeze-v': 'squeezev',
+    zoom: 'zoomin',
+    ...Object.fromEntries(['tl', 'tr', 'bl', 'br'].flatMap((c) => [
+        [`wipe-${c}`, `wipe${c}`],
+        [`diag-${c}`, `diag${c}`],
+    ])),
+    radial: 'radial',
+    'open-h': 'horzopen',
+    'close-h': 'horzclose',
+    'open-v': 'vertopen',
+    'close-v': 'vertclose',
+    circle: 'circleopen',
+    'circle-close': 'circleclose',
+    'circle-crop': 'circlecrop',
+    'rect-crop': 'rectcrop',
+    pixel: 'pixelize',
+    glitch: 'drawn',
+    leak: 'drawn',
+} as Readonly<Record<CutKind, string | null>>
+export const CUT_KINDS = Object.keys(CUTS) as readonly CutKind[]
+export type CutKind = 'hard' | 'fade' | 'fade-fast' | 'fade-slow' | 'dissolve' | 'grays' | 'blur' | 'dip-black' | 'dip-white'
+    | `${'slide' | 'cover' | 'reveal' | 'wipe' | 'smooth' | 'slice' | 'wind' | 'whip'}-${(typeof DIRS)[number]}`
+    | 'squeeze-h' | 'squeeze-v' | 'zoom' | `${'wipe' | 'diag'}-${'tl' | 'tr' | 'bl' | 'br'}` | 'radial'
+    | 'open-h' | 'close-h' | 'open-v' | 'close-v' | 'circle' | 'circle-close' | 'circle-crop' | 'rect-crop' | 'pixel' | 'glitch' | 'leak'
+/** a drawn cut's length when its line names none: a whip snaps, a leak burns slowly */
+export const CUT_SECONDS: Partial<Record<CutKind, number>> = { 'whip-left': 0.35, 'whip-right': 0.35, 'whip-up': 0.35, 'whip-down': 0.35, glitch: 0.3, leak: 0.8 }
+export const CORE_FILMS = ['clip', 'image', 'card', 'run', 'url', 'page', 'grid', 'split'] as const
 
 /** the most frames a second a cut runs at */
 export const FPS_MAX = 60
@@ -86,6 +118,9 @@ export type Film =
     /** 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 }
+    /** a page filmed frame by frame through the house shot service: `window[step](t)` before each frame, then its ready
+     *  mark; `query` its words (`key value`, cues made seconds of the take) as the url's query, in the order written */
+    | { kind: 'page'; line: number; route: string; query: string[]; flags?: string[]; step: string; viewport?: [number, number]; wait?: number; still?: true; at?: number }
     /** 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] }
@@ -118,12 +153,59 @@ export interface Title {
     knock?: number
     /** a `progress` line's step: the i-th of n notches filled under its name */
     step?: { i: number; n: number }
+    /** the brand style it wears (`trailer.styles`); its `style` is the built in one under it */
+    named?: string
+    /** its look over its style's own */
+    fx?: TitleFx
+    /** how it comes in and goes out, over its style's own */
+    in?: Move
+    out?: Move
+}
+
+/** where a title stands: as `place` says; a short's caption in the frame's middle, a progress bar at the top; else
+ *  the bottom */
+export type TitlePlace = 'top' | 'middle' | 'bottom'
+export const placeOf = (ti: Pick<Title, 'place' | 'style'>): TitlePlace => ti.place ?? (ti.style === 'short' ? 'middle' : ti.style === 'progress' ? 'top' : 'bottom')
+
+/** a colour as a line writes it: `#rgb`, `#rrggbb`, or one of the look's (titles.ts resolves it) */
+export const LOOK_COLOURS = ['light', 'edge', 'accent'] as const
+
+/** a title's look over its style's: its face (a font file or a Google Fonts family), weight, size in pixels of a frame
+ *  1080 tall, fill, and its outline, shadow and glow, each a size in those pixels and a colour */
+export interface TitleFx {
+    font?: string
+    weight?: number
+    size?: number
+    color?: string
+    gradient?: string[]
+    outline?: { px: number; color?: string }
+    shadow?: { px: number; color?: string }
+    glow?: { px: number; color?: string }
+}
+
+/** how a made sound is made (design call 9): its seed, the voice or engine it is made `by`, its length (`for`), an sfx
+ *  trimmed to its first `hit` */
+export interface SoundGen {
+    seed?: number
+    by?: string
+    for?: number
+    hit?: true
+}
+
+/** a sound a command writes at `{out}` (marks `{out}`, `{seconds}`), and the files it reads, keyed by their content */
+export interface SoundRun {
+    cmd: string
+    reads?: string[]
 }
 
 export interface Sfx {
     line: number
-    /** a file, or an id the repo's sound resolver knows */
+    /** a file, an id the repo's sound resolver knows, or a prompt (`prompt`); `run` for a run's sound */
     id: string
+    /** the id is a quoted prompt the house makes from */
+    prompt?: true
+    gen?: SoundGen
+    run?: SoundRun
     at: number
     volume: number
 }
@@ -133,6 +215,8 @@ export interface Voice {
     /** a line the repo's voice resolver finds by its text, or a recorded file */
     text?: string
     file?: string
+    gen?: SoundGen
+    run?: SoundRun
     at: number
     volume: number
 }
@@ -165,8 +249,13 @@ export interface SectionRef {
 
 export interface Music {
     line: number
-    /** a file, `none`, or an id the repo's sound resolver knows */
+    /** a file, `none`, an id the repo's sound resolver knows, or a prompt (`prompt`); `run` for a run's music */
     song: string
+    prompt?: true
+    gen?: SoundGen
+    run?: SoundRun
+    /** it plays only in this music variant (`sk trailer --variant <name>`) */
+    variant?: string
     take?: string
     from: number
     fadeIn: number
@@ -295,6 +384,9 @@ export interface Trailer {
     vertical: Vertical | null
     /** the global process whose url a `film url` route resolves against (`base <id>`); null: the repo's one */
     base: string | null
+    /** the music variants the file names, and the one it was read as (null: it names none) */
+    variants: string[]
+    variant: string | null
 }
 
 export interface TrailerError {
@@ -311,6 +403,9 @@ interface Word {
 
 /** 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 */
+/** a hex colour at `k` (`#rgb`, `#rrggbb`, then the word's end or a comma): a word, never a comment */
+const colourAt = (line: string, k: number): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6})(?=[\s,"]|$)/i.test(line.slice(k))
+
 export function tokens(line: string): { words: Word[] } | { error: string } {
     const words: Word[] = []
     let i = 0
@@ -320,7 +415,7 @@ export function tokens(line: string): { words: Word[] } | { error: string } {
             i++
             continue
         }
-        if (c === '#') break
+        if (c === '#' && !colourAt(line, i)) break
         if (c === "'") {
             const end = line.indexOf("'", i + 1)
             const word = end < 0 ? line.slice(i).split(/[\s#]/)[0]! : line.slice(i, end + 1)
@@ -334,7 +429,7 @@ export function tokens(line: string): { words: Word[] } | { error: string } {
             continue
         }
         let j = i
-        while (j < line.length && line[j] !== ' ' && line[j] !== '\t' && line[j] !== '"' && line[j] !== '#') j++
+        while (j < line.length && line[j] !== ' ' && line[j] !== '\t' && line[j] !== '"' && (line[j] !== '#' || (j === i || line[j - 1] === ',') && colourAt(line, j))) j++
         words.push({ text: line.slice(i, j), quoted: false })
         i = j
     }
@@ -416,6 +511,131 @@ const sizeWord = (what: string, w: Word | undefined, lo: number, hi: number): [n
     return [x, y]
 }
 
+/** a colour word: `#rgb`, `#rrggbb`, or the look's light, edge or accent */
+const colour = (k: string, text: string | undefined): string => {
+    if (!text || !/^(#[0-9a-f]{3}|#[0-9a-f]{6}|light|edge|accent)$/i.test(text)) return bad(`${k} wants a colour: #rgb, #rrggbb, ${LOOK_COLOURS.join(', ')}${text ? `, got ${text}` : ''}`)
+    return text
+}
+/** `<px>[,<colour>]`: an outline, a shadow or a glow, its size in pixels of a frame 1080 tall */
+const sized = (w: Word | undefined, k: string): { px: number; color?: string } => {
+    if (!w || w.quoted) return bad(`${k} wants <px>[,<colour>] (10, or 10,#2a1020)`)
+    const [a, c, more] = w.text.split(',')
+    const px = Number(a)
+    if (!Number.isFinite(px) || px < 0 || px > 300 || more !== undefined) return bad(`${k} wants <px>[,<colour>], its size 0 to 300, got ${w.text}`)
+    return { px, ...(c !== undefined ? { color: colour(k, c) } : {}) }
+}
+/** a title's look words, in TitleFx */
+const FX_WORDS = ['font', 'weight', 'size', 'color', 'gradient', 'outline', 'shadow', 'glow'] as const
+const TITLE_WORDS: Record<string, (w: Word | undefined, k: string) => unknown> = {
+    style: (w, k) => word(k, w, /^[a-z][a-z0-9-]*$/),
+    at: when,
+    for: (w, k) => time(k, w),
+    place: (w, k) => {
+        const pl = word(k, w)
+        return pl === 'top' || pl === 'bottom' ? pl : bad(`${k} wants top|bottom, got ${pl}`)
+    },
+    knock: (w, k) => time(k, w),
+    font: (w, k) => pathWord(k, w),
+    weight: (w, k) => {
+        const v = num(k, w, 100, 1000)
+        return Number.isInteger(v) ? v : bad(`${k} wants a whole number from 100 to 1000, got ${w?.text}`)
+    },
+    size: (w, k) => num(k, w, 6, 600),
+    color: (w, k) => colour(k, w && !w.quoted ? w.text : undefined),
+    gradient: (w, k) => {
+        const cs = w && !w.quoted ? w.text.split(',') : []
+        if (cs.length < 2 || cs.length > 4) bad(`${k} wants two to four colours, top to bottom: light,accent`)
+        return cs.map((c) => colour(k, c))
+    },
+    outline: sized,
+    shadow: sized,
+    glow: sized,
+}
+
+/** a title's words, in order, each `+<preset>` in place; `in` and `out` take a move and, when the next word is a
+ *  time, its length. A word the line itself writes twice is an error; a preset's word gives way to a later one */
+function readTitleWords(raw: Word[], presets: ReadonlyMap<string, Word[]>, what = 'title'): Record<string, unknown> {
+    type Own = Word & { own?: true }
+    const words: Own[] = raw.flatMap((w): Own[] => {
+        if (w.quoted || !/^\+[a-z][a-z0-9-]*$/.test(w.text)) return [{ ...w, own: true }]
+        return presets.get(w.text.slice(1)) ?? bad(`${what}: no preset ${w.text.slice(1)} (preset <name> <words> in the header${presets.size ? `: ${[...presets.keys()].join(', ')}` : ''})`)
+    })
+    const values: Record<string, unknown> = {}
+    const written = new Set<string>()
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i]!
+        if (w.quoted) bad(`${what}: a quoted text "${w.text}" where a word was expected`)
+        if (w.own) {
+            if (written.has(w.text)) bad(`${what}: ${w.text} given twice`)
+            written.add(w.text)
+        }
+        if (w.text === 'in' || w.text === 'out') {
+            const kind = word(`${what} ${w.text}`, words[i + 1])
+            if (!(MOVES as readonly string[]).includes(kind)) bad(`${what} ${w.text} wants ${MOVES.join('|')}, got ${kind}`)
+            i++
+            const next = words[i + 1]
+            const seconds = next && !next.quoted && /^\d/.test(next.text) ? time(`${what} ${w.text} ${kind}`, next) : undefined
+            if (seconds !== undefined) i++
+            values[w.text] = { kind: kind as MoveKind, ...(seconds !== undefined ? { seconds } : {}) }
+            continue
+        }
+        const f = TITLE_WORDS[w.text]
+        if (!f) bad(`${what}: unknown word ${w.text} (title takes ${[...Object.keys(TITLE_WORDS), 'in', 'out', '+<preset>'].join(', ')})`)
+        values[w.text] = f!(words[++i], `${what} ${w.text}`)
+    }
+    return values
+}
+
+/** a title's look words out of read values */
+const fxOf = (v: Record<string, unknown>): TitleFx => Object.fromEntries(FX_WORDS.filter((k) => v[k] !== undefined).map((k) => [k, v[k]])) as TitleFx
+const builtInStyle = (st: string): st is TitleStyle => (TITLE_STYLES as readonly string[]).includes(st)
+
+/** the brand's text styles (`trailer.styles`, each a title's words by name) laid under each title: the defaults of
+ *  its built in style, then the brand style it names, then its own words, a later one winning. A brand style names
+ *  the built in style under it (default caption) and holds look words, `place`, `in` and `out` only. Run again, it
+ *  gives the same titles. Every error at the title's line */
+export function resolveStyles(t: Pick<Trailer, 'shots'>, styles: Readonly<Record<string, string>>): TrailerError[] {
+    const errors: TrailerError[] = []
+    const read = (name: string): Record<string, unknown> => {
+        const tk = tokens(styles[name]!)
+        if ('error' in tk) return bad(`the brand's style ${name}: ${tk.error}`)
+        const v = readTitleWords(tk.words, new Map(), `the brand's style ${name}`)
+        const odd = Object.keys(v).filter((k) => !['style', 'place', 'in', 'out', ...FX_WORDS].includes(k))
+        if (odd.length > 0) bad(`the brand's style ${name} holds look words, place, in and out, never ${odd.join(', ')}`)
+        return v
+    }
+    for (const s of t.shots)
+        for (const ti of s.titles) {
+            if (ti.style === 'progress') continue
+            try {
+                let base: string = ti.style
+                let named: Record<string, unknown> = {}
+                if (ti.named) {
+                    if (styles[ti.named] === undefined) bad(`title style wants ${[...TITLE_STYLES, ...Object.keys(styles).filter((k) => !builtInStyle(k))].join('|')}, got ${ti.named}`)
+                    named = read(ti.named)
+                    base = (named.style as string | undefined) ?? 'caption'
+                    if (!builtInStyle(base)) bad(`the brand's style ${ti.named} is over ${base}, which is no built in style (${TITLE_STYLES.join('|')})`)
+                }
+                const defaults = styles[base] !== undefined ? read(base) : {}
+                if (defaults.style !== undefined) bad(`the brand's style ${base} gives the defaults of the built in ${base}: it names no style of its own`)
+                const under = { ...defaults, ...named }
+                ti.style = base as TitleStyle
+                const fx = { ...fxOf(under), ...ti.fx }
+                if (Object.keys(fx).length > 0) ti.fx = fx
+                if (under.place && !ti.place) ti.place = under.place as 'top' | 'bottom'
+                if (under.in && !ti.in) ti.in = under.in as Move
+                if (under.out && !ti.out && ti.knock === undefined) ti.out = under.out as Move
+            } catch (e) {
+                if (!(e instanceof LineError)) throw e
+                errors.push({ line: ti.line, message: e.message })
+            }
+        }
+    return errors
+}
+
+/** the brand styles a cut names: a title's style word that is no built in style */
+export const namedStyles = (t: Pick<Trailer, 'shots'>): string[] => [...new Set(t.shots.flatMap((s) => s.titles.flatMap((ti) => (ti.named ? [ti.named] : []))))]
+
 /** the `key value` pairs after a line's fixed words; `flags` take no value */
 function pairs(
     what: string,
@@ -459,7 +679,9 @@ interface FilmContext {
     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
+    later: (f: { argv: string[] }, slot: Typed['times'][number]) => void
+    /** the words a `film page` takes, when the repo declares them (its trailer unit's `page`) */
+    pageWords?: Words
     errors: TrailerError[]
 }
 
@@ -472,9 +694,58 @@ function expandPresets(ws: Word[], line: number, presets: ReadonlyMap<string, Wo
     })
 }
 
+/** `film page <route> [viewport WxH] [wait t] [step <hook>] [still] <words>`: the words a query, typed when the repo
+ *  declares them, else `key value` (a value of cues, `name@<time>` words, made seconds of the take) */
+function pageFilm(ws: Word[], line: number, c: FilmContext): Extract<Film, { kind: 'page' }> {
+    const route = pathWord('film page', ws[1])
+    if (!/^(\/|https?:\/\/)/.test(route)) bad(`film page wants a route of the dev url (/look) or an http url, got ${route}`)
+    const own: Record<string, unknown> = {}
+    const rest: Word[] = []
+    const RESERVED: Record<string, (w: Word | undefined, k: string) => unknown> = { viewport: (w, k) => sizeWord(k, w, 16, 7680), wait: at, step: (w, k) => word(k, w, /^[A-Za-z_$][A-Za-z0-9_$]*$/) }
+    for (let i = 2; i < ws.length; i++) {
+        const w = ws[i]!
+        if (!w.quoted && w.text === 'still') own.still = true
+        else if (!w.quoted && RESERVED[w.text]) {
+            if (w.text in own) bad(`film page: ${w.text} given twice`)
+            own[w.text] = RESERVED[w.text]!(ws[++i], `film page ${w.text}`)
+        } else rest.push(w)
+    }
+    // a page's words are its query, key=value: a positional has no key to write
+    for (const [k, w] of Object.entries(c.pageWords ?? {})) if (w.arg !== undefined) bad(`film page: ${k} declares arg ${w.arg}, and a page word has a key (it is the url's query): drop its arg`)
+    // undeclared words: a key, then one value, or cue words while they come
+    const words: Words = c.pageWords ?? {}
+    if (!c.pageWords)
+        for (let i = 0; i < rest.length; i++) {
+            const k = rest[i]!
+            if (k.quoted || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(k.text)) bad(`film page: ${k.quoted ? `"${k.text}"` : k.text} is no word of the query: write key value`)
+            const cue = (w: Word | undefined): boolean => !!w && !w.quoted && /^[^@\s]+@\S+$/.test(w.text)
+            words[k.text] = { type: cue(rest[i + 1]) ? 'cues' : 'text' }
+            if (cue(rest[i + 1])) while (cue(rest[i + 1])) i++
+            else if (!rest[++i]) bad(`film page ${k.text} wants a value`)
+        }
+    const at2 = (w: Word): LineWord => ({ text: w.text, quoted: w.quoted, line: w.line ?? line })
+    const typed = typedFilm(['page'], words, rest.map(at2), c.pageWords ? c.defaults.map(at2) : [], c.time)
+    c.errors.push(...typed.errors)
+    const f: Extract<Film, { kind: 'page' }> = {
+        kind: 'page',
+        line,
+        route,
+        query: typed.argv.slice(1),
+        ...(Object.entries(words).some(([, s]) => s.type === 'flag') ? { flags: Object.entries(words).filter(([, s]) => s.type === 'flag').map(([k]) => k) } : {}),
+        step: (own.step as string | undefined) ?? '__trailerStep',
+        ...(own.viewport ? { viewport: own.viewport as [number, number] } : {}),
+        ...(own.wait !== undefined ? { wait: own.wait as number } : {}),
+        ...(own.still ? { still: true as const } : {}),
+    }
+    // the query's slots sit one word to the left of the typed argv's (its `page` path word dropped)
+    for (const slot of typed.times) c.later({ argv: f.query }, { ...slot, index: slot.index - 1 })
+    return f
+}
+
 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 : ''
+    if (kind === 'page' && c) return pageFilm(ws, line, c)
     const argv = ws.map((w) => w.text)
     const v = verbs && verbOf(argv, verbs)
     if ((CORE_FILMS as readonly string[]).includes(kind)) {
@@ -574,18 +845,55 @@ export const NO_MUSIC = 'none'
 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), {
+/** `<kind> run "<cmd {out}>" [reads <file>,…]`: the run form of a sound line, and the words after it; null when the
+ *  line is no run */
+function soundRun(kind: string, rest: Word[]): { run: SoundRun; rest: Word[] } | null {
+    if (!(rest[0] && !rest[0].quoted && rest[0].text === 'run' && rest[1]?.quoted)) return null
+    const cmd = quoted(`${kind} run`, rest[1])
+    if (!cmd.includes('{out}')) bad(`${kind} run wants {out} in its command: the file the command writes the sound to`)
+    let more = rest.slice(2)
+    let reads: string[] | undefined
+    if (more[0]?.text === 'reads' && !more[0].quoted) {
+        reads = pathWord(`${kind} run reads`, more[1]).split(',')
+        more = more.slice(2)
+    }
+    return { run: { cmd, ...(reads ? { reads } : {}) }, rest: more }
+}
+
+/** the words a made sound takes, read off a line's pairs */
+const genOf = (p: Record<string, unknown>): { gen?: SoundGen } => {
+    const g: SoundGen = { ...(p.seed !== undefined ? { seed: p.seed as number } : {}), ...(p.by ? { by: p.by as string } : {}), ...(p.for !== undefined ? { for: p.for as number } : {}), ...(p.hit ? { hit: true as const } : {}) }
+    return Object.keys(g).length ? { gen: g } : {}
+}
+const seedWord = (w: Word | undefined, k: string): number => {
+    const v = num(k, w, 0, 2 ** 31 - 1)
+    return Number.isInteger(v) ? v : bad(`${k} wants a whole number, got ${w?.text}`)
+}
+const byWord = (w: Word | undefined, k: string): string => word(k, w, /^[a-zA-Z0-9][a-zA-Z0-9:_./-]*$/)
+
+function musicLine(raw: Word[], n: number, opening = false): Music {
+    const r = soundRun('music', raw)
+    const rest = r ? [{ text: 'run', quoted: false }, ...r.rest] : raw
+    const prompt = !r && rest[0]?.quoted === true
+    const song = r ? 'run' : prompt ? quoted('music', rest[0]) : pathWord('music', rest[0])
+    const p = pairs(`music ${r ? 'run' : 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,
+        by: byWord,
+        for: at,
+        seed: seedWord,
+        variant: (w, k) => word(k, w, /^[a-z0-9][a-z0-9-]*$/),
     })
     return {
         line: n,
         song,
+        ...(prompt ? { prompt: true as const } : {}),
+        ...(r ? { run: r.run } : {}),
+        ...genOf(p),
+        ...(p.variant ? { variant: p.variant as string } : {}),
         ...(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),
@@ -657,6 +965,20 @@ export function scoreLines(text: string): { lines: string[]; code: Score['code']
 export interface ParseOptions {
     /** the project CLI's film rows; null when the repo has no project CLI */
     verbs?: readonly FilmVerb[] | null
+    /** the words a `film page` takes, when the repo's trailer unit declares them */
+    pageWords?: Words
+    /** the music variant the cut is read as; default the first the file names */
+    variant?: string
+}
+
+/** the music variants a file names, in order: its music lines' `variant <name>` words */
+export function variantsOf(text: string): string[] {
+    const out: string[] = []
+    for (const l of text.split('\n')) {
+        const m = /^\s*music\s.*\svariant\s+([a-z0-9][a-z0-9-]*)\b/.exec(l.replace(/"[^"]*"/g, '""'))
+        if (m && !out.includes(m[1]!)) out.push(m[1]!)
+    }
+    return out
 }
 
 /** the file as a trailer, and every error with its line */
@@ -685,8 +1007,20 @@ export function filmOptionLines(lines: string[]): Map<number, { line: number; te
 
 export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Trailer; errors: TrailerError[] } {
     const verbs = o.verbs ?? null
-    const t: Trailer = { name: '', footage: [], size: [1920, 1080], fps: 30, music: null, duck: -10, duckSfx: null, fadeIn: 0, shots: [], sections: [], score: null, timelineAt: null, vertical: null, base: null }
+    const variants = variantsOf(text)
+    const variant = o.variant ?? variants[0] ?? 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, variants, variant }
+    /** a music line of another variant plays elsewhere; one of this variant takes the place of the line with none */
+    const mine = (m: Music, had: Music | null, what: string): boolean => {
+        if (m.variant !== undefined && m.variant !== variant) return false
+        // the variant's line came first: the plain one under it stands aside, whatever their order
+        if (had && had.variant !== undefined && m.variant === undefined) return false
+        if (had && (had.variant !== undefined || m.variant === undefined)) bad(`${what} already ${had.variant ? `plays variant ${had.variant}` : 'plays its music'} on line ${had.line}`)
+        return true
+    }
     const errors: TrailerError[] = []
+    /** a section's defaults that some film of it cannot read, by the defaults line */
+    const unread: { line: number; section: string; films: string[] }[] = []
     const seen = new Set<string>()
     let shot: Shot | null = null
     let pending: SectionRef | null = null
@@ -705,7 +1039,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
     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] }[] = []
+    const slots: { shot: Shot; film: { argv: string[] }; 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)
@@ -756,7 +1090,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                 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
+                    const m = !w.quoted ? /^([A-Za-z])=([a-zA-Z][a-zA-Z0-9]*(?::[a-z0-9-]+)?)$/.exec(w.text) : null
                     if (!m) bad(`drums wants <letter>=<instrument>, got ${w.text}`)
                     into[m![1]!] = m![2]!
                 }
@@ -843,11 +1177,12 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                         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')
+                    case 'music': {
+                        const m = musicLine(rest, n, true)
+                        if (m.song === NO_MUSIC) bad('music none is a shot\'s cue, the header names the song the cut opens on')
+                        if (mine(m, t.music, 'the header')) t.music = m
                         break
+                    }
                     case 'duck': {
                         once('duck')
                         const drop = (w: Word | undefined, what: string): number => {
@@ -926,7 +1261,7 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     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]*$/)
+                        const instrument = word(`track ${name}`, rest[1], /^[a-zA-Z][a-zA-Z0-9]*(:[a-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 })
@@ -951,39 +1286,45 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                             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, {
+                        const f = (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 }),
+                            ...(o.pageWords ? { pageWords: o.pageWords } : {}),
                             errors,
-                        })
+                        }))
+                        // a film that reads no declared words drops the section's defaults: said once, at the defaults line
+                        const takes = f.kind === 'cli' ? f.typed === true : f.kind === 'page' && o.pageWords !== undefined
+                        if (!s.offcut && current?.defaults && !takes) {
+                            const at = current.defaults[0]!.line ?? n
+                            const what = f.kind === 'cli' ? `film ${f.argv[0]} declares no words` : f.kind === 'page' ? 'film page declares no words (the trailer unit\'s page)' : `film ${f.kind} is a core film`
+                            if (!unread.some((u) => u.line === at)) unread.push({ line: at, section: current.name, films: [] })
+                            const u = unread.find((x) => x.line === at)!
+                            if (!u.films.includes(what)) u.films.push(what)
+                        }
                     }
                     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 p = readTitleWords(rest.slice(1), presets)
+                    const st = p.style === undefined ? 'caption' : word('title style', { text: p.style as string, quoted: false }, /^[a-z][a-z0-9-]*$/)
                     const ti: Title = {
                         line: n,
                         text,
                         at: 0,
                         for: (p.for as number) ?? null,
-                        style: (p.style as TitleStyle) ?? 'caption',
+                        // a brand style is laid in by resolveStyles, once the brand is read
+                        style: builtInStyle(st) ? st : 'caption',
+                        ...(builtInStyle(st) ? {} : { named: st }),
                         ...(p.place ? { place: p.place as 'top' | 'bottom' } : {}),
                         ...(p.knock !== undefined ? { knock: p.knock as number } : {}),
+                        ...(p.in ? { in: p.in as Move } : {}),
+                        ...(p.out ? { out: p.out as Move } : {}),
                     }
+                    const fx = fxOf(p)
+                    if (Object.keys(fx).length > 0) ti.fx = fx
+                    if (ti.knock !== undefined && ti.out) bad('title: knock is its exit, give out or knock, not both')
                     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`)
@@ -1010,18 +1351,22 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     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 }
+                    const r = soundRun('sfx', rest)
+                    const words = r ? r.rest : rest.slice(1)
+                    const prompt = !r && rest[0]?.quoted === true
+                    const id = r ? 'run' : prompt ? quoted('sfx', rest[0]) : pathWord('sfx', rest[0])
+                    const p = pairs(`sfx ${r ? 'run' : id}`, words, { at: when, volume, for: at, seed: seedWord }, ['hit'])
+                    const x: Sfx = { line: n, id, ...(prompt ? { prompt: true as const } : {}), ...(r ? { run: r.run } : {}), ...genOf(p), 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 }
+                    const r = soundRun('voice', rest)
+                    const fileForm = !r && rest[0] && !rest[0].quoted && rest[0].text === 'file'
+                    const src = r ? { run: r.run } : fileForm ? { file: pathWord('voice file', rest[1]) } : { text: quoted('voice', rest[0]) }
+                    const p = pairs('voice', r ? r.rest : rest.slice(fileForm ? 2 : 1), { at: when, volume, ...(fileForm || r ? {} : { by: byWord, seed: seedWord }) })
+                    const v: Voice = { line: n, ...src, ...genOf(p), at: 0, volume: (p.volume as number) ?? 1 }
                     v.at = landAt(p.at, n, s, (x) => (v.at = x))
                     s.voices.push(v)
                     break
@@ -1030,17 +1375,18 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
                     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
+                    const seconds = k === 'hard' ? 0 : rest[1] ? time(`cut ${k}`, rest[1]) : (CUT_SECONDS[k as CutKind] ?? 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}`)
+                case 'music': {
                     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)
+                    const m = musicLine(rest, n)
+                    if (mine(m, s.music, `shot ${s.name}`)) s.music = m
                     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>]')
@@ -1097,6 +1443,9 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
         }
     }
     if (!seen.has('trailer')) errors.push({ line: 1, message: 'the file names its trailer first: trailer <name>' })
+    if (o.variant !== undefined && !variants.includes(o.variant)) errors.push({ line: 1, message: `--variant ${o.variant}: this cut names ${variants.length ? `the variants ${variants.join(', ')}` : 'no music variant (music … variant <name>)'}` })
+    // a variant other than the first renders beside it: out/<name>-<variant>.mp4
+    if (variant !== null && variant !== variants[0]) t.name = `${t.name}-${variant}`
     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')}` })
@@ -1121,6 +1470,8 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
         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))
     }
+    // a page still is the page stepped to its shot's from: the moment is part of its take
+    for (const s of t.shots) if (s.film?.kind === 'page' && s.film.still) s.film.at = s.from
     for (const p of slots) {
         const i = t.shots.indexOf(p.shot)
         const parts = p.slot.parts.map((x) => {
@@ -1131,10 +1482,21 @@ export function parseTrailer(text: string, o: ParseOptions = {}): { trailer: Tra
             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 }
         })
+        // a moment of the take lies in its footage: from 0 to where the shot stops showing it
+        const end = p.shot.from + p.shot.length
+        p.slot.parts.forEach((x, k) => {
+            const sec = parts[k]!.seconds
+            if (sec < -1e-4 || sec > end + 1e-4)
+                errors.push({ line: x.line, message: `film: ${x.name ? `${x.name}@` : ''}${+sec.toFixed(4)}s of the footage is outside the take (0 to ${+end.toFixed(4)}s, its from plus its length)` })
+        })
         p.film.argv[p.slot.index] = slotText(parts)
     }
+    for (const u of unread) errors.push({ line: u.line, message: `defaults of section ${u.section}: ${u.films.join(', ')}, so it drops them; give its words on its film line` })
     errors.push(...structure(t), ...grids(t))
-    return { trailer: t, errors: errors.sort((a, b) => a.line - b.line) }
+    // a section's defaults read by each of its film lines say a wrong word once, at its line
+    const said = new Set<string>()
+    const once = errors.filter((e) => !said.has(`${e.line} ${e.message}`) && said.add(`${e.line} ${e.message}`))
+    return { trailer: t, errors: once.sort((a, b) => a.line - b.line) }
 }
 
 /** the least a fitted shot keeps past its cut out */
@@ -1189,7 +1551,7 @@ function landShots(t: Trailer): TrailerError[] {
 
 /** 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')
+    f?.kind === 'card' || f?.kind === 'image' || ((f?.kind === 'run' || f?.kind === 'url' || f?.kind === 'page') && 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[] {
@@ -1197,7 +1559,7 @@ function structure(t: Trailer): TrailerError[] {
     t.shots.forEach((s, i) => {
         if (s.broken) return
         if (!s.film) out.push({ line: s.line, message: `shot ${s.name} films nothing: give it a film line` })
-        if (isStill(s.film) && s.from > 0) out.push({ line: s.line, message: `shot ${s.name}: its film is a still image, no footage to skip (from)` })
+        if (isStill(s.film) && s.film?.kind !== 'page' && 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)
@@ -1229,7 +1591,7 @@ export function gridCells(t: Pick<Trailer, 'shots' | 'footage'>, cells: readonly
 }
 
 /** 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)
+export const isCellFilm = (f: Film | null): boolean => (f?.kind === 'run' || f?.kind === 'url' || f?.kind === 'page' || f?.kind === 'cli') && !isStill(f)
 
 /** what a grid or a split names, and what a footage block films */
 function grids(t: Trailer): TrailerError[] {