rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/graph.ts

@@ -1,7 +1,7 @@
 // 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 { 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'
@@ -32,8 +32,29 @@ const XFADE: Record<Exclude<CutKind, 'hard'>, string> = {
     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 }
+/** 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
@@ -50,6 +71,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)
 
@@ -143,7 +239,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}`)
@@ -215,10 +378,19 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
         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)]
+            // 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
-            const f = Math.min(ti.style === 'line' || ti.style === 'logo' ? 0.7 : 0.25, dur / 3)
+            // 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)]
@@ -226,14 +398,16 @@ export function pieceArgs(a: Pick<StitchInput, 't' | 'sources' | 'titles' | 'loo
             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,` : ''}` +
+                `[${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
-            const rise = `${n3(H / 40)}*pow(max(0,1-(n-${n3(at * fps - base)})/${n3(Math.max(f, 0.05) * fps)}),2)`
+            // 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}` : `${img.x - (hyp - img.w) / 2}-${n3(W * 1.1)}*${flown}`
+            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}`
@@ -259,9 +433,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 +500,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,6 +18,8 @@ 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
 }
@@ -44,6 +46,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 +101,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 })

package/src/trailer/passage.ts

@@ -0,0 +1,129 @@
+// the verbs over a built cut (wiki build/trailer.md, The verbs and Versions): each section's levels, a passage clipped
+// with its sound (and the same passage of a kept version), a version kept, the take file of a shot
+import { constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import { type Loaded, load, Refused, type Say, takesOfLoaded } from './build.ts'
+import { ffmpeg } from './ffmpeg.ts'
+import { starts, type Trailer } from './grammar.ts'
+
+const outOf = (l: Pick<Loaded, 'dir'>): string => join(l.dir, 'out')
+
+/** the built video of a cut, refused when the build never ran */
+function builtOf(l: Pick<Loaded, 'dir' | 'file' | 't'>, cwd: string): string {
+    const f = join(outOf(l), `${l.t.name}.mp4`)
+    if (!existsSync(f)) throw new Refused(`no ${relative(cwd, f)}: sk trailer ${relative(cwd, l.file)} first`)
+    return f
+}
+
+/** a moment of the cut on the video clock: a section or a mark, a shot, or seconds; `end` takes its end */
+export function momentOf(t: Pick<Trailer, 'sections' | 'timelineAt' | 'shots'>, name: string, end: boolean): number {
+    if (/^\d+(\.\d+)?$/.test(name)) return Number(name)
+    if (t.timelineAt !== null) {
+        const sec = t.sections.find((s) => s.name === name)
+        if (sec) return t.timelineAt + sec.at + (end ? sec.seconds : 0)
+        for (const s of t.sections) {
+            const m = s.marks.find((x) => x.name === name)
+            if (m) return t.timelineAt + s.at + m.at
+        }
+    }
+    const i = t.shots.findIndex((s) => s.name === name)
+    if (i >= 0) return starts(t)[i]! + (end ? t.shots[i]!.length : 0)
+    throw new Refused(`${name}: no section, mark or shot of that name (or write seconds)`)
+}
+
+/** each section's loudness in the built cut, and its step from the section before */
+export async function levels(l: Loaded, say: Say, cwd: string): Promise<void> {
+    const video = builtOf(l, cwd)
+    const at0 = l.t.timelineAt
+    if (l.t.sections.length === 0 || at0 === null) throw new Refused('levels: this cut has no section')
+    const rows = await Promise.all(
+        l.t.sections.map(async (s) => {
+            const err = await ffmpeg(['-loglevel', 'info', '-ss', String(at0 + s.at), '-t', String(s.seconds), '-i', video, '-vn', '-af', 'volumedetect', '-f', 'null', '-'])
+            const mean = Number(/mean_volume: (-?[\d.]+)/.exec(err)?.[1] ?? Number.NaN)
+            const max = Number(/max_volume: (-?[\d.]+)/.exec(err)?.[1] ?? Number.NaN)
+            return { s, mean, max }
+        }),
+    )
+    say(`${relative(cwd, video)}: each section's mean and peak, dB (video clock)`)
+    rows.forEach((r, i) => {
+        const prev = rows[i - 1]
+        const step = prev ? `${r.mean - prev.mean >= 0 ? '+' : ''}${(r.mean - prev.mean).toFixed(1)}` : ''
+        say(`  ${r.s.name.padEnd(12)} ${(at0 + r.s.at).toFixed(1).padStart(6)} s ${r.s.seconds.toFixed(1).padStart(5)} s   mean ${r.mean.toFixed(1).padStart(6)}  peak ${r.max.toFixed(1).padStart(5)}  ${step.padStart(5)}`)
+    })
+}
+
+/** a kept version's video: the one mp4 of `versions/<v>/` */
+export function versionVideo(dir: string, v: string): string | null {
+    const d = join(dir, 'versions', v)
+    if (!existsSync(d)) return null
+    const f = readdirSync(d).find((x) => x.endsWith('.mp4'))
+    return f ? join(d, f) : null
+}
+
+/** a version's cut text read as today's tool reads it, with the cut's own recipes, and its video */
+async function versionCut(l: Loaded, v: string, cwd: string): Promise<{ t: Trailer; video: string }> {
+    const text = join(l.dir, 'versions', `${v}.trailer`)
+    if (!existsSync(text)) throw new Refused(`no ${relative(cwd, text)}`)
+    const kept = await load(text, l.root, { dir: l.dir, check: false })
+    if (kept.errors.length > 0) throw new Refused(`${v} does not read with today's tool (an older version builds only in a worktree at its tag): ${kept.errors[0]!.message}`)
+    const video = versionVideo(l.dir, v) ?? join(l.dir, 'versions', v, `${basename(l.dir)}-${v}.mp4`)
+    if (!existsSync(video)) throw new Refused(`no ${relative(cwd, video)}`)
+    return { t: kept.t, video }
+}
+
+/** the passage from `from` to the end of `to` as its own mp4, sound included; with a version, the same passage of it too */
+export async function clip(l: Loaded, from: string, to: string, pad: number, version: string | undefined, say: Say, cwd: string): Promise<void> {
+    const cut = async (t: Trailer, video: string, out: string): Promise<void> => {
+        const a = Math.max(0, momentOf(t, from, false) - pad)
+        const b = momentOf(t, to, true) + pad
+        if (b <= a) throw new Refused(`clip: ${to} ends before ${from} starts`)
+        await ffmpeg(['-ss', String(a), '-to', String(b), '-i', video, '-c:v', 'libx264', '-crf', '18', '-preset', 'veryfast', '-pix_fmt', 'yuv420p', '-c:a', 'aac', out], { nice: 10 })
+        say(`ok: ${relative(cwd, out)} (${a.toFixed(2)} to ${b.toFixed(2)} s)`)
+    }
+    const tag = from === to ? from : `${from}-${to}`
+    await cut(l.t, builtOf(l, cwd), join(outOf(l), `clip-${tag}.mp4`))
+    if (version) {
+        const v = await versionCut(l, version, cwd)
+        await cut(v.t, v.video, join(outOf(l), `clip-${tag}-${version}.mp4`))
+    }
+}
+
+/** keep the built cut as a version: its text, its video, its strip and each shot's take, cloned so they cost nothing */
+export function keep(l: Loaded, v: string, say: Say, cwd: string): void {
+    if (!/^v\d+$/.test(v)) throw new Refused(`keep: a version is v<n>, not ${v}`)
+    const text = join(l.dir, 'versions', `${v}.trailer`)
+    const dir = join(l.dir, 'versions', v)
+    if (existsSync(text) || existsSync(dir)) throw new Refused(`${v} is kept already: versions are never overwritten`)
+    const video = builtOf(l, cwd)
+    mkdirSync(join(dir, 'shots'), { recursive: true })
+    writeFileSync(text, readFileSync(l.file, 'utf8'))
+    // a build rewrites its files in place: a link would turn the version into the next build, a clone costs nothing on APFS
+    const clone = (a: string, b: string): void => copyFileSync(a, b, constants.COPYFILE_FICLONE)
+    clone(video, join(dir, `${basename(l.dir)}-${v}.mp4`))
+    const strip = join(outOf(l), `${l.t.name}.strip.png`)
+    if (existsSync(strip)) clone(strip, join(dir, `${l.t.name}.strip.png`))
+    const shots = join(outOf(l), `${l.t.name}-shots`)
+    const files = existsSync(shots) ? readdirSync(shots) : []
+    for (const f of files) clone(join(shots, f), join(dir, 'shots', f))
+    // the clones are the machine's: git keeps the text and the index, never a version's folder
+    const ignored = Bun.spawnSync(['git', 'check-ignore', '-q', dir], { cwd: l.root }).exitCode === 0
+    const ignore = join(l.dir, 'versions', '.gitignore')
+    if (!ignored && !existsSync(ignore)) writeFileSync(ignore, '*/\n')
+    say(`ok: kept ${v}: ${relative(cwd, text)}, ${relative(cwd, dir)}/ (the video, the strip, ${files.length} shots)`)
+    say(`then: its row in ${relative(cwd, join(l.dir, 'versions', 'index.md'))}, commit ${relative(cwd, text)} and that index, git tag trailer-${basename(l.dir)}-${v}, push the commit and the tag`)
+}
+
+/** the take file of each named shot or footage block */
+export function footage(l: Loaded, names: string[], say: Say, cwd: string): void {
+    const takes = takesOfLoaded(l)
+    for (const name of names) {
+        const s = [...l.t.shots, ...l.t.footage].find((x) => x.name === name)
+        if (!s) throw new Refused(`${name}: no shot or footage block of that name`)
+        const tk = takes.find((x) => x.shot === s)
+        if (!tk) {
+            say(`${name}  no take: its film is ${s.film?.kind ?? 'nothing'}`)
+            continue
+        }
+        say(`${name}  ${relative(cwd, tk.file)}${existsSync(tk.file) ? '' : '  (not filmed)'}`)
+    }
+}