rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/graph.ts

@@ -0,0 +1,508 @@
+// 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 { GROW_S, 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',
+}
+
+/** a grid's or a split's cell: a shot's or a footage block's take, from its `from`, cropped by its `frame` */
+export interface GridCell {
+    footage: string
+    seconds: number
+    from: number
+    frame: number | null
+    /** where a grid's cell crops, each 0 to 1 across and down its take; absent, its middle */
+    at?: readonly [number, number]
+}
+
+/** a split's drawn pieces: each pane's shape (white on black) and the seams laid over them (stitch.ts splitMasks) */
+export interface SplitMasks {
+    panes: string[]
+    seams: string
+}
+
+/** what each shot is drawn from: a video and its length, a still image held for the shot, or a grid or a split of
+ *  other takes laid under its frame (stitch.ts gridMask, splitMasks) */
+export type Source =
+    | { footage: string; seconds: number }
+    | { image: string }
+    | { grid: GridCell[]; pop: number; grow?: [number, number]; mask: string }
+    | { split: GridCell[]; angle: number; slide: number; masks: SplitMasks }
+
+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()
+const even = (x: number): number => 2 * Math.round(x / 2)
+
+/** the grid's margin round the cells and the gap between them, and the corners' radius, in frame heights */
+export const GRID_MARGIN = 0.03
+export const GRID_GAP = 0.014
+export const GRID_RADIUS = 0.022
+/** a cell's pop: its length, seconds, and the overshoot of its ease */
+const POP_S = 0.22
+const POP_BACK = 1.70158
+/** a split's pane j slides in this long after pane j - 1 */
+const SPLIT_STAGGER = 0.08
+/** how much bigger a pane's take is drawn than the frame, so its middle can move to the pane's middle */
+export const SPLIT_ZOOM = 1.3
+/** a growing grid is laid this many times the frame's size, so the one cell it opens on fills the frame sharp */
+export const GROW_RES = 3
+
+/** where each of `n` cells lies on the frame: 2 by 2 up to four, else 3 by 3, row by row; even pixels for the encoder */
+export function gridLayout(n: number, W: number, H: number): { x: number; y: number; w: number; h: number }[] {
+    const cols = n <= 1 ? 1 : n <= 4 ? 2 : 3
+    const rows = Math.max(1, Math.ceil(n / cols))
+    const m = H * GRID_MARGIN
+    const g = H * GRID_GAP
+    const cw = (W - 2 * m - (cols - 1) * g) / cols
+    const ch = (H - 2 * m - (rows - 1) * g) / rows
+    return Array.from({ length: n }, (_, i) => {
+        const [c, r] = [i % cols, Math.floor(i / cols)]
+        const x = even(m + c * (cw + g))
+        const y = even(m + r * (ch + g))
+        return { x, y, w: even(m + c * (cw + g) + cw) - x, h: even(m + r * (ch + g) + ch) - y }
+    })
+}
+
+/** a split's pane j of `n`: the frame cut by seams through (W i / n, H / 2), each leaning `angle` degrees from
+ *  upright, its top toward the right (two panes at 56: top left and bottom right). Its outline (it may run past the
+ *  frame, which clips it), and its middle, where its take centres */
+export function splitPane(n: number, j: number, angle: number, W: number, H: number): { points: [number, number][]; cx: number; cy: number } {
+    const t = Math.tan((angle * Math.PI) / 180)
+    const far = W + H * (1 + t)
+    const seam = (i: number, y: number): number => (i <= 0 ? -far : i >= n ? W + far : (W * i) / n + (H / 2 - y) * t)
+    const points: [number, number][] = [
+        [seam(j, 0), 0],
+        [seam(j + 1, 0), 0],
+        [seam(j + 1, H), H],
+        [seam(j, H), H],
+    ]
+    // its middle: the mean of a fine grid's points inside it
+    let [sx, sy, k] = [0, 0, 0]
+    for (let gy = 0.5; gy < 36; gy++)
+        for (let gx = 0.5; gx < 64; gx++) {
+            const [x, y] = [(gx * W) / 64, (gy * H) / 36]
+            if (x >= seam(j, y) && x < seam(j + 1, y)) [sx, sy, k] = [sx + x, sy + y, k + 1]
+        }
+    return { points, cx: k ? sx / k : W / 2, cy: k ? sy / k : H / 2 }
+}
+
+/** the grow's look rectangle at time t, in the big grid's pixels: cell 0, then the 2 by 2 block, then the whole */
+function growZoom(cells: { x: number; y: number; w: number; h: number }[], grow: [number, number], W: number, H: number): { z: string; x: string; y: string } {
+    const c0 = cells[0]!
+    const c4 = cells[4]!
+    const pad = cells[1]!.x - (c0.x + c0.w)
+    const fit = (x0: number, y0: number, x1: number, y1: number): [number, number, number] => {
+        // the frame's aspect round the rectangle, a little margin, centred on it
+        const w = Math.max(x1 - x0 + pad, ((y1 - y0 + pad) * W) / H)
+        return [(x0 + x1) / 2, (y0 + y1) / 2, w]
+    }
+    const one = fit(c0.x, c0.y, c0.x + c0.w, c0.y + c0.h)
+    const four = fit(c0.x, c0.y, c4.x + c4.w, c4.y + c4.h)
+    const all: [number, number, number] = [W / 2, H / 2, W]
+    // each move eases in and out over GROW_S, ending on its settle
+    const ease = (end: number): string => `(1-cos(PI*clip((it-${n3(end - GROW_S)})/${GROW_S},0,1)))/2`
+    const [a, b] = [ease(grow[0]), ease(grow[1])]
+    const lerp = (k: 0 | 1 | 2): string => `(${n3(one[k])}+(${n3(four[k] - one[k])})*${a}+(${n3(all[k] - four[k])})*${b})`
+    const w = lerp(2)
+    return { z: `${W}/${w}`, x: `${lerp(0)}-${w}/2`, y: `${lerp(1)}-${w}*${n3(H / W)}/2` }
+}
+/** 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 ('grid' in src) {
+            // the cells, each its take from its own `from`, cropped to fill its place and held on its last frame, laid on
+            // the slots' ground under the grid's frame; cell j pops in at j times `pop`, its take starting then. Then the
+            // shot's own frame, push and shakes as any footage
+            const G = src.grow ? GROW_RES : 1
+            const cells = gridLayout(src.grid.length, W * G, H * G)
+            const ground = input('-f', 'lavfi', '-i', `color=c=${ff(a.look.edge)}:s=${W * G}x${H * G}:r=${fps}:d=${n3(len + 0.1)}`)
+            graph.push(`[${ground}:v]format=yuv420p[g${i}_0]`)
+            src.grid.forEach((c, j) => {
+                const at = cells[j]!
+                const T0 = Math.min(len, j * src.pop)
+                const run = len - T0
+                const avail = Math.max(0, c.seconds - c.from)
+                const k = input(...DECODE, '-ss', n3(c.from), '-t', n3(Math.min(avail, run) + 0.1), '-i', c.footage)
+                const crop = !c.frame || c.frame <= 1 ? '' : c.at
+                    ? `crop=w='2*trunc(iw/${n3(c.frame)}/2)':h='2*trunc(ih/${n3(c.frame)}/2)':x='min(max(iw*${n3(c.at[0])}-ow/2,0),iw-ow)':y='min(max(ih*${n3(c.at[1])}-oh/2,0),ih-oh)',`
+                    : `crop=iw/${n3(c.frame)}:ih/${n3(c.frame)},`
+                const fit = `${crop}scale=${at.w}:${at.h}:force_original_aspect_ratio=increase:${FULL_601},crop=${at.w}:${at.h},setsar=1`
+                if (src.pop <= 0) {
+                    graph.push(`[${k}:v]trim=duration=${n3(Math.min(avail, run))},setpts=PTS-STARTPTS,fps=${fps},${fit},format=yuv420p,tpad=stop_mode=clone:stop_duration=${n3(len)}[c${i}_${j}]`)
+                    graph.push(`[g${i}_${j}][c${i}_${j}]overlay=x=${at.x}:y=${at.y}:eof_action=repeat[g${i}_${j + 1}]`)
+                    return
+                }
+                // the pop: grown from 55 % to a hair past whole and back (an ease out with overshoot), faded in
+                const x = `clip((t-${n3(T0)})/${POP_S},0,1)`
+                const K = `(0.55+0.45*(1+${n3(POP_BACK + 1)}*pow(${x}-1,3)+${POP_BACK}*pow(${x}-1,2)))`
+                graph.push(
+                    `[${k}:v]trim=duration=${n3(Math.min(avail, run))},setpts=PTS-STARTPTS,fps=${fps},${fit},format=yuva420p,tpad=stop_mode=clone:stop_duration=${n3(run)},setpts=PTS+${n3(T0)}/TB,` +
+                        `fade=t=in:st=${n3(T0)}:d=0.08:alpha=1,scale=w='trunc(${at.w}*${K}/2)*2':h='trunc(${at.h}*${K}/2)*2':eval=frame[c${i}_${j}]`,
+                )
+                graph.push(`[g${i}_${j}][c${i}_${j}]overlay=x='${at.x}+(${at.w}-w)/2':y='${at.y}+(${at.h}-h)/2':eval=frame:format=auto:eof_action=repeat[g${i}_${j + 1}]`)
+            })
+            const m = input('-loop', '1', '-framerate', String(fps), '-t', n3(len + 0.1), '-i', src.mask)
+            // a growing grid: the frame looks at cell 0, eases out to the 2 by 2 block, then to the whole, scaled to the frame
+            const zoom = src.grow ? growZoom(cells, src.grow, W * G, H * G) : null
+            const grow = zoom ? `,zoompan=z='${zoom.z}':x='${zoom.x}':y='${zoom.y}':d=1:s=${W}x${H}:fps=${fps}` : ''
+            graph.push(`[g${i}_${src.grid.length}][${m}:v]overlay=x=0:y=0:format=auto,trim=duration=${n3(len)},setpts=PTS-STARTPTS,fps=${fps}${grow}${skip > 0 ? `,trim=start_frame=${skip}` : ''},setsar=1,format=yuv420p${frameF}${pushF}${tail}`)
+        } else if ('split' in src) {
+            // each pane its take drawn a little bigger and centred on the pane's middle, cut to its shape, sliding in from
+            // its side with pane j a beat after pane j - 1; the seams laid over all; the ground where no pane shows yet
+            const ground = input('-f', 'lavfi', '-i', `color=c=${ff(a.look.edge)}:s=${W}x${H}:r=${fps}:d=${n3(len + 0.1)}`)
+            graph.push(`[${ground}:v]format=yuv420p[p${i}_0]`)
+            const [BW, BH] = [even(W * SPLIT_ZOOM), even(H * SPLIT_ZOOM)]
+            src.split.forEach((c, j) => {
+                const pane = splitPane(src.split.length, j, src.angle, W, H)
+                const ox = Math.round(Math.min(BW - W, Math.max(0, BW / 2 - pane.cx)))
+                const oy = Math.round(Math.min(BH - H, Math.max(0, BH / 2 - pane.cy)))
+                const avail = Math.max(0, c.seconds - c.from)
+                const k = input(...DECODE, '-ss', n3(c.from), '-t', n3(Math.min(avail, len) + 0.1), '-i', c.footage)
+                const m = input('-loop', '1', '-framerate', String(fps), '-t', n3(len + 0.1), '-i', src.masks.panes[j]!)
+                const crop = c.frame && c.frame > 1 ? `crop=iw/${n3(c.frame)}:ih/${n3(c.frame)},` : ''
+                graph.push(
+                    `[${k}:v]trim=duration=${n3(Math.min(avail, len))},setpts=PTS-STARTPTS,fps=${fps},${crop}scale=${BW}:${BH}:force_original_aspect_ratio=increase:${FULL_601},crop=${BW}:${BH},crop=${W}:${H}:${ox}:${oy},setsar=1,format=yuva420p,tpad=stop_mode=clone:stop_duration=${n3(len)}[pf${i}_${j}]`,
+                    `[${m}:v]format=gray,scale=${W}:${H}[pm${i}_${j}]`,
+                    `[pf${i}_${j}][pm${i}_${j}]alphamerge[pa${i}_${j}]`,
+                )
+                // it slides in from the side its middle is on, eased out, from a pane's width away
+                const T0 = j * SPLIT_STAGGER
+                const side = pane.cx < W / 2 - 1 ? -1 : pane.cx > W / 2 + 1 ? 1 : 0
+                const x = src.slide > 0 ? `clip((t-${n3(T0)})/${n3(src.slide)},0,1)` : '1'
+                const ease = `(1-pow(1-${x},3))`
+                const dx = side !== 0 ? `${n3(side * W * 0.7)}*(1-${ease})` : '0'
+                const dy = side === 0 ? `${n3(H * 0.8)}*(1-${ease})` : '0'
+                graph.push(`[p${i}_${j}][pa${i}_${j}]overlay=x='${dx}':y='${dy}':eval=frame:format=auto:eof_action=repeat[p${i}_${j + 1}]`)
+            })
+            const sm = input('-loop', '1', '-framerate', String(fps), '-t', n3(len + 0.1), '-i', src.masks.seams)
+            graph.push(`[p${i}_${src.split.length}][${sm}:v]overlay=x=0:y=0:format=auto,trim=duration=${n3(len)},setpts=PTS-STARTPTS,fps=${fps}${skip > 0 ? `,trim=start_frame=${skip}` : ''},setsar=1,format=yuv420p${frameF}${pushF}${tail}`)
+        } else 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)
+            // a progress step ends the frame before the next one starts: two steps never stand on one frame
+            const handOff = ti.style === 'progress' && ti.step !== undefined && ti.step.i < ti.step.n ? 1 : 0
+            const [ta, te] = [frameAt(at, fps), Math.floor((at + dur) * fps + 1e-6) - handOff]
+            if (te < p.from || ta >= p.to || te < ta) return
+            // a tagline and the logo breathe in slowly; the plates pop; a short's words come quick
+            const short = ti.style === 'short' || ti.style === 'progress'
+            const f = Math.min(ti.style === 'line' || ti.style === 'logo' ? 0.7 : short ? 0.15 : 0.25, dur / 3)
+            // the steps of a progress swap on their beat: the first alone fades in, the last alone fades out
+            const step = ti.style === 'progress' ? ti.step : undefined
+            const fadeIn = step === undefined || step.i === 1
+            const fadeOut = step === undefined || step.i === step.n
+            // a short's caption on the cut's first frame is there whole: frame 0 is the cover the platforms take
+            const cover = ti.style === 'short' && ta === 0
+            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}${cover || !fadeIn ? '' : `fade=t=in:st=0:d=${n3(f)}:alpha=1,`}${fadeOut && 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. A short's
+            // caption slides in from the left instead, eased out over 0.15 s
+            const rise = cover || short ? '0' : `${n3(H / 40)}*pow(max(0,1-(n-${n3(at * fps - base)})/${n3(Math.max(f, 0.05) * fps)}),2)`
+            const slide = cover || ti.style !== 'short' ? '' : `-${n3(H / 32)}*pow(max(0,1-(n-${n3(at * fps - base)})/${n3(0.15 * fps)}),3)`
+            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}${slide}` : `${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 true peak the mix is held under, dBTP */
+export const MIX_TRUE_PEAK = -1
+/** what the limiter aims at below MIX_TRUE_PEAK: the aac encode after it overshoots by a few tenths */
+const LIMIT_MARGIN_DB = 0.5
+/** the limiter runs 4 times oversampled, so it sees the peaks between samples a player's converter makes */
+const OVERSAMPLE = 4
+
+/** 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 sum through a true peak limiter held under MIX_TRUE_PEAK. `trimDb` lowers the
+ *  limited sum before the encode, for a mix whose aac encode still overshoots (stitch.ts) */
+export function mixArgs(a: Pick<StitchInput, 't' | 'music' | 'sfx' | 'voices'>, out: string, trimDb = 0): 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]`)
+    // level=disabled: alimiter's default auto level lifts the output back to 0 dBFS, past the limit
+    const limit = n3(10 ** ((MIX_TRUE_PEAK - LIMIT_MARGIN_DB) / 20))
+    const limiter = `aresample=${48000 * OVERSAMPLE},alimiter=limit=${limit}:attack=1:release=60:level=disabled,aresample=48000${trimDb < 0 ? `,volume=${n3(trimDb)}dB` : ''}`
+    graph.push(`${mix.join('')}amix=inputs=${mix.length}:normalize=0:duration=longest,atrim=duration=${n3(T)},${limiter}[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/holes.ts

@@ -0,0 +1,72 @@
+// the frames of a take where the picture dropped out (wiki build/trailer.md, A take and its world): most of the frame
+// one flat colour while the take's other frames are not. A take that shows it is filmed again once, then refused.
+// Turned on by the trailer unit's `holes`
+import { readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ffmpeg } from './ffmpeg.ts'
+
+/** the size the frames are read at: a flat sky is flat at any size */
+export const HOLE_W = 64
+export const HOLE_H = 36
+/** a frame with a hole is mostly one colour bucket... */
+const FLAT = 0.4
+/** ...well past what the take's own frames hold (snow, a dark room, open water are flat in every frame) */
+const OVER_MEDIAN = 0.25
+/** ...and well past the frames either side of its run: the picture drops out and comes back, a flat ground stays */
+const SIDE_DROP = 0.2
+
+/** a pixel no channel lifts over this is dark, one no channel drops under that is bright: neither is a hole */
+const DARK = 60
+const BRIGHT = 225
+
+/** the share of a frame's pixels in its most common colour bucket (5 bits a channel); dark and bright count in no
+ *  bucket: a dark room, a fade or a flash is the film's or the cut's own */
+export function flatShare(rgb: Uint8Array, frame: number): number {
+    const n = HOLE_W * HOLE_H
+    const counts = new Map<number, number>()
+    let best = 0
+    for (let i = 0; i < n; i++) {
+        const o = (frame * n + i) * 3
+        const r = rgb[o]!
+        const g = rgb[o + 1]!
+        const b = rgb[o + 2]!
+        if (Math.max(r, g, b) < DARK || Math.min(r, g, b) > BRIGHT) continue
+        const k = ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3)
+        const c = (counts.get(k) ?? 0) + 1
+        counts.set(k, c)
+        if (c > best) best = c
+    }
+    return best / n
+}
+
+/** the frames flat far past the take's median, in runs the frames on either side of stand well under: the holes */
+export function holeFrames(shares: readonly number[]): number[] {
+    const sorted = [...shares].sort((a, b) => a - b)
+    const median = sorted[Math.floor(sorted.length / 2)] ?? 0
+    const flat = (i: number): boolean => shares[i]! > FLAT && shares[i]! > median + OVER_MEDIAN
+    const out: number[] = []
+    for (let a = 0; a < shares.length; a++) {
+        if (!flat(a)) continue
+        let b = a
+        while (b + 1 < shares.length && flat(b + 1)) b++
+        const top = Math.max(...shares.slice(a, b + 1))
+        const sides = [shares[a - 1], shares[b + 1]].filter((s) => s !== undefined)
+        if (sides.every((s) => s < top - SIDE_DROP)) for (let i = a; i <= b; i++) out.push(i)
+        a = b
+    }
+    return out
+}
+
+/** the hole frames of a take file */
+export async function takeHoles(file: string): Promise<number[]> {
+    const raw = join(tmpdir(), `holes-${process.pid}-${Math.random().toString(36).slice(2)}.rgb`)
+    try {
+        await ffmpeg(['-i', file, '-vf', `scale=${HOLE_W}:${HOLE_H}`, '-pix_fmt', 'rgb24', '-f', 'rawvideo', raw])
+        const rgb = new Uint8Array(readFileSync(raw))
+        const frames = Math.floor(rgb.length / (HOLE_W * HOLE_H * 3))
+        return holeFrames(Array.from({ length: frames }, (_, f) => flatShare(rgb, f)))
+    } finally {
+        rmSync(raw, { force: true })
+    }
+}

package/src/trailer/load-unit.ts

@@ -0,0 +1,31 @@
+// the repo's trailer unit, found by the walk every unit file takes (core/discover-checks.ts). Only a file whose text
+// calls `trailer(` is imported: `sk trailer check` stays fast in a repo of many units
+import { readFileSync } from 'node:fs'
+import { importFresh, repoUnitFiles } from '../core/discover-checks.ts'
+import type { TrailerUnit } from './adapter.ts'
+
+const cache = new Map<string, Promise<TrailerUnit | null>>()
+
+/** the unit found and imported again on the next read (a changed file is imported anew, keyed on its mtime) */
+export const forgetTrailerUnit = (root: string): void => void cache.delete(root)
+
+/** the repo's trailer unit, or null; two of them is an error naming both files. Read once per process */
+export function loadTrailerUnit(root: string): Promise<TrailerUnit | null> {
+    let got = cache.get(root)
+    if (!got) {
+        got = find(root)
+        cache.set(root, got)
+    }
+    return got
+}
+
+async function find(root: string): Promise<TrailerUnit | null> {
+    const found: { file: string; unit: TrailerUnit }[] = []
+    for (const f of repoUnitFiles(root)) {
+        if (!/\btrailer\s*\(/.test(readFileSync(f, 'utf8'))) continue
+        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
+}