rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/graph.ts

@@ -1,9 +1,10 @@
 // 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 { CUTS, GROW_S, musicCues, starts, total } from './grammar.ts'
 import type { TrailerLook } from './look.ts'
 import { frameAt, frameSpans, type Piece } from './plan.ts'
+import { inFrames, KNOCK_S, outFrames, type TitleMotion, titleMotion } from './motion.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 */
@@ -14,26 +15,29 @@ const SEAM_EDGE: Partial<Record<CutKind, { axis: 'x' | 'y'; from: boolean }>> =
     '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]
 }
 
-/** 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 }
+/** 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
@@ -50,6 +54,81 @@ export interface StitchInput {
 }
 
 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)
 
@@ -102,9 +181,107 @@ function flashF(s: Shot): string {
         .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
+/** a frame's own pseudo random number, 0 to 1: the same cut draws the same frames */
+const rnd = (...xs: number[]): number => {
+    const v = Math.sin(xs.reduce((n, x, j) => n + x * [12.9898, 78.233, 37.719, 4.581][j % 4]!, 0)) * 43758.5453
+    return v - Math.floor(v)
+}
+
+/** the cuts the core draws, frame by frame over the frames both shots hold: `a` the shot leaving, `b` the one coming,
+ *  `n` frames, the result labelled `out`. A whip pans both shots past at speed, blurred along the way they fly; a
+ *  glitch tears the picture (colours split, bands torn sideways, grain) round a flicker from one shot to the next; a
+ *  leak burns two soft lights of the look across a dissolve */
+export function drawnCut(kind: CutKind, a: string, b: string, out: string, n: number, i: number, [W, H]: readonly [number, number], fps: number, look: Pick<TrailerLook, 'accent' | 'light'>): string[] {
+    const d = n / fps
+    if (kind === 'leak') {
+        const big = `s=${2 * W}x${H}:r=${fps}:d=${n3(d + 0.2)}:type=radial:speed=0`
+        const [y1, y2, r1, r2] = [Math.round(H * 0.4), Math.round(H * 0.85), Math.round(W * 0.45), Math.round(W * 0.3)]
+        return [
+            `[${a}][${b}]xfade=transition=fade:duration=${n3(d)}:offset=0,format=gbrp[lx${i}]`,
+            `gradients=${big}:n=3:c0=0xffdcaa:c1=${ff(look.accent)}:c2=0x000000:x0=${W}:y0=${y1}:x1=${W + r1}:y1=${y1},format=gbrp,crop=w=${W}:h=${H}:x='${W}*(1.1-t/${n3(d)})':y=0[la${i}]`,
+            `gradients=${big}:n=2:c0=0xff5a46:c1=0x000000:x0=${W}:y0=${y2}:x1=${W + r2}:y1=${y2},format=gbrp,crop=w=${W}:h=${H}:x='${W}*(0.25+0.6*t/${n3(d)})':y=0[lb${i}]`,
+            `[la${i}][lb${i}]blend=all_mode=screen,colorchannelmixer=rr=0.8:gg=0.8:bb=0.8,fade=t=in:st=0:d=${n3(d / 2)},fade=t=out:st=${n3(d / 2)}:d=${n3(d / 2)}[ll${i}]`,
+            `[lx${i}][ll${i}]blend=all_mode=screen:shortest=1,format=yuv420p[${out}]`,
+        ]
+    }
+    const ks = Array.from({ length: n }, (_, k) => k)
+    const g = [
+        `[${a}]split=${n}${ks.map((k) => `[ca${i}_${k}x]`).join('')}`,
+        `[${b}]split=${n}${ks.map((k) => `[cb${i}_${k}x]`).join('')}`,
+        ...ks.flatMap((k) => [`[ca${i}_${k}x]trim=start_frame=${k}:end_frame=${k + 1},setpts=PTS-STARTPTS[ca${i}_${k}]`, `[cb${i}_${k}x]trim=start_frame=${k}:end_frame=${k + 1},setpts=PTS-STARTPTS[cb${i}_${k}]`]),
+    ]
+    for (const k of ks) {
+        const [fa, fb, fo] = [`ca${i}_${k}`, `cb${i}_${k}`, `co${i}_${k}`]
+        const p = (k + 0.5) / n
+        if (kind.startsWith('whip-')) {
+            // eased in and out: the speed peaks mid way, and the blur with it (a box as wide as a frame's travel)
+            const u = p < 0.5 ? 4 * p ** 3 : 1 - (-2 * p + 2) ** 3 / 2
+            const across = kind === 'whip-left' || kind === 'whip-right'
+            const span = across ? W : H
+            const sigma = Math.min(600, (12 * Math.min(p, 1 - p) ** 2 * span * 0.35) / n)
+            const forward = kind === 'whip-left' || kind === 'whip-up'
+            const off = Math.round((forward ? u : 1 - u) * span)
+            const pair = forward ? `[${fa}][${fb}]` : `[${fb}][${fa}]`
+            g.push(`${pair}${across ? 'hstack' : 'vstack'}=inputs=2,crop=${W}:${H}:${across ? off : 0}:${across ? 0 : off},gblur=sigma=${n3(across ? sigma : 0)}:sigmaV=${n3(across ? 0 : sigma)}[${fo}]`)
+            continue
+        }
+        // glitch: the picture flickers from one shot to the other round the middle, torn hardest there
+        const env = Math.sin(Math.PI * p) ** 0.7
+        const flick = p > 0.3 && p < 0.7 && rnd(i, k, 9) < 0.45
+        const src = (p < 0.5) !== flick ? fa : fb
+        g.push(`[${src === fa ? fb : fa}]nullsink`)
+        const dx = Math.round(W * 0.016 * env * (0.4 + rnd(i, k, 1)))
+        const bands = 1 + Math.floor(rnd(i, k, 2) * 3)
+        let cur = `[${src}]format=gbrp,rgbashift=rh=${dx}:bh=${-dx}:gv=${Math.round(dx / 3)}:edge=smear`
+        const parts: string[] = []
+        for (let j = 0; j < bands; j++) {
+            const bh = 2 * Math.round((H * (0.03 + 0.1 * rnd(i, k, j, 3))) / 2)
+            const by = Math.round((H - bh) * rnd(i, k, j, 4))
+            const shift = Math.round((rnd(i, k, j, 5) - 0.5) * W * 0.16 * env)
+            parts.push(`${cur},split[gb${i}_${k}_${j}][gs${i}_${k}_${j}]`, `[gs${i}_${k}_${j}]crop=${W}:${bh}:0:${by}[gt${i}_${k}_${j}]`)
+            cur = `[gb${i}_${k}_${j}][gt${i}_${k}_${j}]overlay=x=${shift}:y=${by}`
+        }
+        g.push(...parts, `${cur},noise=alls=${Math.round(28 * env)}:allf=t+u:all_seed=${i * 977 + k},format=yuv420p[${fo}]`)
+    }
+    g.push(`${ks.map((k) => `[co${i}_${k}]`).join('')}concat=n=${n}:v=1:a=0,settb=1/${fps},setpts=N,format=yuv420p[${out}]`)
+    return g
+}
+
+/** each title's span on the cut, shot by shot: its first and last frame (inclusive) and its seconds, a knock's flight
+ *  in them. A progress step ends the frame before the next one starts: two steps never stand on one frame */
+export function titleSpans(t: Pick<Trailer, 'shots' | 'fps'> & Parameters<typeof starts>[0]): { ta: number; te: number; seconds: number }[][] {
+    const st = starts(t)
+    return t.shots.map((s, i) =>
+        s.titles.map((ti) => {
+            const at = st[i]! + ti.at
+            const seconds = Math.min(ti.for ?? s.length - ti.at, ti.knock === undefined ? Infinity : ti.knock - ti.at + KNOCK_S)
+            const handOff = ti.style === 'progress' && ti.step !== undefined && ti.step.i < ti.step.n ? 1 : 0
+            return { ta: frameAt(at, t.fps), te: Math.floor((at + seconds) * t.fps + 1e-6) - handOff, seconds }
+        }),
+    )
+}
+
+/** each title's entrance and exit in frames (motion.ts), shot by shot: what the build draws and the stitch lays */
+export function titleMotions(t: Pick<Trailer, 'shots' | 'fps'> & Parameters<typeof starts>[0]): TitleMotion[][] {
+    const spans = titleSpans(t)
+    return t.shots.map((s, i) =>
+        s.titles.map((ti, j) => {
+            const sp = spans[i]![j]!
+            return titleMotion({
+                style: ti.style,
+                text: ti.text,
+                ...(ti.in ? { in: ti.in } : {}),
+                ...(ti.out ? { out: ti.out } : {}),
+                ...(ti.knock !== undefined ? { knock: ti.knock - ti.at } : {}),
+                ...(ti.step ? { step: ti.step } : {}),
+                seconds: sp.seconds,
+                frames: Math.max(0, sp.te - sp.ta + 1),
+                fps: t.fps,
+                cover: ti.style === 'short' && sp.ta === 0,
+            })
+        }),
+    )
+}
 
 /** 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) */
@@ -143,7 +320,74 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
         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) {
+        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}`)
@@ -177,7 +421,9 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
             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}]`)
+            const how = CUTS[kind] as string
+            if (how === 'drawn') graph.push(...drawnCut(kind, `e${i - 1}`, `h${i}`, `j${i}`, head, i, [W, H], fps, a.look))
+            else if (edge === undefined) graph.push(`[e${i - 1}][h${i}]xfade=transition=${how}: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'
@@ -186,7 +432,7 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
                 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}]`,
+                    `[e${i - 1}][h${i}]xfade=transition=${how}: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}]`,
@@ -210,32 +456,34 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
         cur = 'ends'
     }
 
-    // the titles that show in the piece, wherever their shot is: each faded in and out over its own span
+    // the titles that show in the piece, wherever their shot is: each its entrance's frames, its still held, its exit's
+    // frames (titles.ts drew them all in one box), laid at that box
+    const tspans = titleSpans(t)
     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)]
+        s.titles.forEach((_, j) => {
+            const { ta, te } = tspans[i]![j]!
             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 [nIn, nOut] = [img.in ?? 0, img.out ?? 0]
+            const hold = te - ta + 1 - nIn - nOut
             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 segs: string[] = []
+            const seq = (pattern: string, n: number, tag: string): void => {
+                const k = input('-framerate', String(fps), '-start_number', '0', '-i', pattern)
+                graph.push(`[${k}:v]format=rgba,trim=end_frame=${n},settb=1/${fps},setpts=N[t${i}_${j}${tag}]`)
+                segs.push(`[t${i}_${j}${tag}]`)
+            }
+            if (nIn > 0) seq(inFrames(img.file), nIn, 'i')
+            if (hold > 0) {
+                const k = input('-i', img.file)
+                graph.push(`[${k}:v]format=rgba,loop=loop=${hold - 1}:size=1:start=0,settb=1/${fps},setpts=N[t${i}_${j}h]`)
+                segs.push(`[t${i}_${j}h]`)
+            }
+            if (nOut > 0) seq(outFrames(img.file), nOut, 'o')
+            const join = segs.length > 1 ? `${segs.join('')}concat=n=${segs.length}:v=1:a=0,` : `${segs[0]}`
+            graph.push(`${join}${segs.length > 1 ? '' : 'null,'}trim=start_frame=${from - ta}:end_frame=${to - ta + 1},settb=1/${fps},setpts=N+${from - base}[t${i}_${j}]`)
             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}]`)
+            graph.push(`[${cur}][t${i}_${j}]overlay=x=${img.x}:y=${img.y}:eof_action=pass:enable='${on}'[v${i}_${j}]`)
             cur = `v${i}_${j}`
         })
     })
@@ -259,9 +507,17 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
     ]
 }
 
+/** 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 mix through a limiter */
-export function mixArgs(a: Pick<StitchInput, 't' | 'music' | 'sfx' | 'voices'>, out: string): string[] {
+ *  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)
@@ -318,6 +574,9 @@ export function mixArgs(a: Pick<StitchInput, 't' | 'music' | 'sfx' | 'voices'>,
     })
     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]`)
+    // 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

@@ -1,11 +1,28 @@
-// the repo's trailer unit, found by the walk every unit file takes (core/discover-checks.ts)
+// 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'
 
-/** 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 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 })
     }

package/src/trailer/look.ts

@@ -18,8 +18,13 @@ export interface TrailerLookInput {
     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 words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left out */
+    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string }
     /** the vertical short's look (a `vertical` cut), each part `false` to leave it out (vertical.ts) */
     vertical?: VerticalLookInput
+    /** text styles by name, each a title line's words (`style big font "Bebas Neue" in letters`): a title's `style`
+     *  names one; one named like a built in style gives that style its defaults (grammar.ts resolveStyles) */
+    styles?: Record<string, string>
 }
 
 /** what a vertical short wears, image paths repo relative; its colours and face are the look's */
@@ -44,6 +49,8 @@ export interface TrailerLook {
     chip: { fill: string; ink: string }
     font: { file: string | null; family: string; weight: number }
     logo: string | null
+    /** the short's words: their face and colours */
+    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string }
 }
 
 export interface BrandLike {
@@ -97,14 +104,24 @@ export function lookOf(brand: BrandLike | null, webLogo: string | null = null):
     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)]
+    const font = { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 }
+    const light = i.light ?? (luminance(p.ink) > 0.45 ? p.ink : '#ffffff')
+    const edge = i.edge ?? (luminance(ground[1]) < 0.2 ? ground[1] : darker(p.bg, 0.8))
+    const accent = i.accent ?? p.accent
+    const sh = i.short ?? {}
+    const shortFont = sh.font ? { file: sh.font.file ?? null, family: sh.font.family ?? (sh.font.file ? 'TrailerShortFace' : font.family), weight: sh.font.weight ?? font.weight } : font
     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,
+        light,
+        edge,
+        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,
+        short: { font: shortFont, light: sh.light ?? light, edge: sh.edge ?? edge, accent: sh.accent ?? accent },
     }
 }
+
+/** the look a short's words wear: the look with the short's face and colours in place */
+export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent })