rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/ffmpeg.ts

@@ -0,0 +1,72 @@
+// the one way the trailer spawns ffmpeg and ffprobe: a run that fails loud with ffmpeg's own words, a probe, the nine
+// frame sheet. The binaries resolve once, with the homebrew path for processes started without it
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename } from 'node:path'
+
+const FFMPEG = Bun.which('ffmpeg') ?? '/opt/homebrew/bin/ffmpeg'
+const FFPROBE = Bun.which('ffprobe') ?? '/opt/homebrew/bin/ffprobe'
+
+/** ffmpeg and ffprobe on this machine, or what to install */
+export function ffmpegMissing(): string | null {
+    for (const [name, bin] of [['ffmpeg', FFMPEG], ['ffprobe', FFPROBE]] as const) if (!Bun.which(bin)) return `${name} not found: brew install ffmpeg`
+    return null
+}
+
+const niced = (cmd: string[], nice?: number): string[] => (nice ? ['nice', '-n', String(nice), ...cmd] : cmd)
+
+const failure = (args: readonly string[], err: string, code: number | null): Error =>
+    new Error(`ffmpeg → ${basename(args.at(-1) ?? '')}: ${err.trim().split('\n').slice(-6).join('\n') || `exit ${code}`}`)
+
+/** ffmpeg with `args` after `-hide_banner -nostdin -y -loglevel error`; resolves to its stderr, rejects with it */
+export function ffmpeg(args: readonly string[], o: { nice?: number } = {}): Promise<string> {
+    return new Promise((ok, fail) => {
+        const cmd = niced([FFMPEG, '-hide_banner', '-nostdin', '-y', '-loglevel', 'error', ...args], o.nice)
+        const p = spawn(cmd[0]!, cmd.slice(1), { stdio: ['ignore', 'ignore', 'pipe'] })
+        let err = ''
+        p.stderr.on('data', (d: Buffer) => (err += d.toString()))
+        p.on('error', (e) => fail(new Error(`${FFMPEG}: ${e.message}; brew install ffmpeg`)))
+        p.on('close', (code) => (code === 0 ? ok(err) : fail(failure(args, err, code))))
+    })
+}
+
+/** one ffprobe of a media file: its length in seconds; throws when ffprobe cannot read it or finds no length */
+export function duration(file: string): number {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })
+    const d = Number(r.stdout.toString().trim())
+    if (r.exitCode !== 0 || !(d > 0)) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || 'no length'}`)
+    return d
+}
+
+/** the media file carries a sound stream */
+export function hasAudio(file: string): boolean {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })
+    if (r.exitCode !== 0) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`)
+    return r.stdout.toString().trim() !== ''
+}
+
+/** a sound's integrated loudness (LUFS) and true peak (dBTP), as ffmpeg's ebur128 measures them */
+export async function loudness(file: string): Promise<{ lufs: number; truePeak: number }> {
+    const log = await ffmpeg(['-nostats', '-loglevel', 'info', '-i', file, '-map', '0:a', '-af', 'ebur128=peak=true', '-f', 'null', '-'])
+    const summary = log.split('Summary:').at(-1) ?? ''
+    // silence measures -inf: floored, so the value stays a number in json
+    const num = (v: string | undefined): number => (v === '-inf' ? -120 : Number(v ?? Number.NaN))
+    const lufs = num(/I:\s+(-?[\d.]+|-inf) LUFS/.exec(summary)?.[1])
+    const truePeak = num(/Peak:\s+(-?[\d.]+|-inf) dBFS/.exec(summary)?.[1])
+    if (Number.isNaN(lufs) || Number.isNaN(truePeak)) throw new Error(`ebur128 ${basename(file)}: no loudness summary in ffmpeg's log`)
+    return { lufs, truePeak }
+}
+
+/** loudness() of a file that never changes under its name (a cached render), kept beside it */
+export async function loudnessKept(file: string): Promise<{ lufs: number; truePeak: number }> {
+    const json = `${file}.loudness.json`
+    if (existsSync(json)) return JSON.parse(readFileSync(json, 'utf8')) as { lufs: number; truePeak: number }
+    const m = await loudness(file)
+    writeFileSync(json, JSON.stringify(m))
+    return m
+}
+
+/** nine frames of a clip evenly spaced, three by three on one png: how a shot is judged */
+export async function sheetOf(clip: string, seconds: number, png: string): Promise<void> {
+    await ffmpeg(['-i', clip, '-vf', `fps=${(9 / seconds).toFixed(4)},scale=480:-2,tile=3x3`, '-frames:v', '1', png])
+}

package/src/trailer/footage.ts

@@ -0,0 +1,173 @@
+// the takes on disk: each film line that writes its own take (a project CLI film row, a `film run`, a `film url`) filmed once into
+// `.shipkit/cache/trailer/footage/<key>.<ext>`, a stamp beside it naming the world it was filmed on. A take of an older
+// world is reported, and filmed again only on --refilm. Written aside then renamed, two at once
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import type { TrailerFilmLine, TrailerUnit } from './adapter.ts'
+import { duration } from './ffmpeg.ts'
+import type { Shot, Trailer } from './grammar.ts'
+import { cliArgv, isTake, recipeText, recipeWords, runCommand, type Stamp, specOf, type Take, type TakeFilm, type TakeSpec, takeIsStill, takeName, takeSeconds } from './plan.ts'
+import { statesOf } from './states.ts'
+
+export const trailerCache = (root: string, part: 'footage' | 'pieces' | 'titles' | 'sound' | 'score'): string => join(root, '.shipkit', 'cache', 'trailer', part)
+
+/** a recipe file a `@<file>` word names: its repo relative path, its text */
+export interface Recipe {
+    path: string
+    text: string
+}
+
+/** what a take reads past its line: the recipe files, the repo's trailer unit */
+export interface TakeContext {
+    recipes: ReadonlyMap<string, Recipe>
+    unit: TrailerUnit | null
+}
+
+/** a film line as the unit sees it */
+export function filmLineOf(shot: Shot, f: Extract<TakeFilm, { kind: 'cli' }>, c: Pick<TakeContext, 'recipes'>): TrailerFilmLine {
+    const files = Object.fromEntries(recipeWords(f.argv).flatMap((w) => (c.recipes.has(w) ? [[w, c.recipes.get(w)!.text]] : [])))
+    return { line: f.line, shot: shot.name, argv: f.argv, output: f.output, files }
+}
+
+/** a take's spec and the words it runs: its row's defaults, the unit's `take` over them, each `@<file>` resolved */
+export function specFor(shot: Shot, f: TakeFilm, c: TakeContext): { spec: TakeSpec; argv?: string[] } {
+    // a run keys the files it says it reads, by their content
+    if (f.kind === 'run') return { spec: specOf(f, Object.fromEntries((f.reads ?? []).map((p) => [`reads:${p}`, c.recipes.get(`reads:${p}`)?.text ?? '']))) }
+    if (f.kind !== 'cli') return { spec: specOf(f) }
+    const line = filmLineOf(shot, f, c)
+    // a declared file word keys its content, and reaches the row as its repo relative path
+    const declared = Object.fromEntries((f.files ?? []).flatMap((i) => (c.recipes.has(`file:${f.argv[i]}`) ? [[`file:${f.argv[i]}`, c.recipes.get(`file:${f.argv[i]}`)!.text]] : [])))
+    const base = specOf(f, { ...Object.fromEntries(Object.entries(line.files).map(([w, text]) => [w, recipeText(text)])), ...declared })
+    const got = c.unit?.take?.({ ...line, version: base.version, length: base.length })
+    const spec: TakeSpec = got
+        ? { ...base, version: got.version ?? base.version, length: got.length ?? base.length, world: got.world ?? null, recipe: got.recipe === undefined ? base.recipe : { recipe: got.recipe, files: (base.recipe as { files?: unknown }).files ?? null } }
+        : base
+    const files = new Set(f.files ?? [])
+    return { spec, argv: f.argv.map((w, i) => (files.has(i) ? (c.recipes.get(`file:${w}`)?.path ?? w) : c.recipes.has(w) ? `@${c.recipes.get(w)!.path}` : w)) }
+}
+
+/** every shot's and footage block's take, with its stamp when it was filmed */
+export function takesOf(t: Trailer, root: string, c: TakeContext = { recipes: new Map(), unit: null }): Take[] {
+    const dir = trailerCache(root, 'footage')
+    return [...t.shots, ...t.footage].flatMap((shot) => {
+        const film = shot.film
+        if (!isTake(film) || shot.broken) return []
+        const { spec, argv } = specFor(shot, film, c)
+        const file = join(dir, takeName(shot, film, t, spec))
+        const stampFile = `${file}.json`
+        const stamp = existsSync(file) && existsSync(stampFile) ? (JSON.parse(readFileSync(stampFile, 'utf8')) as Stamp) : null
+        return [{ shot, film, file, stamp, spec, ...(argv ? { argv } : {}) }]
+    })
+}
+
+/** a git run's output, null when it fails; no size limit: a big repo lists many files */
+const git = (root: string, args: string[], env?: Record<string, string>): string | null => {
+    const r = Bun.spawnSync(['git', ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe', ...(env ? { env: { ...process.env, ...env } } : {}) })
+    return r.exitCode === 0 ? r.stdout.toString() : null
+}
+
+/**
+ * the world the takes show: every file of the repo as it stands, by its content (`trailer/` and `.shipkit/` left out),
+ * or only the `paths` the trailer unit's `stamp` names; a repo with no git: `no-git`. Content addressed: the working
+ * tree is staged into a throwaway copy of the index and the staged entries hashed, so the same content dirty or
+ * committed is one world, and an edit of the cut alone moves nothing
+ */
+export function worldStamp(root: string, paths?: readonly string[]): string {
+    const real = git(root, ['rev-parse', '--git-path', 'index'])
+    if (real === null) return 'no-git'
+    const spec = paths ? ['--', ...paths] : ['--', '.', ':(exclude)trailer', ':(exclude).shipkit']
+    if (paths) for (const p of paths) if (!existsSync(join(root, p))) throw new Error(`the trailer unit's stamp names a path the repo does not hold: ${p}`)
+    const index = join(tmpdir(), `sk-world-${process.pid}-${Math.random().toString(36).slice(2)}`)
+    try {
+        // a copy of the real index keeps git's stat cache: only the files that changed are read again
+        const from = isAbsolute(real.trim()) ? real.trim() : join(root, real.trim())
+        if (existsSync(from)) copyFileSync(from, index)
+        const env = { GIT_INDEX_FILE: index }
+        if (git(root, ['add', '-A', ...spec], env) === null) throw new Error('git add into the world\'s throwaway index failed')
+        const staged = git(root, ['ls-files', '-s', ...spec], env)
+        if (staged === null) throw new Error('git ls-files of the world\'s throwaway index failed')
+        return new Bun.CryptoHasher('sha1').update(staged).digest('hex').slice(0, 12)
+    } finally {
+        rmSync(index, { force: true })
+    }
+}
+
+export interface FilmContext {
+    root: string
+    t: Pick<Trailer, 'size' | 'fps' | 'base'>
+    world: string
+    /** the project CLI's argv, null when the repo has none */
+    cli: readonly string[] | null
+    /** a clip take that drops its picture is filmed again once, then refused (the unit's `holes`) */
+    holes?: boolean
+    say: (line: string) => void
+}
+
+/** film one take; a failure throws with the shot, its line and what the command said */
+export async function filmTake(tk: Take, c: FilmContext): Promise<Take> {
+    mkdirSync(trailerCache(c.root, 'footage'), { recursive: true })
+    const part = tk.file.replace(/(\.\w+)$/, '.part$1')
+    rmSync(part, { force: true })
+    const t0 = performance.now()
+    const seconds = takeSeconds(tk.shot, tk.film, tk.spec.length)
+    const f = tk.film
+    const still = takeIsStill(f)
+    let said = ''
+    for (let attempt = 1; ; attempt++) {
+        said = f.kind === 'url' ? await urlTake(tk, f, part, seconds, c) : await commandTake(tk, f, part, seconds, c)
+        if (still || !c.holes) break
+        const holes = await (await import('./holes.ts')).takeHoles(part)
+        if (holes.length === 0) break
+        const where = `the picture drops out on frames ${holes[0]} to ${holes.at(-1)}`
+        if (attempt >= 2) {
+            rmSync(part, { force: true })
+            throw new Error(`shot ${tk.shot.name} (line ${f.line}): ${where}, twice`)
+        }
+        c.say(`  ${tk.shot.name}: ${where}, filmed again`)
+    }
+    renameSync(part, tk.file)
+    const states = statesOf(said)
+    const first = (said.split('\n')[0] ?? '').replace(/\s·\sstates \S+/, '').replace(part, '').trim()
+    const stamp: Stamp = {
+        world: tk.spec.world ?? c.world,
+        filmedAt: new Date().toISOString(),
+        seconds: still ? 0 : duration(tk.file),
+        note: first.slice(0, 200),
+        ...(states ? { states } : {}),
+        ...(tk.spec.world ? { fixed: true as const } : {}),
+    }
+    writeFileSync(`${tk.file}.json`, JSON.stringify(stamp, null, 2))
+    c.say(`  filmed ${tk.shot.name}: ${still ? 'a still' : `${stamp.seconds.toFixed(2)} s`} in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
+    return { ...tk, stamp }
+}
+
+/** a take a command writes at `part` (a `film run`, a project CLI row); what it said, or a throw with its last lines */
+async function commandTake(tk: Take, f: Exclude<TakeFilm, { kind: 'url' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
+    if (f.kind === 'cli' && c.cli === null) throw new Error(`shot ${tk.shot.name} (line ${f.line}): film ${f.argv.join(' ')} needs the project CLI (the cli script of package.json)`)
+    const argv = f.kind === 'run' ? ['sh', '-c', runCommand(f, { out: part, seconds, size: c.t.size, fps: c.t.fps })] : cliArgv(c.cli!, f, part, seconds, tk.argv)
+    // the cut's frame and rate: a row that films at the cut's size reads them
+    const env = { ...process.env, SK_TRAILER_SIZE: `${c.t.size[0]}x${c.t.size[1]}`, SK_TRAILER_FPS: String(c.t.fps) }
+    const p = Bun.spawn(argv, { cwd: c.root, stdout: 'pipe', stderr: 'pipe', env })
+    const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    const said = `${out}${err}`.trim()
+    if (code !== 0 || !existsSync(part)) {
+        rmSync(part, { force: true })
+        const shown = f.kind === 'run' ? f.cmd : [...(c.cli ?? []), ...(tk.argv ?? f.argv)].join(' ')
+        throw new Error(`shot ${tk.shot.name} (line ${f.line}): ${shown} ${code !== 0 ? `exited ${code}` : `wrote no file at its --out`}${said ? `\n${said.split('\n').slice(-8).join('\n')}` : ''}`)
+    }
+    return said
+}
+
+/** a `film url` take through the house shot service; a throw names the shot, its line and the service's reason */
+async function urlTake(tk: Take, f: Extract<TakeFilm, { kind: 'url' }>, part: string, seconds: number | null, c: FilmContext): Promise<string> {
+    const { filmUrl } = await import('./url.ts')
+    try {
+        const note = await filmUrl(f, { root: c.root, base: c.t.base, size: c.t.size, fps: c.t.fps, seconds, out: part, say: c.say })
+        if (!existsSync(part)) throw new Error('the shot service wrote no file')
+        return note
+    } catch (e) {
+        rmSync(part, { force: true })
+        throw new Error(`shot ${tk.shot.name} (line ${f.line}): film url ${f.route}: ${(e as Error).message}`)
+    }
+}