rvlib-shipkit 2.1.1 → 2.2.0

package/src/trailer/graph.ts

@@ -0,0 +1,323 @@
+// the stitch's ffmpeg arguments, as data: a piece of the cut (its shots cut to their frames, joined by their cuts, the
+// titles laid over) and the mix of the sound. Pure: stitch.ts runs them, keyed on these very arguments
+import type { CutKind, Shot, Trailer } from './grammar.ts'
+import { musicCues, starts, total } from './grammar.ts'
+import type { TrailerLook } from './look.ts'
+import { frameAt, frameSpans, type Piece } from './plan.ts'
+import type { TitleImage } from './titles.ts'
+
+/** a wipe's edge, as xfade draws it: along x or y, starting from the far side (`from`) or the near one */
+const SEAM_EDGE: Partial<Record<CutKind, { axis: 'x' | 'y'; from: boolean }>> = {
+    'wipe-left': { axis: 'x', from: true },
+    'wipe-right': { axis: 'x', from: false },
+    'wipe-up': { axis: 'y', from: true },
+    'wipe-down': { axis: 'y', from: false },
+}
+
+const XFADE: Record<Exclude<CutKind, 'hard'>, string> = {
+    fade: 'fade',
+    'dip-black': 'fadeblack',
+    'dip-white': 'fadewhite',
+    'slide-left': 'slideleft',
+    'slide-right': 'slideright',
+    'slide-up': 'slideup',
+    'slide-down': 'slidedown',
+    'whip-left': 'smoothleft',
+    'whip-right': 'smoothright',
+    'wipe-left': 'wipeleft',
+    'wipe-right': 'wiperight',
+    'wipe-up': 'wipeup',
+    'wipe-down': 'wipedown',
+    circle: 'circleopen',
+    pixel: 'pixelize',
+}
+
+/** what each shot is drawn from: a video and its length, or a still image held for the shot */
+export type Source = { footage: string; seconds: number } | { image: string }
+
+export interface StitchInput {
+    t: Trailer
+    sources: Source[]
+    /** each title's PNG, shot by shot, in the order of its titles */
+    titles: TitleImage[][]
+    /** each music cue's file, in the order of musicCues */
+    music: string[]
+    /** each sfx's file and length, shot by shot */
+    sfx: { file: string; seconds: number }[][]
+    /** each voice line's file and its length, shot by shot */
+    voices: { file: string; seconds: number }[][]
+    look: TrailerLook
+}
+
+const n3 = (x: number): string => (+x.toFixed(4)).toString()
+/** ffmpeg's colour syntax for a hex colour */
+const ff = (c: string): string => (c.startsWith('#') ? `0x${c.slice(1)}` : c)
+
+const MAC = process.platform === 'darwin'
+const X264 = ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', '18', '-pix_fmt', 'yuv420p']
+/** how a piece is encoded: `draft` the Mac's media engine, `final` x264 for a release, `lossless` for parity tests */
+export const ENCODERS = {
+    draft: MAC ? ['-c:v', 'h264_videotoolbox', '-q:v', '70', '-pix_fmt', 'yuv420p'] : X264,
+    final: X264,
+    lossless: ['-c:v', 'libx264', '-preset', 'ultrafast', '-qp', '0', '-pix_fmt', 'yuv420p'],
+} as const
+export type Encoder = keyof typeof ENCODERS
+/** the footage decoded by the media engine: the same frames, at a third of the CPU */
+const DECODE = MAC ? ['-hwaccel', 'videotoolbox'] : []
+/** every shot's frames tagged alike: no join converts one shot to match another, and the joined pieces share one header */
+const TAGS = 'setparams=range=pc:color_primaries=unknown:color_trc=unknown:colorspace=unknown'
+/** a footage's frames made full range BT.601, the matrix of the cards and stills */
+const FULL_601 = 'out_range=pc:out_color_matrix=bt601:flags=bicubic+accurate_rnd+full_chroma_int'
+/** the width of a shot's frame on the contact strip */
+export const THUMB_W = 480
+
+/** the frame of each shot the contact strip shows: its middle */
+const middles = (t: Pick<Trailer, 'shots' | 'fps'>): number[] => {
+    const st = starts(t)
+    return t.shots.map((s, i) => frameAt(st[i]! + s.length / 2, t.fps))
+}
+
+/** each shake's swing at shot time t: its strength, easing out over its span */
+const swing = (s: Shot, H: number): string =>
+    s.shakes.map((x) => `${n3((H / 60) * x.strength)}*if(between(t,${n3(x.at)},${n3(x.at + x.for)}),pow(1-(t-${n3(x.at)})/${n3(x.for)},2),0)`).join('+')
+
+/** the shakes: the frame moved by a jitter of two sines a side, the edge it uncovers mirrored from the film's own */
+function shakeF(s: Shot, W: number, H: number): string {
+    if (s.shakes.length === 0) return ''
+    const m = 2 * Math.ceil((Math.max(...s.shakes.map((x) => (H / 60) * x.strength)) + 1) / 2)
+    const A = `(${swing(s, H)})`
+    const jx = `(sin(t*113)+0.5*sin(t*71+1))/1.5`
+    const jy = `(cos(t*97)+0.5*sin(t*53+2))/1.5`
+    return `,pad=${W + 2 * m}:${H + 2 * m}:${m}:${m},fillborders=left=${m}:right=${m}:top=${m}:bottom=${m}:mode=mirror,crop=${W}:${H}:x='${m}+${A}*${jx}':y='${m}+${A}*${jy}'`
+}
+
+/** the flashes: every pixel eased toward white, full at the flash, gone at its end */
+function flashF(s: Shot): string {
+    return s.flashes
+        .map((x) => {
+            const k = `pow(1-(T-${n3(x.at)})/${n3(x.for)},2)`
+            const en = `between(t,${n3(x.at)},${n3(x.at + x.for)})`
+            return `,geq=lum='lum(X,Y)+(255-lum(X,Y))*${k}':cb='cb(X,Y)+(128-cb(X,Y))*${k}':cr='cr(X,Y)+(128-cr(X,Y))*${k}':enable='${en}'`
+        })
+        .join('')
+}
+
+/** a knocked title flies out of the frame in this long, turning this many radians */
+const KNOCK_S = 0.4
+const KNOCK_TURN = 1.4
+
+/** the ffmpeg arguments that render a piece's frames, no sound, and the row of its shots' middle frames for the
+ *  contact strip (`thumbs`, when a middle falls in it) */
+export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'look'>, p: Piece, out: string, encoder: Encoder = 'draft', thumbs?: string): string[] {
+    const { t } = a
+    const [W, H] = t.size
+    const fps = t.fps
+    const T = total(t)
+    const st = starts(t)
+    const spans = frameSpans(t)
+    // the graph starts at the piece's first frame: the shot before a section draws only what its cut overlaps
+    const base = p.from
+    const inputs: string[] = []
+    const graph: string[] = []
+    let n = 0
+    const input = (...args: string[]): number => {
+        inputs.push(...args)
+        return n++
+    }
+
+    // the shots, each exactly its frames in the piece, on a time base of one frame. A shot's own clock (its push, its
+    // shakes, its flashes) runs from its own first frame, whatever the piece leaves out of it
+    const count: number[] = []
+    for (let i = p.chain; i < p.end; i++) {
+        const s = t.shots[i]!
+        const src = a.sources[i]!
+        const len = s.length
+        const skip = Math.max(0, base - spans[i]!.a)
+        const frames = Math.min(spans[i]!.b, p.to) - spans[i]!.a - skip
+        count[i] = frames
+        const push = s.push && s.push > 1 ? s.push : null
+        const pushF = push
+            ? `,scale=${W * 2}:${H * 2},zoompan=z='1+${n3(push - 1)}*(on+${skip})/${Math.round(len * fps)}':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=1:s=${W}x${H}:fps=${fps}`
+            : ''
+        const [ax, ay] = s.frameAt ?? [0.5, 0.5]
+        const cropF = s.frame && s.frame > 1 ? `crop=w='2*trunc(iw/${n3(s.frame)}/2)':h='2*trunc(ih/${n3(s.frame)}/2)':x='min(max(iw*${n3(ax)}-ow/2,0),iw-ow)':y='min(max(ih*${n3(ay)}-oh/2,0),ih-oh)'` : null
+        const frameF = cropF ? `,${cropF},scale=${W}:${H}` : ''
+        const tail = `,trim=end_frame=${frames},settb=1/${fps},setpts=N+${skip}${shakeF(s, W, H)},setsar=1,format=yuv420p${s.lift ? `,eq=gamma=${n3(s.lift)}` : ''}${flashF(s)},${TAGS},setpts=N[s${i}]`
+        if ('image' in src) {
+            // read at the cut's rate: a still read at the demuxer's 25 fps breaks the xfade of a cut into it
+            const k = input('-framerate', String(fps), '-i', src.image)
+            graph.push(`[${k}:v]scale=${W}:${H}:force_original_aspect_ratio=increase:out_range=pc,crop=${W}:${H},setsar=1${frameF},loop=loop=${frames - 1}:size=1:start=0,setpts=N/${fps}/TB${pushF}${tail}`)
+        } else {
+            const avail = Math.max(0, src.seconds - s.from)
+            // seeking at the input decodes only what the shot shows of a long footage
+            const k = input(...DECODE, '-ss', n3(s.from), '-t', n3(Math.min(avail, len) + 0.1), '-i', src.footage)
+            graph.push(
+                `[${k}:v]trim=duration=${n3(Math.min(avail, len))},setpts=PTS-STARTPTS,fps=${fps}${skip > 0 ? `,trim=start_frame=${skip}` : ''},` +
+                    `${cropF ? `${cropF},` : ''}scale=${W}:${H}:force_original_aspect_ratio=increase:${FULL_601},crop=${W}:${H},setsar=1,` +
+                    `tpad=stop_mode=clone:stop_duration=${n3(len)}${pushF}${tail}`,
+            )
+        }
+    }
+
+    // the cuts: only the frames both shots hold go through xfade, then every part joins in one concat, so a piece draws
+    // its frames as the whole cut would
+    const both = (i: number): number => (i > p.chain && t.shots[i - 1]!.cut.kind !== 'hard' ? Math.max(0, spans[i - 1]!.b - spans[i]!.a) : 0)
+    const parts: string[] = []
+    for (let i = p.chain; i < p.end; i++) {
+        const [head, tail] = [both(i), i + 1 < p.end ? both(i + 1) : 0]
+        const cuts = (
+            [
+                ['h', 0, head],
+                ['b', head, count[i]! - tail],
+                ['e', count[i]! - tail, count[i]!],
+            ] as const
+        ).filter(([, from, to]) => to > from)
+        graph.push(`[s${i}]split=${cuts.length}${cuts.map(([k]) => `[${k}${i}x]`).join('')};${cuts.map(([k, from, to]) => `[${k}${i}x]trim=start_frame=${from}:end_frame=${to},setpts=N[${k}${i}]`).join(';')}`)
+        if (head > 0) {
+            const kind = t.shots[i - 1]!.cut.kind as Exclude<CutKind, 'hard'>
+            const d = head / fps
+            const edge = SEAM_EDGE[kind]
+            if (edge === undefined) graph.push(`[e${i - 1}][h${i}]xfade=transition=${XFADE[kind]}:duration=${n3(d)}:offset=0,format=yuv420p[j${i}]`)
+            else {
+                // a wipe's seam rides its edge: a soft shadow of the look's edge, then a line of its light
+                const across = edge.axis === 'x'
+                const pos = `${across ? W : H}*${edge.from ? `(1-t/${n3(d)})` : `t/${n3(d)}`}`
+                const bar = (c: string, w: number, k: string): string => `color=c=${c}:s=${across ? `${w}x${H}` : `${W}x${w}`}:r=${fps}:d=${n3(d + 1 / fps)},format=rgba[${k}${i}]`
+                const at = (w: number): string => (across ? `x='${pos}-${w / 2}':y=0` : `x=0:y='${pos}-${w / 2}'`)
+                const [sw, lw] = [Math.round(H / 64), Math.max(4, Math.round(H / 300))]
+                graph.push(
+                    `[e${i - 1}][h${i}]xfade=transition=${XFADE[kind]}:duration=${n3(d)}:offset=0[jw${i}]`,
+                    bar(`${ff(a.look.edge)}@0.35`, sw, 'ws'),
+                    bar(ff(a.look.light), lw, 'wl'),
+                    `[jw${i}][ws${i}]overlay=${at(sw)}:eval=frame:shortest=1[jv${i}]`,
+                    `[jv${i}][wl${i}]overlay=${at(lw)}:eval=frame:shortest=1,format=yuv420p[j${i}]`,
+                )
+            }
+            parts.push(`[j${i}]`)
+        }
+        if (cuts.some(([k]) => k === 'b')) parts.push(`[b${i}]`)
+    }
+    let cur = 'chain'
+    graph.push(`${parts.join('')}concat=n=${parts.length}:v=1:a=0,settb=1/${fps},setpts=N[chain]`)
+
+    // the opening and the ending
+    const last = t.shots.at(-1)!.cut
+    const ends: string[] = []
+    if (p.chain === 0 && t.fadeIn > 0) ends.push(`fade=t=in:st=0:d=${n3(t.fadeIn)}`)
+    if (p.end === t.shots.length && last.seconds > 0) ends.push(`fade=t=out:st=${n3(T - last.seconds - base / fps)}:d=${n3(last.seconds)}${last.kind === 'dip-white' ? ':color=white' : ''}`)
+    if (ends.length > 0) {
+        graph.push(`[${cur}]${ends.join(',')}[ends]`)
+        cur = 'ends'
+    }
+
+    // the titles that show in the piece, wherever their shot is: each faded in and out over its own span
+    t.shots.forEach((s, i) => {
+        s.titles.forEach((ti, j) => {
+            const at = st[i]! + ti.at
+            const dur = Math.min(ti.for ?? s.length - ti.at, ti.knock === undefined ? Infinity : ti.knock - ti.at + KNOCK_S)
+            const [ta, te] = [frameAt(at, fps), Math.floor((at + dur) * fps + 1e-6)]
+            if (te < p.from || ta >= p.to || te < ta) return
+            // a tagline and the logo breathe in slowly; the plates pop
+            const f = Math.min(ti.style === 'line' || ti.style === 'logo' ? 0.7 : 0.25, dur / 3)
+            const img = a.titles[i]![j]!
+            const k = input('-i', img.file)
+            const [from, to] = [Math.max(ta, base), Math.min(te, p.to - 1)]
+            const kn = ti.knock === undefined ? null : ti.knock - ti.at
+            const hyp = kn === null ? 0 : Math.ceil(Math.hypot(img.w, img.h))
+            const tip = kn === null ? '' : `rotate=a='-${KNOCK_TURN}*pow(max(0,t-${n3(kn)})/${KNOCK_S},2)':ow=${hyp}:oh=${hyp}:c=none,`
+            graph.push(
+                `[${k}:v]format=rgba,loop=loop=${to - ta}:size=1:start=0,setpts=N/${fps}/TB,${tip}fade=t=in:st=0:d=${n3(f)}:alpha=1,${kn === null ? `fade=t=out:st=${n3(dur - f)}:d=${n3(f)}:alpha=1,` : ''}` +
+                    `trim=start_frame=${from - ta},settb=1/${fps},setpts=N+${from - base}[t${i}_${j}]`,
+            )
+            // it rises into place over its fade in, eased, by a fortieth of the frame; counted in frames
+            const rise = `${n3(H / 40)}*pow(max(0,1-(n-${n3(at * fps - base)})/${n3(Math.max(f, 0.05) * fps)}),2)`
+            const on = `between(t,${n3((ta - base - 0.5) / fps)},${n3((te - base + 0.5) / fps)})`
+            const flown = kn === null ? '' : `pow(max(0,n-${n3((at + kn) * fps - base)})/${n3(KNOCK_S * fps)},2)`
+            const x = kn === null ? `${img.x}` : `${img.x - (hyp - img.w) / 2}-${n3(W * 1.1)}*${flown}`
+            const y = kn === null ? `${img.y}+${rise}` : `${img.y - (hyp - img.h) / 2}+${rise}-${n3(H * 0.45)}*${flown}`
+            graph.push(`[${cur}][t${i}_${j}]overlay=x='${x}':y='${y}':eof_action=pass:enable='${on}'[v${i}_${j}]`)
+            cur = `v${i}_${j}`
+        })
+    })
+    graph.push(`[${cur}]trim=end_frame=${p.to - base},format=yuv420p,${TAGS}[vout]`)
+
+    // the contact strip's row: the middle frame of each shot whose middle is in the piece, side by side
+    const mids = middles(t).filter((m) => m >= p.from && m < p.to)
+    const row = thumbs !== undefined && mids.length > 0
+    if (row) {
+        graph[graph.length - 1] = graph.at(-1)!.replace('[vout]', ',split[vout][all]')
+        graph.push(`[all]select='${mids.map((m) => `eq(n,${m - base})`).join('+')}',scale=${THUMB_W}:-2,tile=${mids.length}x1[row]`)
+    }
+    return [
+        '-hide_banner', '-loglevel', 'error', '-y',
+        ...inputs,
+        '-filter_complex', graph.join(';\n'),
+        '-map', '[vout]', '-r', String(fps),
+        ...ENCODERS[encoder],
+        out,
+        ...(row ? ['-map', '[row]', '-frames:v', '1', '-update', '1', thumbs] : []),
+    ]
+}
+
+/** the ffmpeg arguments that mix the cut's sound: the music trimmed, faded and ducked under each voice line, the sfx
+ *  and the voices on their times, the mix through a limiter */
+export function mixArgs(a: Pick<StitchInput, 't' | 'music' | 'sfx' | 'voices'>, out: string): string[] {
+    const { t } = a
+    const T = total(t)
+    const st = starts(t)
+    const inputs: string[] = []
+    const graph: string[] = []
+    let n = 0
+    const input = (...args: string[]): number => {
+        inputs.push(...args)
+        return n++
+    }
+    const mix: string[] = []
+    const windows: [number, number][] = []
+    const hits: [number, number][] = []
+    const voiceLabels: string[] = []
+    t.shots.forEach((s, i) => {
+        s.sfx.forEach((x, j) => {
+            const src = a.sfx[i]![j]!
+            const k = input('-i', src.file)
+            const ms = Math.round((st[i]! + x.at) * 1000)
+            if (t.duckSfx !== null) hits.push([st[i]! + x.at, st[i]! + x.at + src.seconds])
+            graph.push(`[${k}:a]aresample=48000,aformat=channel_layouts=stereo,adelay=${ms}:all=1,volume=${n3(x.volume)}[x${i}_${j}]`)
+            mix.push(`[x${i}_${j}]`)
+        })
+        s.voices.forEach((v, j) => {
+            const src = a.voices[i]![j]!
+            const k = input('-i', src.file)
+            const at = st[i]! + v.at
+            windows.push([at, at + src.seconds])
+            graph.push(`[${k}:a]aresample=48000,aformat=channel_layouts=stereo,adelay=${Math.round(at * 1000)}:all=1,volume=${n3(v.volume)}[o${i}_${j}]`)
+            voiceLabels.push(`[o${i}_${j}]`)
+        })
+    })
+    mix.push(...voiceLabels)
+    // the duck: the gain eases to `duck` dB 0.15 s before each voice line and back 0.15 s after it
+    const r = 0.15
+    const g = 10 ** (t.duck / 20)
+    const env = windows.map(([s, e]) => `clip((t-${n3(s - r)})/${r},0,1)*clip((${n3(e + r)}-t)/${r},0,1)`)
+    // and, with `duck … sfx`, to that drop under each sfx, eased in and out over 0.06 s
+    const rs = 0.06
+    const envS = hits.map(([s, e]) => `clip((t-${n3(s - rs)})/${rs},0,1)*clip((${n3(e + rs)}-t)/${rs},0,1)`)
+    const gains = [
+        ...(env.length > 0 ? [`(1-${n3(1 - g)}*min(1,${env.join('+')}))`] : []),
+        ...(envS.length > 0 ? [`(1-${n3(1 - 10 ** ((t.duckSfx ?? 0) / 20))}*min(1,${envS.join('+')}))`] : []),
+    ]
+    const duck = gains.length > 0 ? `,volume='${gains.join('*')}':eval=frame` : ''
+    musicCues(t).forEach(({ cue: m, at, end }, i, cues) => {
+        const dur = end - at
+        const k = input('-ss', n3(m.from), '-t', n3(dur), '-i', a.music[i]!)
+        const last = i === cues.length - 1
+        const fadeOut = last ? m.fadeOut : (cues[i + 1]?.cue.fadeIn ?? 0) || 0.05
+        const fades = [m.fadeIn > 0 ? `afade=t=in:st=0:d=${n3(m.fadeIn)}` : '', fadeOut > 0 ? `afade=t=out:st=${n3(Math.max(0, dur - fadeOut))}:d=${n3(Math.min(fadeOut, dur))}` : ''].filter(Boolean)
+        graph.push(`[${k}:a]asetpts=PTS-STARTPTS,aresample=48000,aformat=channel_layouts=stereo${fades.length ? `,${fades.join(',')}` : ''},volume=${n3(m.volume)},adelay=${Math.round(at * 1000)}:all=1${duck}[mus${i}]`)
+        mix.unshift(`[mus${i}]`)
+    })
+    const silence = input('-f', 'lavfi', '-t', n3(T), '-i', 'anullsrc=r=48000:cl=stereo')
+    mix.push(`[${silence}:a]`)
+    graph.push(`${mix.join('')}amix=inputs=${mix.length}:normalize=0:duration=longest,atrim=duration=${n3(T)},alimiter=limit=0.95[aout]`)
+    return ['-hide_banner', '-loglevel', 'error', '-y', ...inputs, '-filter_complex', graph.join(';\n'), '-map', '[aout]', '-c:a', 'aac', '-b:a', '192k', '-t', n3(T), out]
+}

package/src/trailer/load-unit.ts

@@ -0,0 +1,14 @@
+// the repo's trailer unit, found by the walk every unit file takes (core/discover-checks.ts)
+import { importFresh, repoUnitFiles } from '../core/discover-checks.ts'
+import type { TrailerUnit } from './adapter.ts'
+
+/** the repo's trailer unit, or null; two of them is an error naming both files */
+export async function loadTrailerUnit(root: string): Promise<TrailerUnit | null> {
+    const found: { file: string; unit: TrailerUnit }[] = []
+    for (const f of repoUnitFiles(root)) {
+        const d = (await importFresh(f)) as { kind?: unknown } | undefined
+        if (d?.kind === 'trailer') found.push({ file: f, unit: d as TrailerUnit })
+    }
+    if (found.length > 1) throw new Error(`two trailer units: ${found.map((x) => x.file).join(' and ')}; keep one`)
+    return found[0]?.unit ?? null
+}

package/src/trailer/look.ts

@@ -0,0 +1,110 @@
+// the look every trailer wears, drawn from the repo's brand (`.shipkit/identity/brand.ts`): the card's ground, the
+// title colours, the face and the logo. A repo changes its look in that data, never in code; a value it leaves out is
+// derived from its palette, and a repo with no brand gets the house default. Pure
+export interface TrailerLookInput {
+    /** the card's ground, middle then edge (default: the palette's bg, then a darker bg) */
+    ground?: [string, string]
+    /** words over footage (default: the palette's ink when it is light, else white) */
+    light?: string
+    /** the dark edge under words over footage (default: the ground's edge) */
+    edge?: string
+    /** the key colour: the caption's dot, a `line` title's `*word*`, the corner chip (default: the palette's accent) */
+    accent?: string
+    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) */
+    plate?: { fill?: string; line?: string; ink?: string }
+    /** the corner chip (default: the accent, ink of the palette's bg) */
+    chip?: { fill?: string; ink?: string }
+    /** the face: a font file (repo relative, .ttf .otf .woff2) or a family the machine has, and its heavy weight */
+    font?: { file?: string; family?: string; weight?: number }
+    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present) */
+    logo?: string
+    /** the vertical short's look (a `vertical` cut), each part `false` to leave it out (vertical.ts) */
+    vertical?: VerticalLookInput
+}
+
+/** what a vertical short wears, image paths repo relative; its colours and face are the look's */
+export interface VerticalLookInput {
+    /** over every frame of the short, under the platforms' top tabs: a wordmark image, else the logo and the name; a
+     *  tag pill under it */
+    lockup?: { image?: string; name?: string; tag?: string } | false
+    /** a bottom corner of the short and its outro: an image (default: the logo) and a word beside it (default: the
+     *  name, when there is no image) */
+    watermark?: { image?: string; text?: string; corner?: 'left' | 'right' } | false
+    /** the card the short ends on: an image that hops in (default: the logo), the name, lines with `*word*` in the
+     *  accent (default: the tagline), its length in seconds */
+    end?: { image?: string; name?: string; lines?: string[]; seconds?: number } | false
+}
+
+export interface TrailerLook {
+    ground: [string, string]
+    light: string
+    edge: string
+    accent: string
+    plate: { fill: string; line: string; ink: string }
+    chip: { fill: string; ink: string }
+    font: { file: string | null; family: string; weight: number }
+    logo: string | null
+}
+
+export interface BrandLike {
+    name: string
+    tagline?: string
+    palette: { bg: string; accent: string; ink: string }
+    trailer?: TrailerLookInput
+}
+
+/** named faces first: a generic sans-serif can resolve to one with no Latin-1 accents (the og card uses it too) */
+export const HOUSE_FAMILIES = 'Helvetica, Arial, "DejaVu Sans", "Liberation Sans", "Noto Sans", sans-serif'
+
+/** the palette a repo with no brand wears: a deep ink ground, warm accent, cream words */
+export const HOUSE_PALETTE = { bg: '#1d1b2e', accent: '#ffb547', ink: '#fbf5ea' } as const
+
+/** `#rgb` or `#rrggbb` as [r, g, b], 0 to 255; null for any other colour text */
+export function rgbOf(c: string): [number, number, number] | null {
+    const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim())
+    if (!m) return null
+    const h = m[1]!.length === 3 ? [...m[1]!].map((x) => x + x).join('') : m[1]!
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+const hex = (rgb: readonly number[]): string => `#${rgb.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')).join('')}`
+
+/** the colour mixed toward black by `k`, 0 to 1; a colour that is not hex stays as it is */
+export function darker(c: string, k: number): string {
+    const rgb = rgbOf(c)
+    return rgb ? hex(rgb.map((v) => v * (1 - k))) : c
+}
+
+/** relative luminance, 0 dark to 1 light; 0.5 for a colour that is not hex */
+export function luminance(c: string): number {
+    const rgb = rgbOf(c)
+    if (!rgb) return 0.5
+    const [r, g, b] = rgb.map((v) => {
+        const s = v / 255
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+    }) as [number, number, number]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** the colour with an alpha, as canvas reads it; a colour that is not hex stays as it is */
+export function alpha(c: string, a: number): string {
+    const rgb = rgbOf(c)
+    return rgb ? `rgba(${rgb.join(',')},${a})` : c
+}
+
+/** the look of a brand, every value its own or derived from its palette; `webLogo` the web root's logo.png when present */
+export function lookOf(brand: BrandLike | null, webLogo: string | null = null): TrailerLook {
+    const p = brand?.palette ?? HOUSE_PALETTE
+    const i = brand?.trailer ?? {}
+    const ground: [string, string] = i.ground ?? [p.bg, darker(p.bg, luminance(p.bg) > 0.5 ? 0.25 : 0.45)]
+    return {
+        ground,
+        light: i.light ?? (luminance(p.ink) > 0.45 ? p.ink : '#ffffff'),
+        edge: i.edge ?? (luminance(ground[1]) < 0.2 ? ground[1] : darker(p.bg, 0.8)),
+        accent: i.accent ?? p.accent,
+        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink },
+        chip: { fill: i.chip?.fill ?? p.accent, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff') },
+        font: { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 },
+        logo: i.logo ?? webLogo,
+    }
+}

package/src/trailer/plan.ts

@@ -0,0 +1,133 @@
+// what a build does, as data: each shot's take and its key, which takes film, the pieces the stitch renders. Pure: the
+// io (stamps on disk, the world's git stamp, ffmpeg) lives in footage.ts and stitch.ts, which read these answers
+import type { Film, Shot, Trailer } from './grammar.ts'
+import { starts } from './grammar.ts'
+
+/** bump when the core films differently from the same line: every core take films again */
+export const FILM_VERSION = 1
+
+/**
+ * the key of a take: what films, never how the cut uses it. The formula of pkm-multi's `footageKey`, verbatim, so a
+ * take filmed there under the same version, recipe, size, fps and seconds keeps its file
+ */
+export function footageKey(version: number | readonly number[], recipe: unknown, size: readonly [number, number], fps: number, seconds: number | null): string {
+    return new Bun.CryptoHasher('sha1').update(JSON.stringify([version, recipe, size, fps, seconds])).digest('hex').slice(0, 12)
+}
+
+/** a film that writes a take of its own: the others are read where they lie (a clip, an image) or drawn (a card) */
+export type TakeFilm = Extract<Film, { kind: 'run' | 'cli' | 'url' }>
+export const isTake = (f: Film | null): f is TakeFilm => f?.kind === 'run' || f?.kind === 'cli' || f?.kind === 'url'
+
+/** the take is one picture, held for the shot */
+export const takeIsStill = (f: TakeFilm): boolean => (f.kind === 'cli' ? f.output === 'still' : f.still === true)
+
+/** the seconds a clip take films: what the shot shows, rounded up to 2 s, so a small edit never films again; a still: none */
+export function takeSeconds(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm): number | null {
+    return takeIsStill(f) ? null : Math.ceil((s.from + s.length) / 2) * 2
+}
+
+/** the film line as its key reads it: the line it sits on is never part of what films */
+export function recipeOf(f: TakeFilm): Omit<TakeFilm, 'line'> {
+    const { line: _line, ...recipe } = f
+    return recipe
+}
+
+/** the take's file name, by its key alone: shots on one film line, in one cut or in several, share one file */
+export function takeName(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, t: Pick<Trailer, 'size' | 'fps'>): string {
+    return `${footageKey(FILM_VERSION, recipeOf(f), t.size, t.fps, takeSeconds(s, f))}.${takeIsStill(f) ? 'png' : 'mp4'}`
+}
+
+/** the world a take was filmed on, beside it */
+export interface Stamp {
+    /** the repo's state when it filmed (footage.ts worldStamp) */
+    world: string
+    filmedAt: string
+    /** the take's own length, seconds; 0 for a still */
+    seconds: number
+    /** what the film said of it, its first line */
+    note: string
+}
+
+export const fresh = (stamp: Stamp, world: string): boolean => stamp.world === world
+
+/** a take as a build sees it: its shot, its file, its stamp when it was filmed */
+export interface Take {
+    shot: Shot
+    film: TakeFilm
+    file: string
+    stamp: Stamp | null
+}
+
+/** `--refilm`: every stale take, or the takes of the named shots */
+export type Refilm = 'stale' | ReadonlySet<string> | null
+
+/** the takes to film, each group sharing one file and filmed once by its first shot: a missing take, a stale one under
+ *  `--refilm`, or one whose shot `--refilm` names */
+export function takesToFilm(takes: readonly Take[], world: string, refilm: Refilm, only?: ReadonlySet<string>): Take[][] {
+    const groups = new Map<string, Take[]>()
+    for (const tk of takes) {
+        if (only !== undefined && !only.has(tk.shot.name)) continue
+        const g = groups.get(tk.file)
+        if (g) g.push(tk)
+        else groups.set(tk.file, [tk])
+    }
+    return [...groups.values()].filter((g) => {
+        const first = g[0]!
+        if (first.stamp === null) return true
+        if (refilm === 'stale') return !fresh(first.stamp, world)
+        return refilm instanceof Set && g.some((tk) => refilm.has(tk.shot.name))
+    })
+}
+
+/** the argv a project CLI film runs: its words, then the file and, for a clip, its seconds */
+export function cliArgv(cli: readonly string[], f: Extract<Film, { kind: 'cli' }>, out: string, seconds: number | null): string[] {
+    return [...cli, ...f.argv, '--out', out, ...(seconds === null ? [] : ['--seconds', String(seconds)])]
+}
+
+/** a `film run` command with its marks filled: `{out}`, `{seconds}`, `{w}`, `{h}`, `{fps}` */
+export function runCommand(f: Extract<Film, { kind: 'run' }>, o: { out: string; seconds: number | null; size: readonly [number, number]; fps: number }): string {
+    const q = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`
+    return f.cmd
+        .replaceAll('{out}', q(o.out))
+        .replaceAll('{seconds}', String(o.seconds ?? 0))
+        .replaceAll('{w}', String(o.size[0]))
+        .replaceAll('{h}', String(o.size[1]))
+        .replaceAll('{fps}', String(o.fps))
+}
+
+/** the first frame at or after a time: a shot, a cut or a title starts on it */
+export const frameAt = (seconds: number, fps: number): number => Math.ceil(seconds * fps - 1e-6) || 0
+
+/** each shot's frames on the cut, [a, b): a cut's frames are those both shots hold; a hard cut's shots share none */
+export function frameSpans(t: Pick<Trailer, 'shots' | 'fps'>): { a: number; b: number }[] {
+    const st = starts(t)
+    return t.shots.map((s, i) => ({ a: frameAt(st[i]!, t.fps), b: frameAt(st[i]! + s.length, t.fps) }))
+}
+
+/** a piece of the cut rendered alone: a section, or the shots before the first section (`start`) */
+export interface Piece {
+    name: string
+    /** its shots, [first, end) */
+    first: number
+    end: number
+    /** the first shot its graph draws: the shot before `first` when the cut into the section overlaps it */
+    chain: number
+    /** its frames on the cut, [from, to) */
+    from: number
+    to: number
+}
+
+export const START_PIECE = 'start'
+
+/** the cut split at its sections; the pieces' frames tile the cut */
+export function pieces(t: Pick<Trailer, 'shots' | 'fps'>): Piece[] {
+    const spans = frameSpans(t)
+    const opens = t.shots.flatMap((s, i) => (i > 0 && s.section ? [i] : []))
+    const firsts = [0, ...opens]
+    return firsts.map((first, k) => {
+        const end = firsts[k + 1] ?? t.shots.length
+        const from = spans[first]!.a
+        const chain = first > 0 && spans[first - 1]!.b > from ? first - 1 : first
+        return { name: k === 0 ? (t.shots[0]?.section?.name ?? START_PIECE) : t.shots[first]!.section!.name, first, end, chain, from, to: end < t.shots.length ? spans[end]!.a : spans.at(-1)!.b }
+    })
+}