rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/motion.ts

@@ -0,0 +1,207 @@
+// a title's entrance and exit, frame by frame: what each move does to the whole title or to each of its letters at a
+// point of its run. Pure: the grammar checks the words, titles.ts draws each state, graph.ts lays the frames. An exit
+// is its move played backwards; the knock is the one exit of its own
+
+export const MOVES = ['none', 'fade', 'rise', 'drop', 'slide', 'pop', 'shake', 'blur', 'wipe', 'typewriter', 'letters', 'wave'] as const
+export type MoveKind = (typeof MOVES)[number]
+/** the moves drawn letter by letter: the title is drawn again each frame, the rest move the drawn title */
+export const LETTER_MOVES: ReadonlySet<MoveKind> = new Set(['typewriter', 'letters', 'wave'])
+
+/** a move a title line names: `in pop 0.4s`; no seconds, its own default */
+export interface Move {
+    kind: MoveKind
+    seconds?: number
+}
+
+/** the whole title at a frame: its alpha, its offset in frame pixels, its scale and turn (radians) about its box's
+ *  middle, a blur in frame pixels, and the share of its width a wipe shows (1: all) */
+export interface Whole {
+    a: number
+    dx: number
+    dy: number
+    s: number
+    rot: number
+    blur: number
+    wipe: number
+}
+
+/** one letter at a frame, about its own middle: alpha, offset in frame pixels, scale */
+export interface Glyph {
+    a: number
+    dx: number
+    dy: number
+    s: number
+}
+
+/** what a frame draws: the whole title's state; with a letter move, each letter's and the plates' and bands' alpha */
+export interface TitleFrame {
+    whole: Whole
+    glyph?: (i: number, n: number) => Glyph
+    decor: number
+}
+
+export const STILL: Whole = { a: 1, dx: 0, dy: 0, s: 1, rot: 0, blur: 0, wipe: 1 }
+const AT_REST: TitleFrame = { whole: STILL, decor: 1 }
+
+const clip01 = (x: number): number => Math.max(0, Math.min(1, x))
+const BACK = 1.70158
+/** an ease out that overshoots a little and settles */
+export const backOut = (x: number): number => 1 + (BACK + 1) * (x - 1) ** 3 + BACK * (x - 1) ** 2
+const inOut = (x: number): number => (x < 0.5 ? 4 * x ** 3 : 1 - (-2 * x + 2) ** 3 / 2)
+const smooth = (x: number): number => x * x * (3 - 2 * x)
+
+/** a knocked title tips and flies out over this long */
+export const KNOCK_S = 0.4
+const KNOCK_TURN = 1.4
+
+/** the frame of `kind` at `p`, 0 (before the entrance) to 1 (at rest), on a frame W by H whose letters are `px` tall */
+export function moveFrame(kind: MoveKind, p: number, [W, H]: readonly [number, number], px: number): TitleFrame {
+    void W
+    p = clip01(p)
+    const whole = (w: Partial<Whole>): TitleFrame => ({ whole: { ...STILL, ...w }, decor: 1 })
+    switch (kind) {
+        case 'none':
+            return AT_REST
+        case 'fade':
+            return whole({ a: p })
+        case 'rise':
+            return whole({ a: p, dy: (H / 40) * (1 - p) ** 2 })
+        case 'drop':
+            return whole({ a: p, dy: -(H / 30) * (1 - p) ** 2 })
+        case 'slide':
+            return whole({ a: p, dx: -(H / 32) * (1 - p) ** 3 })
+        case 'pop':
+            return whole({ a: clip01(p * 3), s: 0.55 + 0.45 * backOut(p) })
+        case 'shake': {
+            const amp = (H / 26) * (1 - p) ** 2
+            return whole({ a: clip01(p * 4), dx: (amp * (Math.sin(p * 53) + 0.5 * Math.sin(p * 31 + 1))) / 1.5, dy: (amp * (Math.cos(p * 47) + 0.5 * Math.sin(p * 23 + 2))) / 1.5, rot: (amp / H) * 0.6 * Math.sin(p * 41) })
+        }
+        case 'blur':
+            return whole({ a: clip01(p * 1.6), blur: (H / 40) * (1 - p) ** 2, s: 1 + 0.04 * (1 - p) })
+        case 'wipe':
+            return whole({ wipe: inOut(p) })
+        case 'typewriter':
+            return { whole: STILL, decor: clip01(p * 4), glyph: (i, n) => ({ a: p * n >= i + 1 - 1e-9 ? 1 : 0, dx: 0, dy: 0, s: 1 }) }
+        case 'letters':
+            return {
+                whole: STILL,
+                decor: clip01(p * 3),
+                glyph: (i, n) => {
+                    const span = 0.45
+                    const q = smooth(clip01((p - (n > 1 ? (i / (n - 1)) * (1 - span) : 0)) / span))
+                    return { a: q, dx: 0, dy: px * 0.4 * (1 - q) ** 2, s: 1 }
+                },
+            }
+        case 'wave':
+            return {
+                whole: STILL,
+                decor: clip01(p * 3),
+                glyph: (i, n) => {
+                    const span = 0.5
+                    const q = clip01((p - (n > 1 ? (i / (n - 1)) * (1 - span) : 0)) / span)
+                    return { a: clip01(q * 2.5), dx: 0, dy: px * 0.7 * (1 - backOut(q)), s: 0.7 + 0.3 * backOut(q) }
+                },
+            }
+    }
+}
+
+/** a knocked title at `q`, 0 (still in place) to 1 (gone): it tips and flies off left and up */
+export function knockFrame(q: number, [W, H]: readonly [number, number]): TitleFrame {
+    const k = clip01(q) ** 2
+    return { whole: { ...STILL, rot: -KNOCK_TURN * k, dx: -W * 1.1 * k, dy: -H * 0.45 * k }, decor: 1 }
+}
+
+/** how many letters a title's text draws: every character but spaces, the `*` marks and the `\n` breaks */
+export const letterCount = (text: string): number => [...text.replaceAll('\\n', '').replace(/[*\s]/g, '')].length
+
+/** a move's length when its line names none; the default entrance and exit keep the style's own (`styleFade`) */
+export function moveSeconds(kind: MoveKind, letters: number): number {
+    switch (kind) {
+        case 'none':
+            return 0
+        case 'typewriter':
+            return 0.045 * letters
+        case 'letters':
+            return 0.3 + 0.03 * letters
+        case 'wave':
+            return 0.35 + 0.035 * letters
+        case 'pop':
+            return 0.35
+        case 'shake':
+        case 'blur':
+        case 'wipe':
+            return 0.5
+        default:
+            return 0.4
+    }
+}
+
+/** the style's own fade: a tagline and the logo breathe in slowly, the plates pop, a short's words come quick */
+export const styleFade = (style: string): number => (style === 'line' || style === 'logo' ? 0.7 : style === 'short' || style === 'progress' ? 0.15 : 0.25)
+
+/** what a title's entrance and exit are, their frames counted */
+export interface TitleMotion {
+    in: { kind: MoveKind; frames: number }
+    out: { kind: MoveKind | 'knock'; frames: number }
+}
+
+/** the title's span in seconds and frames, and what it shows: the words of its line, its style, its step */
+export interface MotionInput {
+    style: string
+    text: string
+    in?: Move
+    out?: Move
+    /** seconds from the title's start to its knock */
+    knock?: number
+    step?: { i: number; n: number }
+    /** seconds it stands, a knock's flight included */
+    seconds: number
+    /** frames it stands */
+    frames: number
+    fps: number
+    /** a short's caption on the cut's first frame: there whole, the cover the platforms take */
+    cover: boolean
+}
+
+/** a title's entrance and exit in frames. With no `in`, a title rises in (a short slides, a progress fades) over its
+ *  style's fade; with no `out`, it fades out over it; a default never takes more than a third of the title, a letter
+ *  move more than half. A progress step swaps on its beat: only the first fades in, only the last fades out */
+export function titleMotion(m: MotionInput): TitleMotion {
+    const fade = Math.min(styleFade(m.style), m.seconds / 3)
+    const letters = letterCount(m.text)
+    const own = (mv: Move | undefined, fallback: MoveKind): [MoveKind, number] => {
+        if (!mv) return [fallback, fallback === 'none' ? 0 : fade]
+        if (mv.seconds !== undefined) return [mv.kind, mv.seconds]
+        return [mv.kind, Math.min(moveSeconds(mv.kind, letters), m.seconds * (LETTER_MOVES.has(mv.kind) ? 0.5 : 1 / 3))]
+    }
+    const firstStep = m.step === undefined || m.step.i === 1
+    const lastStep = m.step === undefined || m.step.i === m.step.n
+    const defIn: MoveKind = m.style === 'short' ? 'slide' : m.style === 'progress' ? 'fade' : 'rise'
+    let [inKind, inS] = m.cover || !firstStep ? ['none' as MoveKind, 0] : own(m.in, defIn)
+    let [outKind, outS]: [MoveKind | 'knock', number] = m.knock !== undefined ? ['knock', KNOCK_S] : !lastStep ? ['none', 0] : own(m.out, 'fade')
+    if (inKind === 'none') inS = 0
+    if (outKind === 'none') outS = 0
+    let a = Math.round(inS * m.fps)
+    let b = Math.round(outS * m.fps)
+    // a title shorter than its moves shares its frames between them
+    if (a + b > m.frames) {
+        const k = m.frames / (a + b)
+        a = Math.floor(a * k)
+        b = Math.floor(b * k)
+    }
+    if (a === 0) inKind = 'none'
+    if (b === 0) outKind = 'none'
+    return { in: { kind: inKind, frames: a }, out: { kind: outKind, frames: b } }
+}
+
+/** the frame `k` of an entrance of `n` frames: frame 0 is before it, the frame after the last at rest */
+export const inFrame = (kind: MoveKind, k: number, n: number, size: readonly [number, number], px: number): TitleFrame => moveFrame(kind, k / n, size, px)
+
+/** the frame `k` of an exit of `n` frames: its move played backwards, the last frame gone; a knock leaves from its
+ *  first frame, still in place */
+export const outFrame = (kind: MoveKind | 'knock', k: number, n: number, size: readonly [number, number], px: number): TitleFrame =>
+    kind === 'knock' ? knockFrame(k / n, size) : moveFrame(kind, 1 - (k + 1) / n, size, px)
+
+/** the files of an entrance's or an exit's frames beside a title's PNG, as ffmpeg reads a numbered run */
+export const inFrames = (file: string): string => `${file}.in-%04d.png`
+export const outFrames = (file: string): string => `${file}.out-%04d.png`

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)'}`)
+    }
+}

package/src/trailer/plan.ts

@@ -1,40 +1,87 @@
 // what a build does, as data: each shot's take and its key, which takes film, the pieces the stitch renders. Pure: the
 // io (stamps on disk, the world's git stamp, ffmpeg) lives in footage.ts and stitch.ts, which read these answers
-import type { Film, Shot, Trailer } from './grammar.ts'
+import type { Film, Shot, TakeLength, Trailer } from './grammar.ts'
 import { starts } from './grammar.ts'
 
-/** bump when the core films differently from the same line: every core take films again */
-export const FILM_VERSION = 1
+/** bump when the core films differently from the same line: every take films again */
+export const FILM_VERSION = 2
 
-/**
- * the key of a take: what films, never how the cut uses it. The formula of pkm-multi's `footageKey`, verbatim, so a
- * take filmed there under the same version, recipe, size, fps and seconds keeps its file
- */
-export function footageKey(version: number | readonly number[], recipe: unknown, size: readonly [number, number], fps: number, seconds: number | null): string {
+/** the key of a take: what films (its version, its recipe, the frame, the rate, its seconds), never how the cut uses it */
+export function footageKey(version: unknown, recipe: unknown, size: readonly [number, number], fps: number, seconds: number | null): string {
     return new Bun.CryptoHasher('sha1').update(JSON.stringify([version, recipe, size, fps, seconds])).digest('hex').slice(0, 12)
 }
 
 /** a film that writes a take of its own: the others are read where they lie (a clip, an image) or drawn (a card) */
-export type TakeFilm = Extract<Film, { kind: 'run' | 'cli' | 'url' }>
-export const isTake = (f: Film | null): f is TakeFilm => f?.kind === 'run' || f?.kind === 'cli' || f?.kind === 'url'
+export type TakeFilm = Extract<Film, { kind: 'run' | 'cli' | 'url' | 'page' }>
+export const isTake = (f: Film | null): f is TakeFilm => f?.kind === 'run' || f?.kind === 'cli' || f?.kind === 'url' || f?.kind === 'page'
 
 /** the take is one picture, held for the shot */
 export const takeIsStill = (f: TakeFilm): boolean => (f.kind === 'cli' ? f.output === 'still' : f.still === true)
 
-/** the seconds a clip take films: what the shot shows, rounded up to 2 s, so a small edit never films again; a still: none */
-export function takeSeconds(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm): number | null {
-    return takeIsStill(f) ? null : Math.ceil((s.from + s.length) / 2) * 2
+/** the seconds a clip take films: what the shot shows rounded up to 2 s (so a small edit never films again), exactly
+ *  that, or none when it films as long as it plays; a still: none */
+export function takeSeconds(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, length: TakeLength = defaultLength(f)): number | null {
+    if (takeIsStill(f) || length === 'own') return null
+    return length === 'exact' ? +(s.from + s.length).toFixed(3) : Math.ceil((s.from + s.length) / 2) * 2
 }
 
-/** the film line as its key reads it: the line it sits on is never part of what films */
-export function recipeOf(f: TakeFilm): Omit<TakeFilm, 'line'> {
+const defaultLength = (f: TakeFilm): TakeLength => (f.kind === 'cli' && f.length === 'own' ? 'own' : 'steps')
+
+/** the film line as its key reads it: the line it sits on is never part of what films, nor its row's marks (the
+ *  spec's version and length key them) */
+export function recipeOf(f: TakeFilm): unknown {
+    if (f.kind === 'cli') {
+        const { line: _l, version: _v, length: _n, ...recipe } = f
+        return recipe
+    }
     const { line: _line, ...recipe } = f
     return recipe
 }
 
+/** what one take is, past its words: its version, how long it films, a world of its own, what its key reads. A row
+ *  gives the defaults, the repo's trailer unit refines one line (adapter.ts `take`) */
+export interface TakeSpec {
+    version: number | string | null
+    length: TakeLength
+    /** a fixed world (`rev:<commit>`): the take is never stale */
+    world: string | null
+    /** the paths its world is, when its row names them (over the unit's `stamp`) */
+    stamp?: string[]
+    recipe: unknown
+}
+
+/** a recipe file's text as its key reads it: comment lines (`#` first), trailing comments (a space, `#`, then a space or
+ *  the line's end, outside double quotes) and blank lines left out; a `#` inside a value (`#ff0000`) is content */
+export function recipeText(text: string): string {
+    return text
+        .split('\n')
+        .map((l) => {
+            if (l.trimStart().startsWith('#')) return ''
+            let q = false
+            for (let i = 0; i < l.length; i++) {
+                if (l[i] === '"') q = !q
+                else if (l[i] === '#' && !q && /\s/.test(l[i - 1] ?? '') && /^(\s|$)/.test(l.slice(i + 1, i + 2))) return l.slice(0, i).trim()
+            }
+            return l.trim()
+        })
+        .filter(Boolean)
+        .join('\n')
+}
+
+/** the `@<file>` words of a film line */
+export const recipeWords = (argv: readonly string[]): string[] => argv.filter((a) => /^@\S/.test(a))
+
+/** a take's spec from its row alone; `files` the text of each `@<file>` word, as recipeText reads it */
+export function specOf(f: TakeFilm, files: Readonly<Record<string, string>> = {}): TakeSpec {
+    const read = Object.keys(files).length > 0 ? { files: Object.fromEntries(Object.entries(files).map(([k, v]) => [k, new Bun.CryptoHasher('sha1').update(v).digest('hex').slice(0, 12)])) } : {}
+    return { version: f.kind === 'cli' ? (f.version ?? null) : null, length: defaultLength(f), world: null, recipe: { ...(recipeOf(f) as object), ...read }, ...(f.kind === 'cli' && f.stamp ? { stamp: f.stamp } : {}) }
+}
+
 /** the take's file name, by its key alone: shots on one film line, in one cut or in several, share one file */
-export function takeName(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, t: Pick<Trailer, 'size' | 'fps'>): string {
-    return `${footageKey(FILM_VERSION, recipeOf(f), t.size, t.fps, takeSeconds(s, f))}.${takeIsStill(f) ? 'png' : 'mp4'}`
+export function takeName(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, t: Pick<Trailer, 'size' | 'fps'>, spec: TakeSpec = specOf(f)): string {
+    // a fixed world is what films: two past commits are two takes, whatever the recipe keeps of their words
+    const recipe = spec.world === null ? spec.recipe : { world: spec.world, recipe: spec.recipe }
+    return `${footageKey([FILM_VERSION, spec.version ?? 0], recipe, t.size, t.fps, takeSeconds(s, f, spec.length))}.${takeIsStill(f) ? 'png' : 'mp4'}`
 }
 
 /** the world a take was filmed on, beside it */
@@ -46,9 +93,13 @@ export interface Stamp {
     seconds: number
     /** what the film said of it, its first line */
     note: string
+    /** each frame's state, run length encoded (states.ts), when the film said it */
+    states?: string
+    /** its world was fixed by its spec (a film of a past commit): never stale */
+    fixed?: true
 }
 
-export const fresh = (stamp: Stamp, world: string): boolean => stamp.world === world
+export const fresh = (stamp: Stamp, world: string): boolean => stamp.fixed === true || stamp.world === world
 
 /** a take as a build sees it: its shot, its file, its stamp when it was filmed */
 export interface Take {
@@ -56,6 +107,9 @@ export interface Take {
     film: TakeFilm
     file: string
     stamp: Stamp | null
+    spec: TakeSpec
+    /** the words the film runs: each `@<file>` as its repo relative path */
+    argv?: string[]
 }
 
 /** `--refilm`: every stale take, or the takes of the named shots */
@@ -63,7 +117,11 @@ export type Refilm = 'stale' | ReadonlySet<string> | null
 
 /** the takes to film, each group sharing one file and filmed once by its first shot: a missing take, a stale one under
  *  `--refilm`, or one whose shot `--refilm` names */
-export function takesToFilm(takes: readonly Take[], world: string, refilm: Refilm, only?: ReadonlySet<string>): Take[][] {
+/** the world a take is measured against: one for the cut, or one a take (a row that names its own paths) */
+export type World = string | ((tk: Take) => string)
+export const worldFor = (w: World, tk: Take): string => (typeof w === 'string' ? w : w(tk))
+
+export function takesToFilm(takes: readonly Take[], world: World, refilm: Refilm, only?: ReadonlySet<string>): Take[][] {
     const groups = new Map<string, Take[]>()
     for (const tk of takes) {
         if (only !== undefined && !only.has(tk.shot.name)) continue
@@ -74,14 +132,15 @@ export function takesToFilm(takes: readonly Take[], world: string, refilm: Refil
     return [...groups.values()].filter((g) => {
         const first = g[0]!
         if (first.stamp === null) return true
-        if (refilm === 'stale') return !fresh(first.stamp, world)
+        if (refilm === 'stale') return !fresh(first.stamp, worldFor(world, first))
         return refilm instanceof Set && g.some((tk) => refilm.has(tk.shot.name))
     })
 }
 
-/** the argv a project CLI film runs: its words, then the file and, for a clip, its seconds */
-export function cliArgv(cli: readonly string[], f: Extract<Film, { kind: 'cli' }>, out: string, seconds: number | null): string[] {
-    return [...cli, ...f.argv, '--out', out, ...(seconds === null ? [] : ['--seconds', String(seconds)])]
+/** the argv a project CLI film runs: its words (`argv`, the recipe files resolved), then the file and, for a clip, its
+ *  seconds */
+export function cliArgv(cli: readonly string[], f: Extract<Film, { kind: 'cli' }>, out: string, seconds: number | null, argv: readonly string[] = f.argv): string[] {
+    return [...cli, ...argv, '--out', out, ...(seconds === null ? [] : ['--seconds', String(seconds)])]
 }
 
 /** a `film run` command with its marks filled: `{out}`, `{seconds}`, `{w}`, `{h}`, `{fps}` */