rvlib-shipkit 2.3.0 → 2.4.0

package/src/shot/stepped-clip.ts

@@ -0,0 +1,53 @@
+// a clip filmed frame by frame (wiki build/trailer.md, film page): before each frame the page is asked to draw the
+// frame's time, `window[step](t)`, then the shot service waits for its ready mark and two painted frames, takes one
+// screenshot, and ffmpeg encodes the frames in order. The page's own speed never shows: a frame that takes a second to
+// draw sits beside one that took a millisecond. The page owns its clock while it is stepped
+import { mkdirSync } from 'fs'
+import { dirname } from 'path'
+import { domEncodeArgs } from './dom-clip.ts'
+import { type ClipAsk, readMark, waitReady } from './shot-ask.ts'
+
+type Cdp = { send(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> }
+type Page = { evaluate<R, A>(fn: (a: A) => R | Promise<R>, arg: A): Promise<R>; waitForTimeout(ms: number): Promise<void> }
+
+/** the frames a stepped clip holds, and each one's time */
+export const stepTimes = (seconds: number, fps: number): number[] => Array.from({ length: Math.max(1, Math.round(seconds * fps)) }, (_, i) => +(i / fps).toFixed(6))
+
+/** IN THE PAGE: the hook asked to draw time t; false when the page has no such hook */
+export const stepTo = async ([hook, t]: [string, number]): Promise<boolean> => {
+    const f = (window as unknown as Record<string, unknown>)[hook]
+    if (typeof f !== 'function') return false
+    await (f as (t: number) => unknown)(t)
+    await new Promise<void>((ok) => requestAnimationFrame(() => requestAnimationFrame(() => ok())))
+    return true
+}
+
+export async function stepPage(cdp: Cdp, page: Page, a: ClipAsk & { step: string }): Promise<string> {
+    const ffmpeg = Bun.which('ffmpeg') ?? (process.platform === 'darwin' ? '/opt/homebrew/bin/ffmpeg' : null)
+    if (ffmpeg == null) throw new Error('ffmpeg is not installed: brew install ffmpeg')
+    mkdirSync(dirname(a.out), { recursive: true })
+    const times = stepTimes(a.seconds, a.fps)
+    const p = Bun.spawn([ffmpeg, ...domEncodeArgs(a.fps, times.length, a.out)], { stdin: 'pipe', stdout: 'ignore', stderr: 'pipe' })
+    const stderr = new Response(p.stderr).text()
+    const t0 = performance.now()
+    let px = ''
+    try {
+        for (const t of times) {
+            if (!(await page.evaluate(stepTo, [a.step, t] as [string, number]))) throw new Error(`the page has no window.${a.step}(t): a stepped page draws the time it is given there`)
+            await waitReady(() => page.evaluate(readMark, undefined), 0, { now: () => performance.now(), sleep: (n) => page.waitForTimeout(n) })
+            const shot = await cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 92 })
+            const jpeg = Buffer.from(String(shot['data']), 'base64')
+            // the frame's pixels, from the jpeg's start of frame
+            const sof = jpeg.indexOf(Buffer.from([0xff, 0xc0]))
+            if (px === '' && sof >= 0) px = `${jpeg.readUInt16BE(sof + 7)}x${jpeg.readUInt16BE(sof + 5)}`
+            p.stdin.write(jpeg)
+            await p.stdin.flush()
+        }
+    } finally {
+        await Promise.resolve(p.stdin.end()).catch(() => undefined)
+    }
+    const err = await stderr
+    if ((await p.exited) !== 0) throw new Error(`ffmpeg encode → ${a.out}: ${err.trim().split('\n').slice(-6).join('\n') || `exit ${p.exitCode}`}`)
+    const s = (performance.now() - t0) / 1000
+    return `${times.length} frames ${px} at ${a.fps} fps, each stepped through window.${a.step}(t) and its ready mark (${(s / times.length * 1000).toFixed(0)} ms a frame), H.264 by ffmpeg`
+}

package/src/trailer/adapter.ts

@@ -3,15 +3,38 @@
 // resolves the sounds that are not files, names the paths a take's world is, checks the content the language cannot
 // know, refines one film line's take, and turns on the guards that read the repo's own words. Discovered like every
 // unit file (load-unit.ts)
-import type { TakeLength } from './grammar.ts'
+import type { SoundRun, TakeLength } from './grammar.ts'
+import { type Words, wordsProblem } from './words.ts'
 
+/** the repo's sounds by id; null: not the repo's, the house makes it (src/trailer/sound/, design call 9) */
 export interface TrailerSounds {
     /** a music id to an audio file of at least `seconds`, cached by the repo */
-    music?(id: string, o: { take?: string; seconds: number }): Promise<string>
+    music?(id: string, o: { take?: string; seconds: number }): Promise<string | null>
     /** an sfx id to an audio file */
-    sfx?(id: string): Promise<string>
+    sfx?(id: string): Promise<string | null>
     /** a voice line, found by its text, to an audio file */
-    voice?(text: string): Promise<string>
+    voice?(text: string): Promise<string | null>
+}
+
+/** a sound line the house makes (`resolveSound` and `soundStates` of src/trailer/sound/index.ts, the shape it reads):
+ *  the line read, the prompt, or a `.mid` file's path (`text`), how it is made (`seed`, `by`, `for`, `hit`), what a music
+ *  cue covers (`seconds`), or the line's own `run` command */
+export interface SoundRequest {
+    kind: 'music' | 'sfx' | 'voice'
+    text: string
+    seed?: number
+    by?: string
+    for?: number
+    hit?: boolean
+    seconds?: number
+    line: number
+    run?: SoundRun
+    /** the cut's folder: a `reads` file is found beside it first, then from the repo root */
+    dir: string
+    /** the text is a quoted prompt, never an id */
+    prompt?: boolean
+    /** music: the take of a song id */
+    take?: string
 }
 
 /** a film line of the project CLI as the unit sees it: its words as written, the text of each `@<file>` word */
@@ -66,6 +89,8 @@ export interface TrailerDef {
     states?: { ignore?: string[]; underWay?: string[] }
     /** a clip take that drops its picture for a few frames is filmed again once, then refused (holes.ts) */
     holes?: boolean
+    /** the words a `film page` of this repo takes (words.ts): each checked at its line, its query made plain */
+    page?: { words: Words }
 }
 
 export type TrailerUnit = TrailerDef & { kind: 'trailer' }
@@ -73,6 +98,10 @@ export type TrailerUnit = TrailerDef & { kind: 'trailer' }
 export function trailer(d: TrailerDef): TrailerUnit {
     for (const [k, f] of Object.entries(d.sound ?? {})) if (typeof f !== 'function') throw new Error(`trailer: sound.${k} is a function returning an audio file`)
     for (const k of ['check', 'take'] as const) if (d[k] !== undefined && typeof d[k] !== 'function') throw new Error(`trailer: ${k} is a function`)
+    if (d.page !== undefined) {
+        const why = wordsProblem(d.page.words) ?? Object.entries(d.page.words).flatMap(([k, w]) => (w.arg !== undefined ? [`page word ${k} declares arg: a page word has a key (it is the url's query)`] : []))[0] ?? null
+        if (why !== null) throw new Error(`trailer: ${why}`)
+    }
     if (d.stamp !== undefined && (!Array.isArray(d.stamp) || d.stamp.some((p) => typeof p !== 'string' || p === '' || p.startsWith('/')))) throw new Error('trailer: stamp is a list of repo relative paths')
     return { ...d, kind: 'trailer' }
 }

package/src/trailer/build.ts

@@ -2,14 +2,16 @@
 // stitch the pieces, lay the strip, write the montage page. `sk trailer` and its verbs call these
 import { constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path'
-import type { TrailerCheckInput, TrailerUnit } from './adapter.ts'
-import { type FilmVerb, type Film, gridCells, parseTrailer, SCORE, SCORE_LEAD, type Shot, starts, total, type Trailer, type TrailerError, musicCues, NO_MUSIC } from './grammar.ts'
+import type { SoundRequest, TrailerCheckInput, TrailerUnit } from './adapter.ts'
+import { type FilmVerb, type Film, gridCells, namedStyles, parseTrailer, placeOf, resolveStyles, type Title, type SoundGen, type SoundRun, SCORE, SCORE_LEAD, type Shot, starts, total, type Trailer, type TrailerError, musicCues, NO_MUSIC } from './grammar.ts'
 import { filmLineOf, type Recipe, takesOf, trailerCache } from './footage.ts'
 import type { BrandLike, TrailerLook } from './look.ts'
 import { fresh, isTake, type Refilm, recipeWords, type Take, takeIsStill, takesToFilm, type World, worldFor } from './plan.ts'
 import { decodeStates, edgeChanges } from './states.ts'
 import { type CompiledScore, compileScore } from './score/score.ts'
-import { GROW_RES, type Source } from './graph.ts'
+import { GROW_RES, type Source, titleMotions } from './graph.ts'
+import type { TitleMotion } from './motion.ts'
+import type { TitleRequest } from './titles.ts'
 import type { Stitched } from './stitch.ts'
 import { projectCli, readVocab } from './vocab.ts'
 
@@ -85,7 +87,7 @@ export function fileOf(path: string, l: Pick<Loaded, 'dir' | 'root'>): string |
 
 /** the file parsed and checked against the repo: every error at its line, all at once; the trailer unit's check with
  *  it unless `o.check` is false (a cut read only for its keys); `o.fresh` reads the rows and the unit again */
-export async function load(file: string, root: string, o: { text?: string; dir?: string; check?: boolean; fresh?: boolean } = {}): Promise<Loaded> {
+export async function load(file: string, root: string, o: { text?: string; dir?: string; check?: boolean; fresh?: boolean; variant?: string } = {}): Promise<Loaded> {
     const text = o.text ?? readFileSync(file, 'utf8')
     // a watch's build reads the rows and the unit again: a bumped version or an edited unit keys as a fresh run would
     if (o.fresh) {
@@ -95,21 +97,25 @@ export async function load(file: string, root: string, o: { text?: string; dir?:
     const cli = projectCli(root)
     let verbs: FilmVerb[] | null = null
     const errors: TrailerError[] = []
-    let parsed = parseTrailer(text, { verbs: null })
+    const { loadTrailerUnit } = await import('./load-unit.ts')
+    const unit = await loadTrailerUnit(root)
+    const variant = { ...(o.variant !== undefined ? { variant: o.variant } : {}), ...(unit?.page ? { pageWords: unit.page.words } : {}) }
+    let parsed = parseTrailer(text, { verbs: null, ...variant })
     // the project CLI is asked only when a film line does not read as a core film
     const lines = text.split('\n')
     if (cli !== null && parsed.errors.some((e) => /^\s*film\s/.test(lines[e.line - 1] ?? ''))) {
         try {
             verbs = readVocab(root, cli)
-            parsed = parseTrailer(text, { verbs })
+            parsed = parseTrailer(text, { verbs, ...variant })
         } catch (e) {
             errors.push({ line: 1, message: (e as Error).message })
         }
     }
     const t = parsed.trailer
-    const { loadTrailerUnit } = await import('./load-unit.ts')
-    const l: Loaded = { root, file, dir: o.dir ?? dirname(file), t, errors: [...errors, ...parsed.errors], warnings: [], cli, verbs, score: null, recipes: new Map(), unit: await loadTrailerUnit(root) }
+    const l: Loaded = { root, file, dir: o.dir ?? dirname(file), t, errors: [...errors, ...parsed.errors], warnings: [], cli, verbs, score: null, recipes: new Map(), unit }
     l.errors.push(...findRecipes(l))
+    // the brand is read only for a cut that names one of its text styles: a check stays quick
+    if (namedStyles(t).length > 0) l.errors.push(...resolveStyles(t, (await brandStyles(root)) ?? {}))
     if (l.errors.length === 0) l.errors.push(...checkFiles(l))
     if (l.errors.length === 0 && t.score) {
         const c = compileScore(t.score, t.sections, trailerCache(root, 'score'))
@@ -165,7 +171,7 @@ export function checkInput(l: Loaded): TrailerCheckInput {
         fps: l.t.fps,
         films: [...l.t.shots, ...l.t.footage].flatMap((s) => (s.film?.kind === 'cli' ? [filmLineOf(s, s.film, l)] : [])),
         music: [l.t.music, ...l.t.shots.map((s) => s.music)].flatMap((m) =>
-            m && m.song !== NO_MUSIC && !isFileWord(m.song) ? [{ line: m.line, id: m.song, ...(m.take ? { take: m.take } : {}), from: m.from, opening: m === l.t.music }] : [],
+            m && m.song !== NO_MUSIC && !m.prompt && !m.run && !isFileWord(m.song) ? [{ line: m.line, id: m.song, ...(m.take ? { take: m.take } : {}), from: m.from, opening: m === l.t.music }] : [],
         ),
         sfx: ids.filter((x) => x.kind === 'sfx').map((x) => ({ line: x.line, id: x.id })),
         voices: ids.filter((x) => x.kind === 'voice').map((x) => ({ line: x.line, text: x.id })),
@@ -188,6 +194,56 @@ export async function worldOf(l: Pick<Loaded, 'root' | 'unit'>): Promise<(tk: Ta
     }
 }
 
+/** the brand's text styles, null with no brand */
+async function brandStyles(root: string): Promise<Record<string, string> | null> {
+    const brand = await (await import('../assets/run-assets.ts')).loadBrand(root)
+    if (typeof brand === 'string') throw new Refused(brand)
+    return brand?.trailer?.styles ?? null
+}
+
+/** what a title's `font` word names: a font file found beside the .trailer or from the repo root, else a Google
+ *  Fonts family at its weight (400 unless it says) */
+function fontOf(l: Pick<Loaded, 'dir' | 'root'>, ti: Title): { file: string | null; family?: string; weight: number } | null {
+    const f = ti.fx?.font
+    if (f === undefined) return null
+    const weight = ti.fx?.weight ?? 400
+    return /\.(ttf|otf|woff2?)$/i.test(f) ? { file: fileOf(f, l), weight } : { file: null, family: f, weight }
+}
+
+/** the font file a title draws with, fetched from Google Fonts once when it names a family; a family Google lacks
+ *  fails at the title's line */
+async function titleFont(l: Loaded, ti: Title): Promise<string | null> {
+    const f = fontOf(l, ti)
+    if (!f) return null
+    if (f.file) return f.file
+    if (!f.family) throw new Refused(`${relative(l.root, l.file)}:${ti.line}: title font ${ti.fx?.font}: no such font file beside the .trailer or from the repo root`)
+    const { googleFont } = await import('./fonts.ts')
+    try {
+        return await googleFont(f.family, f.weight)
+    } catch (e) {
+        throw new Refused(`${relative(l.root, l.file)}:${ti.line}: ${(e as Error).message}`)
+    }
+}
+
+/** what a title draws, but its font file (titleFont, or googleFile where nothing is fetched) */
+export function titleRequest(l: Pick<Loaded, 'root' | 't'>, ti: Title, look: TrailerLook, motion: TitleMotion): TitleRequest {
+    return { root: l.root, text: ti.text, style: ti.style, size: l.t.size, place: placeOf(ti), look, motion, ...(ti.step ? { step: ti.step } : {}), ...(ti.fx ? { fx: ti.fx } : {}) }
+}
+
+/** one line per font a title names: a file found, a Google Fonts family cached or to fetch */
+export async function fontLines(l: Loaded): Promise<string[]> {
+    const seen = new Map<string, string>()
+    for (const s of l.t.shots)
+        for (const ti of s.titles) {
+            const f = fontOf(l, ti)
+            if (!f || f.file) continue
+            const { googleFile } = await import('./fonts.ts')
+            const k = `${f.family} ${f.weight}`
+            if (!seen.has(k)) seen.set(k, `font "${f.family}" ${f.weight}: ${existsSync(googleFile(f.family!, f.weight)) ? 'cached' : 'to fetch from Google Fonts'}`)
+        }
+    return [...seen.values()]
+}
+
 /** the clips, images and sound files the lines name, each found where it should be */
 function checkFiles(l: Loaded): TrailerError[] {
     const out: TrailerError[] = []
@@ -196,26 +252,104 @@ function checkFiles(l: Loaded): TrailerError[] {
     }
     for (const s of l.t.shots) {
         if (s.film?.kind === 'clip' || s.film?.kind === 'image') need(s.film.line, `film ${s.film.kind}`, s.film.path)
-        for (const x of s.sfx) if (isFileWord(x.id)) need(x.line, 'sfx', x.id)
+        for (const ti of s.titles) if (ti.fx?.font && /\.(ttf|otf|woff2?)$/i.test(ti.fx.font)) need(ti.line, 'title font', ti.fx.font)
+        for (const x of s.sfx) if (isFileSound(x.id, x)) need(x.line, 'sfx', x.id)
         for (const v of s.voices) if (v.file) need(v.line, 'voice file', v.file)
+        for (const x of [...s.sfx, ...s.voices]) for (const f of x.run?.reads ?? []) need(x.line, `${'id' in x ? 'sfx' : 'voice'} run reads`, f)
+    }
+    for (const m of [l.t.music, ...l.t.shots.map((s) => s.music)]) {
+        if (m && m.song !== NO_MUSIC && isFileSound(m.song, m)) need(m.line, 'music', m.song)
+        for (const f of m?.run?.reads ?? []) need(m!.line, 'music run reads', f)
     }
-    for (const m of [l.t.music, ...l.t.shots.map((s) => s.music)]) if (m && m.song !== NO_MUSIC && isFileWord(m.song)) need(m.line, 'music', m.song)
     const v = l.t.vertical
     if (v && typeof v.outro === 'object') need(v.line, 'vertical outro', v.outro.clip)
     return out
 }
 
-/** the ids that are not files: what only the repo's trailer unit resolves */
+/** a sound word that names a file: never a quoted prompt nor a run's */
+const isFileSound = (w: string, x: { prompt?: true; run?: unknown }): boolean => !x.prompt && !x.run && isFileWord(w)
+
+/** the ids that are not files, prompts nor runs: what the repo's trailer unit resolves (else the house) */
 export function soundIds(t: Trailer): { line: number; kind: 'music' | 'sfx' | 'voice'; id: string }[] {
+    const id = (x: { prompt?: true; run?: unknown }): boolean => !x.prompt && !x.run
     return [
-        ...[t.music, ...t.shots.map((s) => s.music)].flatMap((m) => (m && m.song !== NO_MUSIC && !isFileWord(m.song) ? [{ line: m.line, kind: 'music' as const, id: m.song }] : [])),
+        ...[t.music, ...t.shots.map((s) => s.music)].flatMap((m) => (m && m.song !== NO_MUSIC && id(m) && !isFileWord(m.song) ? [{ line: m.line, kind: 'music' as const, id: m.song }] : [])),
         ...t.shots.flatMap((s) => [
-            ...s.sfx.filter((x) => !isFileWord(x.id)).map((x) => ({ line: x.line, kind: 'sfx' as const, id: x.id })),
-            ...s.voices.filter((v) => v.text !== undefined).map((v) => ({ line: v.line, kind: 'voice' as const, id: v.text! })),
+            ...s.sfx.filter((x) => id(x) && !isFileWord(x.id)).map((x) => ({ line: x.line, kind: 'sfx' as const, id: x.id })),
+            ...s.voices.filter((v) => id(v) && v.text !== undefined).map((v) => ({ line: v.line, kind: 'voice' as const, id: v.text! })),
         ]),
     ]
 }
 
+/** a sound that is no plain file: the repo's unit first (an id it knows), else the house's maker (a prompt, a run, a
+ *  `.mid`, an id the unit answers null) */
+export async function soundFile(l: Pick<Loaded, 'root' | 'file' | 'unit'>, req: SoundRequest, say: Say): Promise<string> {
+    const unit = l.unit
+    const own = houseOnly(req) ? null : req.kind === 'music' ? unit?.sound?.music && ((x: string) => unit.sound!.music!(x, { ...(req.take ? { take: req.take } : {}), seconds: req.seconds ?? 0 })) : req.kind === 'sfx' ? unit?.sound?.sfx : unit?.sound?.voice
+    const got = own ? await own(req.text) : null
+    if (got) return got
+    const house = await houseSound()
+    if (!house) throw new Refused(`${relative(l.root, l.file)}:${req.line}: ${req.kind} ${req.run ? 'run' : req.prompt ? `"${req.text}"` : req.text} is no file, and neither a trailer unit (a <name>.shipkit.ts default-exporting trailer({ sound })) nor the house's sound maker makes it`)
+    return house.resolveSound(l.root, req, say)
+}
+
+/** a request the repo's unit never sees: a prompt, a run, a `.mid` */
+const houseOnly = (r: SoundRequest): boolean => r.prompt === true || r.run !== undefined || r.text.endsWith('.mid')
+
+/** a sound line as the house reads it */
+export function soundRequest(kind: SoundRequest['kind'], text: string, x: { prompt?: true; gen?: SoundGen; run?: SoundRun; line: number }, dir: string, seconds?: number, take?: string): SoundRequest {
+    const g = x.gen ?? {}
+    return {
+        kind,
+        text,
+        ...(g.seed !== undefined ? { seed: g.seed } : {}),
+        ...(g.by ? { by: g.by } : {}),
+        ...(g.for !== undefined ? { for: g.for } : {}),
+        ...(g.hit ? { hit: true } : {}),
+        ...(seconds !== undefined ? { seconds } : {}),
+        line: x.line,
+        ...(x.run ? { run: x.run } : {}),
+        dir,
+        ...(x.prompt ? { prompt: true } : {}),
+        ...(take ? { take } : {}),
+    }
+}
+
+/** the sounds of the cut the house makes: every prompt, run and `.mid`, and every id whose kind the unit has no
+ *  function for (an id the unit answers null is known only when it answers) */
+export function houseRequests(l: Loaded): SoundRequest[] {
+    const s = l.unit?.sound
+    const out: SoundRequest[] = []
+    const add = (r: SoundRequest): void => void (houseOnly(r) || !(r.kind === 'music' ? s?.music : r.kind === 'sfx' ? s?.sfx : s?.voice) ? out.push(r) : undefined)
+    for (const { cue, at, end } of musicCues(l.t)) if (cue.song !== SCORE && (!isFileSound(cue.song, cue) || cue.song.endsWith('.mid'))) add(soundRequest('music', cue.song.endsWith('.mid') && !cue.prompt && !cue.run ? (fileOf(cue.song, l) ?? cue.song) : cue.song, cue, l.dir, cue.from + end - at, cue.take))
+    for (const sh of l.t.shots) {
+        for (const x of sh.sfx) if (!isFileSound(x.id, x)) add(soundRequest('sfx', x.id, x, l.dir))
+        for (const v of sh.voices) if (!v.file) add(soundRequest('voice', v.text ?? 'run', v, l.dir))
+    }
+    return out
+}
+
+/** one line per sound the house makes for this cut (its command, made or to make, a paid voice's characters), from
+ *  the house's `soundStates`; none until it exists. A failure of the house is said, never thrown past the check */
+export async function soundLines(l: Loaded): Promise<string[]> {
+    const p = join(import.meta.dir, 'sound', 'index.ts')
+    const reqs = houseRequests(l)
+    if (!existsSync(p) || reqs.length === 0) return []
+    try {
+        const m = (await import(p)) as { soundStates?: (root: string, rs: SoundRequest[]) => Promise<unknown[]>; stateLine?: (s: unknown) => string }
+        if (!m.soundStates) return []
+        return (await m.soundStates(l.root, reqs)).map((s) => (m.stateLine ? m.stateLine(s) : JSON.stringify(s)))
+    } catch (e) {
+        return [`WARN the house's sound states failed: ${(e as Error).message}`]
+    }
+}
+
+/** the house's sound maker (design call 9, src/trailer/sound/index.ts), null until it exists */
+async function houseSound(): Promise<{ resolveSound(root: string, req: SoundRequest, say: Say): Promise<string> } | null> {
+    const p = join(import.meta.dir, 'sound', 'index.ts')
+    return existsSync(p) ? ((await import(p)) as { resolveSound(root: string, req: SoundRequest, say: Say): Promise<string> }) : null
+}
+
 /** the errors, which stop the build, then the warnings, which do not */
 export function sayErrors(l: Loaded, say: Say, cwd: string): boolean {
     for (const e of l.errors) say(`${relative(cwd, l.file)}:${e.line}: ${e.message}`)
@@ -234,6 +368,7 @@ const filmText = (f: Film | null): string => {
     if (f.kind === 'run') return `run "${f.cmd}"${f.still ? ' still' : ''}`
     if (f.kind === 'cli') return f.argv.join(' ')
     if (f.kind === 'url') return `url ${f.route}${f.viewport ? ` viewport ${f.viewport.join('x')}` : ''}${f.still ? ' still' : ''}`
+    if (f.kind === 'page') return `page ${f.route}${f.query.length ? ` ${f.query.join(' ')}` : ''}, stepped by ${f.step}${f.still ? ', still' : ''}`
     if (f.kind === 'grid') return `grid of ${f.cells.join(', ')}${f.pop ? `, a cell every ${secs(f.pop)}` : ''}${f.grow ? `, growing to ${f.grow.map(secs).join(' and ')}` : ''}`
     if (f.kind === 'split') return `split of ${f.cells.join(', ')}, seams at ${f.angle}°${f.slide ? `, sliding in over ${secs(f.slide)}` : ''}`
     return 'card'
@@ -369,7 +504,7 @@ export async function scoreFile(l: Loaded, seconds: number, say: Say): Promise<s
 /** everything the stitch reads but its output: sources, titles, sounds, the look */
 async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Shot[], silent: boolean, say: Say = () => undefined) {
     const { gridMask, splitMasks } = await import('./stitch.ts')
-    const [{ cardPng, placeOf, titlePng }, { lookOf }, { duration }, { trailerCache }, { loadBrand, identityLogo }] = await Promise.all([
+    const [{ cardPng, titlePng }, { lookOf }, { duration }, { trailerCache }, { loadBrand, identityLogo }] = await Promise.all([
         import('./titles.ts'),
         import('./look.ts'),
         import('./ffmpeg.ts'),
@@ -404,26 +539,27 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
         const tk = takeOf(s)!
         return tk.stamp!.seconds === 0 ? { image: tk.file } : { footage: tk.file, seconds: tk.stamp!.seconds }
     }))
-    const drawn = await Promise.all(shots.map((s) => Promise.all(s.titles.map((ti) => titlePng(titles, l.root, ti.text, ti.style, l.t.size, placeOf(ti), look, ti.step)))))
+    const styleErrors = resolveStyles(l.t, brand?.trailer?.styles ?? {})
+    if (styleErrors.length > 0) throw new Refused(styleErrors.map((e) => `${relative(l.root, l.file)}:${e.line}: ${e.message}`).join('\n'))
+    const motions = titleMotions({ ...l.t, shots: [...shots] })
+    const drawn = await Promise.all(shots.map((s, i) => Promise.all(s.titles.map(async (ti, j) => titlePng(titles, { ...titleRequest(l, ti, look, motions[i]![j]!), font: await titleFont(l, ti) })))))
     if (silent) return { ...base, sources, titles: drawn, music: [], sfx: shots.map(() => []), voices: shots.map(() => []) }
-    const ids = soundIds(l.t)
-    const unit = ids.length > 0 ? await (await import('./load-unit.ts')).loadTrailerUnit(l.root) : null
-    const resolveId = async (kind: 'music' | 'sfx' | 'voice', id: string, line: number, seconds = 0, take?: string): Promise<string> => {
-        const f = kind === 'music' ? unit?.sound?.music && ((x: string) => unit.sound!.music!(x, { take, seconds })) : kind === 'sfx' ? unit?.sound?.sfx : unit?.sound?.voice
-        if (!f) throw new Refused(`${relative(l.root, l.file)}:${line}: ${kind} ${id} is no file, and no trailer unit resolves ${kind} ids (a <name>.shipkit.ts default-exporting trailer({ sound }))`)
-        return f(id)
-    }
+    const resolve = (req: SoundRequest): Promise<string> => soundFile(l, req, say)
+    const ask = (kind: SoundRequest['kind'], text: string, x: { prompt?: true; gen?: SoundGen; run?: SoundRun; line: number }, seconds?: number, take?: string): SoundRequest => soundRequest(kind, text, x, l.dir, seconds, take)
     const music = await Promise.all(
-        musicCues(l.t).map(({ cue, at, end }) =>
-            cue.song === SCORE ? scoreFile(l, cue.from + end - at, say) : isFileWord(cue.song) ? fileOf(cue.song, l)! : resolveId('music', cue.song, cue.line, cue.from + end - at, cue.take),
-        ),
+        musicCues(l.t).map(({ cue, at, end }) => {
+            if (cue.song === SCORE) return scoreFile(l, cue.from + end - at, say)
+            const seconds = cue.from + end - at
+            if (isFileSound(cue.song, cue)) return cue.song.endsWith('.mid') ? resolve(ask('music', fileOf(cue.song, l)!, cue, seconds)) : fileOf(cue.song, l)!
+            return resolve(ask('music', cue.song, cue, seconds, cue.take))
+        }),
     )
     const sfx = await Promise.all(shots.map((s) => Promise.all(s.sfx.map(async (x) => {
-        const file = isFileWord(x.id) ? fileOf(x.id, l)! : await resolveId('sfx', x.id, x.line)
+        const file = isFileSound(x.id, x) ? fileOf(x.id, l)! : await resolve(ask('sfx', x.id, x))
         return { file, seconds: duration(file) }
     }))))
     const voices = await Promise.all(shots.map((s) => Promise.all(s.voices.map(async (v) => {
-        const file = v.file ? fileOf(v.file, l)! : await resolveId('voice', v.text!, v.line)
+        const file = v.file ? fileOf(v.file, l)! : await resolve(ask('voice', v.text ?? 'run', v))
         return { file, seconds: duration(file) }
     }))))
     return { ...base, sources, titles: drawn, music, sfx, voices }
@@ -579,8 +715,13 @@ export async function auditionScore(l: Loaded, o: BuildOptions): Promise<void> {
         `[top][sp]vstack,${marks.join(',')}`,
     ].join(';')
     await ffmpeg(['-i', wav, '-filter_complex', graph, '-frames:v', '1', png])
+    // the score as General MIDI, for a DAW or a soundfont (score/midi.ts), once it exists
+    const midi = join(import.meta.dir, 'score', 'midi.ts')
+    const mid = join(outDir(l), `${l.t.name}.score.mid`)
+    if (existsSync(midi)) writeFileSync(mid, ((await import(midi)) as { scoreMidi(s: CompiledScore): Uint8Array }).scoreMidi(sc))
     o.say(`ok: ${wav} (${span.toFixed(1)} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
     o.say(`ok: ${png} (the waveform over the spectrum; red: each section's start${sc.stop !== null ? ', yellow: the stop' : ''})`)
+    if (existsSync(mid)) o.say(`ok: ${mid} (the score as General MIDI)`)
 }
 
 /** one shot alone with its titles, no sound: out/shot-<name>.mp4 and its nine frames on out/shot-<name>.png */

package/src/trailer/fonts.ts

@@ -0,0 +1,55 @@
+// a title's face: a font file of the repo, or a Google Fonts family fetched once per weight into the machine's cache
+// (every repo shares it). Each face is drawn under a name of its own, and one that does not register fails loud: a
+// title never falls back to another face in silence
+import { GlobalFonts } from '@napi-rs/canvas'
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** a `font` word that names a file; any other names a Google Fonts family */
+export const isFontFile = (w: string): boolean => /\.(ttf|otf|woff2?)$/i.test(w)
+
+export const fontCache = (): string => process.env.SHIPKIT_FONT_CACHE || join(homedir(), '.cache', 'shipkit', 'fonts')
+
+const slug = (family: string): string => family.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+
+/** where a Google Fonts family at a weight is kept */
+export const googleFile = (family: string, weight: number): string => join(fontCache(), `${slug(family)}-${weight}.ttf`)
+
+/** a Google Fonts family at a weight, fetched when the cache lacks it: the css answer names a truetype file to a plain
+ *  agent */
+export async function googleFont(family: string, weight: number): Promise<string> {
+    const file = googleFile(family, weight)
+    if (existsSync(file)) return file
+    const url = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family).replaceAll('%20', '+')}:wght@${weight}`
+    const css = await fetch(url)
+    if (!css.ok) throw new Error(`font "${family}" weight ${weight}: Google Fonts has no such family at that weight (HTTP ${css.status}); check its name and weights on fonts.google.com, or name a font file of the repo (.ttf .otf .woff .woff2)`)
+    const src = /url\((https:[^)]+)\)/.exec(await css.text())?.[1]
+    if (!src) throw new Error(`font "${family}" weight ${weight}: Google Fonts answered with no font file (${url})`)
+    const got = await fetch(src)
+    if (!got.ok) throw new Error(`font "${family}" weight ${weight}: its file did not download (HTTP ${got.status}, ${src})`)
+    mkdirSync(fontCache(), { recursive: true })
+    const part = `${file}.${process.pid}.part`
+    writeFileSync(part, Buffer.from(await got.arrayBuffer()))
+    renameSync(part, file)
+    return file
+}
+
+const registered = new Map<string, string>()
+
+/** the name a face file is drawn under, its own: two files never share a family, and a file that does not load fails */
+export function registerFont(abs: string): string {
+    const had = registered.get(abs)
+    if (had) return had
+    if (!existsSync(abs)) throw new Error(`the font file ${abs} is missing`)
+    const name = `F${new Bun.CryptoHasher('sha1').update(abs).digest('hex').slice(0, 12)}`
+    GlobalFonts.registerFromPath(abs, name)
+    if (!GlobalFonts.has(name)) throw new Error(`the font file ${abs} does not load: a .ttf, .otf, .woff or .woff2 face`)
+    registered.set(abs, name)
+    return name
+}
+
+/** a family the machine draws, never a stand in: a name it lacks fails loud */
+export function hasFamily(family: string): boolean {
+    return family.split(',').some((f) => GlobalFonts.has(f.trim().replace(/^["']|["']$/g, '')))
+}

package/src/trailer/footage.ts

@@ -115,7 +115,7 @@ export async function filmTake(tk: Take, c: FilmContext): Promise<Take> {
     const still = takeIsStill(f)
     let said = ''
     for (let attempt = 1; ; attempt++) {
-        said = f.kind === 'url' ? await urlTake(tk, f, part, seconds, c) : await commandTake(tk, f, part, seconds, c)
+        said = f.kind === 'url' || f.kind === 'page' ? await urlTake(tk, f, part, seconds, c) : await commandTake(tk, f, part, seconds, c)
         if (still || !c.holes) break
         const holes = await (await import('./holes.ts')).takeHoles(part)
         if (holes.length === 0) break
@@ -143,7 +143,7 @@ export async function filmTake(tk: Take, c: FilmContext): Promise<Take> {
 }
 
 /** a take a command writes at `part` (a `film run`, a project CLI row); what it said, or a throw with its last lines */
-async function commandTake(tk: Take, f: Exclude<TakeFilm, { kind: 'url' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
+async function commandTake(tk: Take, f: Exclude<TakeFilm, { kind: 'url' | 'page' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
     if (f.kind === 'cli' && c.cli === null) throw new Error(`shot ${tk.shot.name} (line ${f.line}): film ${f.argv.join(' ')} needs the project CLI (the cli script of package.json)`)
     const argv = f.kind === 'run' ? ['sh', '-c', runCommand(f, { out: part, seconds, size: c.t.size, fps: c.t.fps })] : cliArgv(c.cli!, f, part, seconds, tk.argv)
     // the cut's frame and rate: a row that films at the cut's size reads them
@@ -160,7 +160,7 @@ async function commandTake(tk: Take, f: Exclude<TakeFilm, { kind: 'url' }>, part
 }
 
 /** a `film url` take through the house shot service; a throw names the shot, its line and the service's reason */
-async function urlTake(tk: Take, f: Extract<TakeFilm, { kind: 'url' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
+async function urlTake(tk: Take, f: Extract<TakeFilm, { kind: 'url' | 'page' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
     const { filmUrl } = await import('./url.ts')
     try {
         const note = await filmUrl(f, { root: c.root, base: c.t.base, size: c.t.size, fps: c.t.fps, seconds, out: part, say: c.say })
@@ -168,6 +168,6 @@ async function urlTake(tk: Take, f: Extract<TakeFilm, { kind: 'url' }>, part: st
         return note
     } catch (e) {
         rmSync(part, { force: true })
-        throw new Error(`shot ${tk.shot.name} (line ${f.line}): film url ${f.route}: ${(e as Error).message}`)
+        throw new Error(`shot ${tk.shot.name} (line ${f.line}): film ${f.kind} ${f.route}: ${(e as Error).message}`)
     }
 }