rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/build.ts

@@ -0,0 +1,603 @@
+// a cut's .trailer file → its mp4: load (parse, resolve every file and sound), film what is missing, draw the titles,
+// 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 { 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 type { Stitched } from './stitch.ts'
+import { projectCli, readVocab } from './vocab.ts'
+
+export type Say = (line: string) => void
+
+export class Refused extends Error {}
+const refuse = (why: string): never => {
+    throw new Refused(why)
+}
+
+/** every cut a build can name: each `.trailer` under `trailer/`, at any depth, a kept version's and `out/` left out */
+export function cutFiles(root: string, dir = join(root, 'trailer')): string[] {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir, { withFileTypes: true })
+        .flatMap((e) => (e.isDirectory() ? (e.name === 'versions' || e.name === 'out' ? [] : cutFiles(root, join(dir, e.name))) : e.name.endsWith('.trailer') ? [join(dir, e.name)] : []))
+        .sort()
+}
+
+/** every `.trailer` under `trailer/<trailer>/` */
+export function trailerFiles(root: string): string[] {
+    const dir = join(root, 'trailer')
+    if (!existsSync(dir)) return []
+    return readdirSync(dir)
+        .filter((d) => statSync(join(dir, d)).isDirectory())
+        .flatMap((d) => readdirSync(join(dir, d)).filter((f) => f.endsWith('.trailer')).map((f) => join(dir, d, f)))
+        .sort()
+}
+
+/** the .trailer a command names: a file, a folder's main.trailer (or its one .trailer), or the one under trailer/ */
+export function trailerFile(arg: string | undefined, root: string, cwd: string): string {
+    if (arg !== undefined) {
+        const p = resolve(cwd, arg)
+        if (existsSync(p) && statSync(p).isDirectory()) {
+            if (existsSync(join(p, 'main.trailer'))) return join(p, 'main.trailer')
+            const own = readdirSync(p).filter((f) => f.endsWith('.trailer'))
+            return own.length === 1 ? join(p, own[0]!) : refuse(own.length === 0 ? `${arg} has no .trailer` : `${arg} has several cuts, name one: ${own.join(', ')}`)
+        }
+        return existsSync(p) ? p : refuse(`no file ${arg}`)
+    }
+    const all = trailerFiles(root)
+    if (all.length === 1) return all[0]!
+    return refuse(all.length === 0 ? 'no .trailer under trailer/<trailer>/: write trailer/<name>/main.trailer (wiki build/trailer.md)' : `several cuts, name one: ${all.map((f) => relative(cwd, f)).join(', ')}`)
+}
+
+/** a sound or a media word that names a file rather than an id */
+export const isFileWord = (w: string): boolean => w.includes('/') || /\.[a-z0-9]{2,5}$/i.test(w)
+
+export interface Loaded {
+    root: string
+    file: string
+    dir: string
+    t: Trailer
+    errors: TrailerError[]
+    /** what the trailer unit's check said and never blocks */
+    warnings: TrailerError[]
+    /** the project CLI's argv, null when the repo has none */
+    cli: string[] | null
+    verbs: FilmVerb[] | null
+    /** the score's notes, null when the cut has none or it failed */
+    score: CompiledScore | null
+    /** each `@<file>` word of a film line, found */
+    recipes: Map<string, Recipe>
+    /** the repo's trailer unit, null when it has none */
+    unit: TrailerUnit | null
+}
+
+/** a file a line names: beside the .trailer first, then from the repo root */
+export function fileOf(path: string, l: Pick<Loaded, 'dir' | 'root'>): string | null {
+    if (isAbsolute(path)) return existsSync(path) ? path : null
+    for (const f of [join(l.dir, path), join(l.root, path)]) if (existsSync(f)) return f
+    return null
+}
+
+/** 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> {
+    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) {
+        ;(await import('./vocab.ts')).forgetVocab()
+        ;(await import('./load-unit.ts')).forgetTrailerUnit(root)
+    }
+    const cli = projectCli(root)
+    let verbs: FilmVerb[] | null = null
+    const errors: TrailerError[] = []
+    let parsed = parseTrailer(text, { verbs: null })
+    // 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 })
+        } 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) }
+    l.errors.push(...findRecipes(l))
+    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'))
+        l.score = c.score
+        l.errors.push(...c.errors)
+    }
+    if (l.errors.length === 0 && l.unit?.check && o.check !== false) {
+        for (const f of await l.unit.check(checkInput(l))) (f.warn ? l.warnings : l.errors).push({ line: f.line, message: f.message })
+        l.warnings.sort((a, b) => a.line - b.line)
+    }
+    l.errors.sort((a, b) => a.line - b.line)
+    return l
+}
+
+/** each `@<file>` word of a film line, and each file a `film run` reads: beside the .trailer first, then from the repo
+ *  root; its repo relative path */
+function findRecipes(l: Loaded): TrailerError[] {
+    const out: TrailerError[] = []
+    for (const s of [...l.t.shots, ...l.t.footage]) {
+        const f = s.film
+        if (f?.kind === 'run')
+            for (const p of f.reads ?? []) {
+                const abs = fileOf(p, l)
+                if (!abs) out.push({ line: f.line, message: `film run: no file ${p} beside the .trailer or from the repo root (reads)` })
+                // its bytes by their digest: an image read as text would lose them
+                else l.recipes.set(`reads:${p}`, { path: relative(l.root, abs), text: new Bun.CryptoHasher('sha1').update(readFileSync(abs)).digest('hex') })
+            }
+        if (f?.kind !== 'cli') continue
+        for (const i of f.files ?? []) {
+            const w = f.argv[i]!
+            if (l.recipes.has(`file:${w}`)) continue
+            const abs = fileOf(w, l)
+            if (!abs) out.push({ line: f.line, message: `film ${f.argv[0]}: no file ${w} beside the .trailer or from the repo root` })
+            else l.recipes.set(`file:${w}`, { path: abs.startsWith(`${l.root}/`) ? relative(l.root, abs) : abs, text: new Bun.CryptoHasher('sha1').update(readFileSync(abs)).digest('hex') })
+        }
+        for (const w of recipeWords(f.argv)) {
+            if (l.recipes.has(w)) continue
+            const abs = fileOf(w.slice(1), l)
+            if (!abs) out.push({ line: f.line, message: `film: no recipe ${w.slice(1)} beside the .trailer or from the repo root` })
+            else l.recipes.set(w, { path: abs.startsWith(`${l.root}/`) ? relative(l.root, abs) : abs, text: readFileSync(abs, 'utf8') })
+        }
+    }
+    return out
+}
+
+/** what the trailer unit's check reads: the film lines of the project CLI, the sounds named by id */
+export function checkInput(l: Loaded): TrailerCheckInput {
+    const ids = soundIds(l.t)
+    return {
+        file: l.file,
+        dir: l.dir,
+        size: l.t.size,
+        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 }] : [],
+        ),
+        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 })),
+    }
+}
+
+/** every take of the cut, its spec read through the repo's unit */
+export const takesOfLoaded = (l: Loaded): Take[] => takesOf(l.t, l.root, l)
+
+/** the world each take shows: its row's `stamp` paths, else the unit's `stamp`, else the whole repo; each measured once */
+export async function worldOf(l: Pick<Loaded, 'root' | 'unit'>): Promise<(tk: Take) => string> {
+    const { worldStamp } = await import('./footage.ts')
+    const seen = new Map<string, string>()
+    return (tk) => {
+        const paths = tk.spec.stamp ?? l.unit?.stamp
+        const k = JSON.stringify(paths ?? null)
+        let w = seen.get(k)
+        if (w === undefined) seen.set(k, (w = worldStamp(l.root, paths)))
+        return w
+    }
+}
+
+/** the clips, images and sound files the lines name, each found where it should be */
+function checkFiles(l: Loaded): TrailerError[] {
+    const out: TrailerError[] = []
+    const need = (line: number, what: string, path: string): void => {
+        if (!fileOf(path, l)) out.push({ line, message: `${what}: no file ${path} beside the .trailer or from the repo root` })
+    }
+    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 v of s.voices) if (v.file) need(v.line, 'voice file', v.file)
+    }
+    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 */
+export function soundIds(t: Trailer): { line: number; kind: 'music' | 'sfx' | 'voice'; id: string }[] {
+    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.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! })),
+        ]),
+    ]
+}
+
+/** 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}`)
+    for (const w of l.warnings) say(`WARN ${relative(cwd, l.file)}:${w.line}: ${w.message}`)
+    return l.errors.length === 0
+}
+
+const ago = (iso: string): string => {
+    const m = Math.round((Date.now() - Date.parse(iso)) / 60_000)
+    return m < 60 ? `${m} min ago` : m < 48 * 60 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} days ago`
+}
+
+const filmText = (f: Film | null): string => {
+    if (!f) return 'nothing'
+    if (f.kind === 'clip' || f.kind === 'image') return `${f.kind} ${f.path}`
+    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 === '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'
+}
+
+/** what changes at a shot's edges in its take (states.ts): a box rising or a change playing on a cut */
+function edgesOf(s: Shot, tk: Take, fps: number, rule: TrailerUnit['states']): string {
+    const states = tk.stamp?.states
+    if (!states) return ''
+    const first = Math.ceil(s.from * fps - 1e-6)
+    const found = edgeChanges(decodeStates(states), first, first + Math.round(s.length * fps) - 1, rule ?? {})
+    return found.length > 0 ? `, AT ITS EDGES: ${found.join('; ')}` : ''
+}
+
+/** the timeline, one line a shot then one a footage block, each take's state against the world: a take's last frame
+ *  held, a change at its edges */
+export function timeline(l: Loaded, takes: readonly Take[], world: World | null, cwd: string): string[] {
+    const st = starts(l.t)
+    const out = [`${relative(cwd, l.file)}: ${l.t.shots.length} shots, ${total(l.t).toFixed(2)} s, ${l.t.size.join('x')} at ${l.t.fps} fps`]
+    const takeOf = (s: Shot): Take | undefined => takes.find((x) => x.shot === s)
+    const line = (s: Shot, head: string): void => {
+        const tk = takeOf(s)
+        const f = s.film
+        const cells = f?.kind === 'grid' || f?.kind === 'split' ? gridCells(l.t, f.cells).map((c) => (c ? takeOf(c) : undefined)) : []
+        const state =
+            f?.kind === 'grid' || f?.kind === 'split'
+                ? `a ${f.kind} of ${cells.length}, ${cells.filter((c) => c?.stamp).length} filmed`
+                : !isTake(f)
+                  ? f?.kind === 'card' ? 'drawn' : 'a file'
+                  : !tk?.stamp
+                    ? 'NOT FILMED'
+                    : world === null || fresh(tk.stamp, worldFor(world, tk))
+                      ? 'filmed'
+                      : `filmed on an older world, ${ago(tk.stamp.filmedAt)} (--refilm ${s.name})`
+        const held = tk?.stamp && !takeIsStill(tk.film) && tk.stamp.seconds - s.from < s.length - 0.05 ? `, its last frame held ${(s.length - (tk.stamp.seconds - s.from)).toFixed(2)} s` : ''
+        const edges = tk ? edgesOf(s, tk, l.t.fps, l.unit?.states) : ''
+        const sec = s.section ? `  [section ${s.section.name} at ${+s.section.at.toFixed(3)} s]` : ''
+        const fit = s.written !== undefined ? ` (fitted, written ${s.written} s)` : ''
+        out.push(`  ${head} ${s.name.padEnd(20)} ${s.length.toFixed(2).padStart(5)} s${fit}  ${state}${held}${edges}${sec}`)
+    }
+    l.t.shots.forEach((s, i) => line(s, `${String(i + 1).padStart(2)} ${st[i]!.toFixed(2).padStart(6)} s `))
+    for (const s of l.t.footage) line(s, ' footage  ')
+    const sc = l.score
+    if (sc) out.push(`  score: ${sc.sections.length} sections, ${sc.notes.length} notes, ${(sc.seconds - SCORE_LEAD).toFixed(2)} s from the cut's ${(l.t.timelineAt ?? 0).toFixed(2)} s${sc.stop !== null ? `, cut dead at its ${(sc.stop - SCORE_LEAD).toFixed(2)} s` : ''}`)
+    return out
+}
+
+function secs(x: number): string {
+    return `${+x.toFixed(2)} s`
+}
+const clockText = (x: number): string => `${Math.floor(x / 60)}:${(x % 60).toFixed(2).padStart(5, '0')}`
+const cell = (s: string): string => s.replaceAll('|', '\\|').replaceAll('\n', ' ')
+
+/** the cut as a table an agent or a human reads: `out/<cut>.montage.md`, written by every build */
+export function montage(t: Trailer, file: string): string {
+    const st = starts(t)
+    const m = t.music
+    const heard = (s: Shot): string =>
+        [s.music ? `music ${s.music.song}` : '', ...s.sfx.map((x) => `sfx ${x.id} at ${secs(x.at)}`), ...s.voices.map((v) => `voice ${v.text ? `"${v.text}"` : v.file} at ${secs(v.at)}`)].filter(Boolean).join('<br>')
+    return [
+        `# Montage: ${t.name}`,
+        '',
+        `Written from \`${file}\` by every \`sk trailer\` build: edit the .trailer, never this file.`,
+        '',
+        `${secs(total(t))}, ${t.size[0]}x${t.size[1]} at ${t.fps} fps, ${t.shots.length} shots${m ? `, music \`${m.song}\` from ${clockText(m.from)}` : ''}${t.score ? `, its own score from ${clockText(t.timelineAt ?? 0)}` : ''}${!m && !t.score ? ', no music' : ''}${t.sections.length ? `, ${t.sections.length} sections: ${t.sections.map((x) => x.name).join(', ')}` : ''}${t.fadeIn ? `, opens from black over ${secs(t.fadeIn)}` : ''}.`,
+        '',
+        '| # | at | shot | length | film | on screen | heard | cut out |',
+        '|---|---|---|---|---|---|---|---|',
+        ...t.shots.map((s, i) =>
+            `| ${i + 1} | ${clockText(st[i] ?? 0)} | ${s.name} | ${secs(s.length)} | ${cell(filmText(s.film) + (s.from ? `, from ${secs(s.from)}` : '') + (s.frame ? `, frame ${s.frame}${s.frameAt ? ` at ${s.frameAt.join(',')}` : ''}` : '') + (s.push ? `, push ${s.push}` : ''))} | ${cell([...s.titles.map((ti) => `${ti.style} "${ti.text}" at ${secs(ti.at)}`), ...s.shakes.map((x) => `shake at ${secs(x.at)}`), ...s.flashes.map((x) => `flash at ${secs(x.at)}`)].join('<br>'))} | ${cell(heard(s))} | ${s.cut.kind === 'hard' ? 'hard' : `${s.cut.kind} ${secs(s.cut.seconds)}`} |`,
+        ),
+        '',
+    ].join('\n')
+}
+
+export interface BuildOptions {
+    refilm: Refilm
+    final: boolean
+    say: Say
+    cwd: string
+}
+
+/** the shots `names` names and the cells their grids and splits read: what a preview films */
+function withCells(l: Loaded, names: Iterable<string>): Set<string> {
+    const out = new Set(names)
+    for (const s of l.t.shots) if (out.has(s.name) && (s.film?.kind === 'grid' || s.film?.kind === 'split')) for (const c of s.film.cells) out.add(c)
+    return out
+}
+
+/** film the takes missing (and what --refilm names), two at once; every shot is tried, the failures said together */
+async function filmAll(l: Loaded, world: World, refilm: Refilm, say: Say, only?: ReadonlySet<string>): Promise<Take[]> {
+    const { filmTake } = await import('./footage.ts')
+    const takes = takesOfLoaded(l)
+    const ask = takesToFilm(takes, world, refilm, only)
+    const failed: string[] = []
+    const lane = async (): Promise<void> => {
+        for (let group = ask.shift(); group; group = ask.shift()) {
+            try {
+                const got = await filmTake(group[0]!, { root: l.root, t: l.t, world: worldFor(world, group[0]!), cli: l.cli, holes: l.unit?.holes === true, say })
+                for (const tk of group) {
+                    const i = takes.indexOf(tk)
+                    takes[i] = { ...tk, stamp: got.stamp }
+                }
+            } catch (e) {
+                failed.push(e instanceof Error ? e.message : String(e))
+            }
+        }
+    }
+    await Promise.all([lane(), lane()])
+    if (failed.length > 0) throw new Refused(`${failed.length} shot(s) did not film:\n${failed.join('\n')}`)
+    return takes
+}
+
+/** the score's wav of `seconds`, rendered by the synth when the cache misses it; each section's level said, and a
+ *  section whose notes are silent refuses the build */
+export async function scoreFile(l: Loaded, seconds: number, say: Say): Promise<string> {
+    const { levelLine, scoreWav } = await import('./score/sound.ts')
+    const sc = l.score ?? refuse(`${relative(l.root, l.file)}: the score did not compile`)
+    const w = scoreWav(sc, seconds, trailerCache(l.root, 'sound'))
+    say(w.made ? `  score: ${sc.notes.length} notes, ${Math.ceil(seconds)} s rendered in ${(w.ms / 1000).toFixed(1)} s` : '  score: cached')
+    const silent: string[] = []
+    for (const x of w.levels) {
+        const { line, bad } = levelLine(x)
+        say(`  ${bad ? 'WARN ' : ''}${line}`)
+        if (bad === 'silent') silent.push(x.name)
+    }
+    if (silent.length > 0) refuse(`the score is silent in ${silent.join(', ')} although notes play there: an instrument at volume 0, a track volume 0, or notes out of hearing`)
+    const m = await (await import('./ffmpeg.ts')).loudnessKept(w.file)
+    say(`  score: ${m.lufs.toFixed(1)} LUFS integrated, true peak ${m.truePeak.toFixed(1)} dBTP`)
+    return w.file
+}
+
+/** 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([
+        import('./titles.ts'),
+        import('./look.ts'),
+        import('./ffmpeg.ts'),
+        import('./footage.ts'),
+        import('../assets/run-assets.ts'),
+    ])
+    const brand = await loadBrand(l.root)
+    if (typeof brand === 'string') throw new Refused(brand)
+    const look = lookOf(brand, await identityLogo(l.root))
+    const base = { look, brand }
+    const titles = trailerCache(l.root, 'titles')
+    const pieces = trailerCache(l.root, 'pieces')
+    const takeOf = (s: Shot): Take | undefined => takes.find((x) => x.shot === s) ?? takes.find((x) => x.shot.name === s.name)
+    const sources = await Promise.all(shots.map(async (s): Promise<Source> => {
+        const f = s.film!
+        if (f.kind === 'grid' || f.kind === 'split') {
+            const cells = gridCells(l.t, f.cells).map((c, j) => {
+                const tk = c && takeOf(c)
+                if (!c || !tk?.stamp) throw new Refused(`shot ${s.name}: its cell ${f.cells[j]} is not filmed`)
+                return { footage: tk.file, seconds: tk.stamp.seconds, from: c.from, frame: c.frame, ...(f.kind === 'grid' && c.frameAt ? { at: c.frameAt } : {}) }
+            })
+            if (f.kind === 'split') return { split: cells, angle: f.angle, slide: f.slide, masks: await splitMasks(pieces, cells.length, f.angle, l.t.size, look) }
+            const k = f.grow ? GROW_RES : 1
+            return { grid: cells, pop: f.pop, ...(f.grow ? { grow: f.grow } : {}), mask: await gridMask(pieces, cells.length, [l.t.size[0] * k, l.t.size[1] * k], look) }
+        }
+        if (f.kind === 'card') return { image: cardPng(titles, l.t.size, look) }
+        if (f.kind === 'image') return { image: fileOf(f.path, l)! }
+        if (f.kind === 'clip') {
+            const file = fileOf(f.path, l)!
+            return { footage: file, seconds: duration(file) }
+        }
+        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)))))
+    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 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),
+        ),
+    )
+    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)
+        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)
+        return { file, seconds: duration(file) }
+    }))))
+    return { ...base, sources, titles: drawn, music, sfx, voices }
+}
+
+/** a vertical cut finished: what the brand's vertical look draws over the stitched cut, the outro, the end card. The
+ *  finish is cached on the pieces and the mix it reads, so a build that changed nothing encodes nothing */
+async function finishVertical(l: Loaded, input: { look: TrailerLook; brand: BrandLike | null }, done: Stitched, cut: string, out: string, final: boolean): Promise<{ note: string; seconds: number }> {
+    const [{ finishArgs, finishSeconds, verticalOf }, { drawEnd, drawMark, drawWear }, { cachedAs }, { duration, hasAudio }, { trailerCache }, { shortLook }] = await Promise.all([
+        import('./vertical.ts'),
+        import('./vertical-draw.ts'),
+        import('./stitch.ts'),
+        import('./ffmpeg.ts'),
+        import('./footage.ts'),
+        import('./look.ts'),
+    ])
+    const v = l.t.vertical!
+    // the vertical's words wear the short's face and colours
+    input = { ...input, look: shortLook(input.look) }
+    const vl = verticalOf(input.brand, input.look, basename(l.root), v.mark)
+    const dir = trailerCache(l.root, 'titles')
+    const clip = typeof v.outro === 'object' ? fileOf(v.outro.clip, l)! : null
+    const [wear, mark, end] = await Promise.all([
+        drawWear(dir, l.root, input.look, vl, l.t.size, l.t.fps),
+        clip ? drawMark(dir, l.root, input.look, vl, l.t.size) : null,
+        v.outro === 'none' ? null : drawEnd(dir, l.root, input.look, vl, l.t.size),
+    ])
+    const a = {
+        cut,
+        seconds: duration(cut),
+        size: l.t.size,
+        fps: l.t.fps,
+        wear,
+        mark,
+        outro: clip ? { clip, seconds: duration(clip), audio: hasAudio(clip) } : null,
+        end: end && { ...end, seconds: vl.end!.seconds },
+        encoder: final ? ('final' as const) : ('draft' as const),
+    }
+    const clipStat = clip ? [statSync(clip).size, statSync(clip).mtimeMs] : null
+    const key = new Bun.CryptoHasher('sha1').update(JSON.stringify([finishArgs(a, 'out.mp4'), done.pieces.map((p) => p.file), done.mix, clipStat])).digest('hex').slice(0, 16)
+    const { files, made } = await cachedAs(join(trailerCache(l.root, 'pieces'), 'vertical'), `${l.t.name}-vertical`, key, ['mp4'], ([o]) => finishArgs(a, o!))
+    copyFileSync(files[0]!, out)
+    return { note: made ? 'the vertical finished' : 'the vertical cached', seconds: finishSeconds(a) }
+}
+
+/** trailer/<trailer>/out/, its own `.gitignore` holding `*`: a build output is never committed by accident */
+function outDir(l: Loaded): string {
+    const dir = join(l.dir, 'out')
+    mkdirSync(dir, { recursive: true })
+    if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), '*\n')
+    return dir
+}
+
+/** each shot's take beside the cut, in cut order and by name (`out/<cut>-shots/07-town.mp4`): clones, free on APFS;
+ *  never a hard link, which a take filmed again in place would turn into the new picture */
+function shelve(l: Loaded, takes: readonly Take[]): void {
+    const dir = join(outDir(l), `${l.t.name}-shots`)
+    rmSync(dir, { recursive: true, force: true })
+    mkdirSync(dir, { recursive: true })
+    l.t.shots.forEach((s, i) => {
+        const f = s.film
+        const from = f?.kind === 'clip' || f?.kind === 'image' ? fileOf(f.path, l) : takes.find((x) => x.shot === s)?.file
+        if (!from || !existsSync(from)) return
+        copyFileSync(from, join(dir, `${String(i + 1).padStart(2, '0')}-${s.name}${extname(from)}`), constants.COPYFILE_FICLONE)
+    })
+}
+
+/** the cache trimmed after a stitch, said in one line */
+async function pruneAfter(root: string, say: Say): Promise<void> {
+    const { prune, sayPruned } = await import('./prune.ts')
+    // the cut is written: a prune that fails is said, never the build's failure
+    try {
+        for (const line of sayPruned(await prune(root, { dry: false }), false, true)) say(line)
+    } catch (e) {
+        say(`WARN the cache prune failed, the cut is written: ${(e as Error).message}`)
+    }
+}
+
+/** the whole cut: out/<cut>.mp4, its strip, montage page and shelf of takes; the timeline and what was rendered, said */
+export async function build(l: Loaded, o: BuildOptions): Promise<string> {
+    const t0 = performance.now()
+    const [{ trailerCache }, { stitch, strip, rendered }, { ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const world = await worldOf(l)
+    const takes = await filmAll(l, world, o.refilm, o.say)
+    shelve(l, takes)
+    const tFilm = performance.now()
+    const input = await stitchInput(l, takes, l.t.shots, false, o.say)
+    const out = join(outDir(l), `${l.t.name}.mp4`)
+    // a vertical cut stitches into the cache, and its finish writes the mp4
+    const cut = l.t.vertical ? join(trailerCache(l.root, 'pieces'), `${l.t.name}-cut.mp4`) : out
+    const done = await stitch({ ...input, t: l.t, out: cut, cache: trailerCache(l.root, 'pieces'), encoder: o.final ? 'final' : 'draft' })
+    const finished = l.t.vertical ? await finishVertical(l, input, done, cut, out, o.final) : null
+    const stripFile = join(outDir(l), `${l.t.name}.strip.png`)
+    await strip(done.pieces, stripFile)
+    writeFileSync(join(outDir(l), `${l.t.name}.montage.md`), montage(l.t, basename(l.file)))
+    for (const line of timeline(l, takes, world, o.cwd)) o.say(line)
+    o.say(`ok: ${out} (${(finished?.seconds ?? total(l.t)).toFixed(2)} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s: filming ${((tFilm - t0) / 1000).toFixed(1)} s, ${rendered(done)}${finished ? `, ${finished.note}` : ''}`)
+    o.say(`ok: ${stripFile}`)
+    // the vertical's finish can lay an outro's own sound after the mix: its mp4 is what is measured then
+    const heard = finished ? out : done.mix
+    if (heard) {
+        const [{ loudness, loudnessKept }, { MIX_TRUE_PEAK }] = await Promise.all([import('./ffmpeg.ts'), import('./graph.ts')])
+        const { lufs, truePeak } = await (finished ? loudness(heard) : loudnessKept(heard))
+        const line = `the mix: ${lufs.toFixed(1)} LUFS integrated, true peak ${truePeak.toFixed(1)} dBTP`
+        if (truePeak > 0) refuse(`${line}, past 0 dBTP: it clips on a player. ${out} is written; lower the loudest sounds (a score's volume, a sfx or voice volume)`)
+        o.say(truePeak > MIX_TRUE_PEAK ? `WARN ${line}, past the limiter's ${MIX_TRUE_PEAK} dBTP` : `ok: ${line}`)
+    }
+    await pruneAfter(l.root, o.say)
+    return out
+}
+
+/** one section with its window of the sound: out/<cut>-<section>.mp4; `start` the shots before the first section */
+export async function previewSection(l: Loaded, name: string, o: BuildOptions): Promise<void> {
+    const t0 = performance.now()
+    const [{ trailerCache }, { stitchPiece, rendered }, { ffmpegMissing }, { pieces }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts'), import('./plan.ts')])
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const p = pieces(l.t).find((x) => x.name === name) ?? refuse(`no section ${name} in ${relative(o.cwd, l.file)}: ${pieces(l.t).map((x) => x.name).join(', ')}`)
+    const takes = await filmAll(l, await worldOf(l), null, o.say, withCells(l, l.t.shots.slice(p.chain, p.end).map((s) => s.name)))
+    const input = await stitchInput(l, takes, l.t.shots, false, o.say)
+    const out = join(outDir(l), `${l.t.name}-${name}.mp4`)
+    const done = await stitchPiece({ ...input, t: l.t, out, cache: trailerCache(l.root, 'pieces'), encoder: o.final ? 'final' : 'draft' }, name)
+    await pruneAfter(l.root, o.say)
+    o.say(`ok: ${out} (${((p.to - p.from) / l.t.fps).toFixed(2)} s, frames ${p.from} to ${p.to}) in ${((performance.now() - t0) / 1000).toFixed(1)} s (${rendered(done)})`)
+}
+
+/** the score alone, no picture: out/<cut>.score.wav, its waveform with a line at each section's start on
+ *  out/<cut>.score.png, each section's level and the whole's loudness said */
+export async function auditionScore(l: Loaded, o: BuildOptions): Promise<void> {
+    const t0 = performance.now()
+    const sc = l.score ?? refuse(`${relative(o.cwd, l.file)} has no score: score tempo <bpm> in the header, sections with their plays`)
+    const { ffmpeg, ffmpegMissing } = await import('./ffmpeg.ts')
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const src = await scoreFile(l, sc.seconds, o.say)
+    const wav = join(outDir(l), `${l.t.name}.score.wav`)
+    copyFileSync(src, wav)
+    const png = join(outDir(l), `${l.t.name}.score.png`)
+    const [w, h] = [1600, 320]
+    const { TAIL_S } = await import('./score/synth.ts')
+    const span = Math.ceil(sc.seconds) + TAIL_S
+    const line = (at: number, colour: string): string => `drawbox=x=${Math.round((at / span) * w)}:y=0:w=2:h=ih:color=${colour}@0.9:t=fill`
+    const marks = [...sc.sections.map((x) => line(x.at, '0xff5050')), ...(sc.stop !== null ? [line(sc.stop, '0xffd040')] : [])]
+    // the waveform over a dark ground, the spectrum under it (low notes at the bottom), a line at each section's start
+    const graph = [
+        `color=c=0x14171c:s=${w}x${h}[bg]`,
+        `[0:a]asplit[a][b]`,
+        `[a]showwavespic=s=${w}x${h}:split_channels=1:colors=0x9ad0ff|0x9ad0ff[wv]`,
+        `[bg][wv]overlay=format=auto[top]`,
+        `[b]showspectrumpic=s=${w}x${h}:legend=0:scale=log:fscale=log[sp]`,
+        `[top][sp]vstack,${marks.join(',')}`,
+    ].join(';')
+    await ffmpeg(['-i', wav, '-filter_complex', graph, '-frames:v', '1', png])
+    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' : ''})`)
+}
+
+/** one shot alone with its titles, no sound: out/shot-<name>.mp4 and its nine frames on out/shot-<name>.png */
+export async function previewShot(l: Loaded, name: string, o: BuildOptions): Promise<void> {
+    const t0 = performance.now()
+    const s = l.t.shots.find((x) => x.name === name) ?? refuse(`no shot ${name} in ${relative(o.cwd, l.file)}: ${l.t.shots.map((x) => x.name).join(', ')}`)
+    const [{ trailerCache }, { stitch }, { sheetOf, ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const one: Trailer = { ...l.t, name: `${l.t.name}-shot-${name}`, music: null, fadeIn: 0, shots: [{ ...s, cut: { line: s.line, kind: 'hard', seconds: 0 }, sfx: [], voices: [], music: null }] }
+    const takes = await filmAll(l, await worldOf(l), o.refilm, o.say, withCells(l, [name]))
+    const input = await stitchInput(l, takes, one.shots, true)
+    const out = join(outDir(l), `shot-${name}.mp4`)
+    await stitch({ ...input, t: one, out, cache: trailerCache(l.root, 'pieces'), silent: true })
+    const sheet = out.replace(/\.mp4$/, '.png')
+    await sheetOf(out, s.length, sheet)
+    await pruneAfter(l.root, o.say)
+    o.say(`ok: ${out} (${s.length} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
+    o.say(`ok: ${sheet}`)
+}