rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/build.ts

@@ -1,10 +1,15 @@
 // 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 { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
-import { type FilmVerb, type Film, parseTrailer, type Shot, starts, total, type Trailer, type TrailerError, musicCues, NO_MUSIC } from './grammar.ts'
+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, type Take, takesToFilm } from './plan.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'
 
@@ -15,6 +20,14 @@ 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')
@@ -50,9 +63,17 @@ export interface Loaded {
     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 */
@@ -62,9 +83,15 @@ export function fileOf(path: string, l: Pick<Loaded, 'dir' | 'root'>): string |
     return null
 }
 
-/** the file parsed and checked against the repo: every error at its line, all at once */
-export function load(file: string, root: string): Loaded {
-    const text = readFileSync(file, 'utf8')
+/** 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[] = []
@@ -80,12 +107,87 @@ export function load(file: string, root: string): Loaded {
         }
     }
     const t = parsed.trailer
-    const l: Loaded = { root, file, dir: dirname(file), t, errors: [...errors, ...parsed.errors], cli, verbs }
+    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[] = []
@@ -114,8 +216,10 @@ export function soundIds(t: Trailer): { line: number; kind: 'music' | 'sfx' | 'v
     ]
 }
 
+/** 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
 }
 
@@ -130,30 +234,56 @@ 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 === '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'
 }
 
-/** the timeline, one line a shot, each take's state against the world */
-export function timeline(l: Loaded, takes: readonly Take[], world: string | null, cwd: string): string[] {
+/** 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`]
-    l.t.shots.forEach((s, i) => {
-        const tk = takes.find((x) => x.shot === s)
-        const state = !isTake(s.film)
-            ? (s.film?.kind === 'card' ? 'drawn' : `a file`)
-            : !tk?.stamp
-              ? 'NOT FILMED'
-              : world === null || fresh(tk.stamp, world)
-                ? 'filmed'
-                : `filmed on an older world, ${ago(tk.stamp.filmedAt)} (--refilm ${s.name})`
+    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(`  ${String(i + 1).padStart(2)} ${st[i]!.toFixed(2).padStart(6)} s  ${s.name.padEnd(20)} ${s.length.toFixed(2).padStart(5)} s${fit}  ${state}${sec}`)
-    })
+        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
 }
 
-const secs = (x: number): string => `${+x.toFixed(2)} s`
+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', ' ')
 
@@ -168,12 +298,12 @@ export function montage(t: Trailer, file: string): string {
         '',
         `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)}` : ', 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)}` : ''}.`,
+        `${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.push ? `, push ${s.push}` : ''))} | ${cell(s.titles.map((ti) => `${ti.style} "${ti.text}" at ${secs(ti.at)}`).join('<br>'))} | ${cell(heard(s))} | ${s.cut.kind === 'hard' ? 'hard' : `${s.cut.kind} ${secs(s.cut.seconds)}`} |`,
+            `| ${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')
@@ -186,16 +316,23 @@ export interface BuildOptions {
     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: string, refilm: Refilm, say: Say, only?: ReadonlySet<string>): Promise<Take[]> {
-    const { filmTake, takesOf } = await import('./footage.ts')
-    const takes = takesOf(l.t, l.root)
+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, cli: l.cli, say })
+                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 }
@@ -210,8 +347,28 @@ async function filmAll(l: Loaded, world: string, refilm: Refilm, say: Say, only?
     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) {
+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'),
@@ -224,18 +381,30 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
     const look = lookOf(brand, await identityLogo(l.root))
     const base = { look, brand }
     const titles = trailerCache(l.root, 'titles')
-    const sources = shots.map((s) => {
+    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 = takes.find((x) => x.shot.name === s.name)!
+        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)))))
+    }))
+    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
@@ -244,7 +413,11 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
         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 }) => (isFileWord(cue.song) ? fileOf(cue.song, l)! : resolveId('music', cue.song, cue.line, cue.from + end - at, cue.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),
+        ),
+    )
     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) }
@@ -259,14 +432,17 @@ async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Sh
 /** 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 }] = await Promise.all([
+    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
@@ -301,16 +477,42 @@ function outDir(l: Loaded): string {
     return dir
 }
 
-/** the whole cut: out/<cut>.mp4, its strip and montage page; the timeline and what was rendered, said */
+/** 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 [{ worldStamp, trailerCache }, { stitch, strip, rendered }, { ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    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 = worldStamp(l.root)
+    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)
+    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
@@ -322,23 +524,80 @@ export async function build(l: Loaded, o: BuildOptions): Promise<string> {
     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 [{ worldStamp, trailerCache }, { stitch }, { sheetOf, ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    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, worldStamp(l.root), o.refilm, o.say, new Set([name]))
+    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}`)
 }

package/src/trailer/ffmpeg.ts

@@ -1,6 +1,7 @@
 // the one way the trailer spawns ffmpeg and ffprobe: a run that fails loud with ffmpeg's own words, a probe, the nine
 // frame sheet. The binaries resolve once, with the homebrew path for processes started without it
 import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename } from 'node:path'
 
 const FFMPEG = Bun.which('ffmpeg') ?? '/opt/homebrew/bin/ffmpeg'
@@ -44,6 +45,27 @@ export function hasAudio(file: string): boolean {
     return r.stdout.toString().trim() !== ''
 }
 
+/** a sound's integrated loudness (LUFS) and true peak (dBTP), as ffmpeg's ebur128 measures them */
+export async function loudness(file: string): Promise<{ lufs: number; truePeak: number }> {
+    const log = await ffmpeg(['-nostats', '-loglevel', 'info', '-i', file, '-map', '0:a', '-af', 'ebur128=peak=true', '-f', 'null', '-'])
+    const summary = log.split('Summary:').at(-1) ?? ''
+    // silence measures -inf: floored, so the value stays a number in json
+    const num = (v: string | undefined): number => (v === '-inf' ? -120 : Number(v ?? Number.NaN))
+    const lufs = num(/I:\s+(-?[\d.]+|-inf) LUFS/.exec(summary)?.[1])
+    const truePeak = num(/Peak:\s+(-?[\d.]+|-inf) dBFS/.exec(summary)?.[1])
+    if (Number.isNaN(lufs) || Number.isNaN(truePeak)) throw new Error(`ebur128 ${basename(file)}: no loudness summary in ffmpeg's log`)
+    return { lufs, truePeak }
+}
+
+/** loudness() of a file that never changes under its name (a cached render), kept beside it */
+export async function loudnessKept(file: string): Promise<{ lufs: number; truePeak: number }> {
+    const json = `${file}.loudness.json`
+    if (existsSync(json)) return JSON.parse(readFileSync(json, 'utf8')) as { lufs: number; truePeak: number }
+    const m = await loudness(file)
+    writeFileSync(json, JSON.stringify(m))
+    return m
+}
+
 /** nine frames of a clip evenly spaced, three by three on one png: how a shot is judged */
 export async function sheetOf(clip: string, seconds: number, png: string): Promise<void> {
     await ffmpeg(['-i', clip, '-vf', `fps=${(9 / seconds).toFixed(4)},scale=480:-2,tile=3x3`, '-frames:v', '1', png])