rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/prune.ts

@@ -0,0 +1,204 @@
+// the trailer's cache kept small (wiki build/trailer.md, The cache): what the cuts of every trailer folder still use
+// stays, the rest goes. Runs after every stitch and by hand (`sk trailer prune [--dry]`). What a cut uses is named by the
+// build's own key functions; a file younger than an hour is never deleted: another build may be writing or reading it
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import { cutFiles, load } from './build.ts'
+import { SCORE, musicCues } from './grammar.ts'
+import { pieces } from './plan.ts'
+
+/** the renders kept per section: the one the cut plays and the one before it, so undoing an edit renders nothing */
+const KEEP_PER_SECTION = 2
+/** a file younger than this is never deleted */
+export const RENDER_GRACE_MS = 60 * 60_000
+/** the folders the trailer's code writes; any other folder of the cache is dead and goes whole */
+const FOLDERS = ['footage', 'pieces', 'sound', 'score', 'titles']
+
+/** what the cuts use, by file name in each folder; `broken` names the cuts that do not read */
+export interface Live {
+    footage: Set<string>
+    /** the render stems of pieces/, pieces/mix/ and pieces/vertical/ */
+    stems: Set<string>
+    sound: Set<string>
+    score: Set<string>
+    titles: Set<string>
+    broken: string[]
+}
+
+/** the live set: each cut read, the name of every cache file its build reads, by the build's own key functions */
+export async function liveSet(root: string): Promise<Live> {
+    const live: Live = { footage: new Set(), stems: new Set(), sound: new Set(), score: new Set(), titles: new Set(), broken: [] }
+    const [{ fileOf, takesOfLoaded, titleRequest }, { trailerCache }, { scoreWavFile }, { scoreModuleFile, scoreModule }, titles, { lookOf }, { loadBrand, identityLogo }, fonts, { titleMotions }, { resolveStyles }] = await Promise.all([
+        import('./build.ts'),
+        import('./footage.ts'),
+        import('./score/sound.ts'),
+        import('./score/score.ts'),
+        import('./titles.ts'),
+        import('./look.ts'),
+        import('../assets/run-assets.ts'),
+        import('./fonts.ts'),
+        import('./graph.ts'),
+        import('./grammar.ts'),
+    ])
+    const brand = await loadBrand(root)
+    const look = typeof brand === 'string' ? null : lookOf(brand, await identityLogo(root))
+    for (const file of cutFiles(root)) {
+        // whatever a cut throws (its parse, the unit's take, its score), it is named and the keyed folders stay
+        try {
+            const l = await load(file, root, { check: false })
+            const why = l.errors[0]
+            if (why) {
+                live.broken.push(`${relative(root, file)}:${why.line}: ${why.message}`)
+                continue
+            }
+            const t = l.t
+            const names = { footage: takesOfLoaded(l).map((tk) => basename(tk.file)), stems: [] as string[], titles: [] as string[], score: [] as string[], sound: [] as string[] }
+            for (const p of pieces(t)) names.stems.push(`${t.name}-${p.name}`)
+            names.stems.push(`mix-${t.name}`, `${t.name}-vertical`)
+            if (look) {
+                const dir = trailerCache(root, 'titles')
+                names.titles.push(basename(titles.cardFile(dir, t.size, look)))
+                resolveStyles(t, (typeof brand === 'object' && brand?.trailer?.styles) || {})
+                const motions = titleMotions(t)
+                t.shots.forEach((s, i) =>
+                    s.titles.forEach((ti, j) => {
+                        const f = ti.fx?.font
+                        const font = f === undefined ? null : fonts.isFontFile(f) ? fileOf(f, l) : fonts.googleFile(f, ti.fx?.weight ?? 400)
+                        names.titles.push(basename(titles.titleFile(dir, { ...titleRequest(l, ti, look, motions[i]![j]!), font })))
+                    }),
+                )
+            }
+            if (t.score && l.score) {
+                names.score.push(basename(scoreModuleFile(scoreModule(t.score, t.sections).text, trailerCache(root, 'score'))))
+                const sound = trailerCache(root, 'sound')
+                names.sound.push(basename(scoreWavFile(l.score, l.score.seconds, sound)))
+                for (const { cue, at, end } of musicCues(t)) if (cue.song === SCORE) names.sound.push(basename(scoreWavFile(l.score, cue.from + end - at, sound)))
+            }
+            for (const k of ['footage', 'stems', 'titles', 'score', 'sound'] as const) for (const n of names[k]) live[k].add(n)
+        } catch (e) {
+            live.broken.push(`${relative(root, file)}: ${(e as Error).message}`)
+        }
+    }
+    return live
+}
+
+/** a file the prune deletes: its bytes, and whether another hard link keeps them on disk */
+interface Doomed {
+    file: string
+    bytes: number
+    linked: boolean
+}
+
+const doomed = (file: string): Doomed => {
+    const s = statSync(file)
+    return { file, bytes: s.size, linked: s.nlink > 1 }
+}
+
+/** the files of `dir` that `keep` refuses, past the grace */
+export function unlisted(dir: string, keep: (name: string) => boolean, now = Date.now()): Doomed[] {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && !keep(e.name))
+        .map((e) => join(dir, e.name))
+        .filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS)
+        .map(doomed)
+}
+
+/** a file stays when a cut names it, and every file named after it (its stamp `<file>.json`, its box, its levels) */
+export const keepListed =
+    (names: ReadonlySet<string>) =>
+    (name: string): boolean =>
+        names.has(name) || [...names].some((n) => name.startsWith(`${n}.`))
+
+const RENDER_RE = /^(.+)-([0-9a-f]{16})(?:\.part)?(?:\.\w+)+$/
+
+/** the renders of `dir` that go: every render of a stem no cut has (a renamed section, a shot's preview), and past the
+ *  newest `keep` of each live stem (a cache hit touches it). `stems` null: no stem is dropped */
+export function oldRenders(dir: string, stems: ReadonlySet<string> | null, keep = KEEP_PER_SECTION, now = Date.now()): Doomed[] {
+    if (!existsSync(dir)) return []
+    const byStem = new Map<string, Map<string, number>>()
+    for (const e of readdirSync(dir, { withFileTypes: true }).filter((x) => x.isFile())) {
+        const m = RENDER_RE.exec(e.name)
+        if (!m) continue
+        const keys = byStem.get(m[1]!) ?? new Map<string, number>()
+        keys.set(m[2]!, Math.max(keys.get(m[2]!) ?? 0, statSync(join(dir, e.name)).mtimeMs))
+        byStem.set(m[1]!, keys)
+    }
+    const kept = new Set<string>()
+    for (const [stem, keys] of byStem) {
+        if (stems !== null && !stems.has(stem)) continue
+        for (const [k] of [...keys].sort((x, y) => y[1] - x[1]).slice(0, keep)) kept.add(`${stem}-${k}`)
+    }
+    return unlisted(
+        dir,
+        (name) => {
+            const m = RENDER_RE.exec(name)
+            return m === null ? stems === null : kept.has(`${m[1]}-${m[2]}`)
+        },
+        now,
+    )
+}
+
+/** what one folder frees */
+export interface Freed {
+    folder: string
+    files: number
+    /** bytes the disk gets back */
+    bytes: number
+    /** bytes another hard link keeps */
+    linked: number
+}
+
+export interface Pruned {
+    freed: Freed[]
+    /** the cuts that do not read: the folders keyed on what the cuts use were left alone */
+    broken: string[]
+}
+
+function filesUnder(dir: string): string[] {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)]))
+}
+
+/** plans every folder's prune, then deletes unless `dry` */
+export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
+    const now = o.now ?? Date.now()
+    const [{ trailerCache }, { viewsToDrop }] = await Promise.all([import('./footage.ts'), import('../review/trailer-desk.ts')])
+    const cache = join(trailerCache(root, 'footage'), '..')
+    const live = await liveSet(root)
+    const whole = live.broken.length === 0
+    // titles/ holds the vertical's drawings too: only a title's and a card's files are the prune's
+    const ownTitle = (n: string): boolean => /^(title|card)-[0-9a-f]{16}\./.test(n)
+    const plan: [string, Doomed[]][] = [
+        ['footage/', whole ? unlisted(join(cache, 'footage'), keepListed(live.footage), now) : []],
+        ['pieces/', ['', 'mix', 'vertical'].flatMap((d) => oldRenders(join(cache, 'pieces', d), whole ? live.stems : null, KEEP_PER_SECTION, now))],
+        ['sound/', whole ? unlisted(join(cache, 'sound'), keepListed(live.sound), now) : []],
+        ['score/', whole ? unlisted(join(cache, 'score'), keepListed(live.score), now) : []],
+        ['titles/', whole ? unlisted(join(cache, 'titles'), (n) => !ownTitle(n) || keepListed(live.titles)(n), now) : []],
+    ]
+    const dead = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name)) : []
+    for (const d of dead) plan.push([`${d.name}/ (dead)`, filesUnder(join(cache, d.name)).map(doomed)])
+    plan.push(['trailer-view/', viewsToDrop(root).filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
+    if (!o.dry) {
+        for (const [, ds] of plan) for (const d of ds) rmSync(d.file, { force: true })
+        for (const d of dead) rmSync(join(cache, d.name), { recursive: true, force: true })
+    }
+    return {
+        freed: plan.map(([folder, ds]) => ({ folder, files: ds.length, bytes: ds.reduce((n, d) => n + (d.linked ? 0 : d.bytes), 0), linked: ds.reduce((n, d) => n + (d.linked ? d.bytes : 0), 0) })),
+        broken: live.broken,
+    }
+}
+
+const gb = (n: number): string => (n >= 1e9 ? `${(n / 1e9).toFixed(2)} GB` : `${(n / 1e6).toFixed(1)} MB`)
+
+/** the report, a line a folder; `short` folds it into one line for the end of a build */
+export function sayPruned(p: Pruned, dry: boolean, short = false): string[] {
+    const total = p.freed.reduce((n, f) => n + f.bytes, 0)
+    const files = p.freed.reduce((n, f) => n + f.files, 0)
+    if (short) return [`cache pruned: ${files} files, ${gb(total)} freed${p.broken.length > 0 ? ` (a cut does not read, the keyed folders left alone: ${p.broken[0]})` : ''}`]
+    return [
+        dry ? 'trailer cache, a dry run: nothing deleted' : 'trailer cache pruned',
+        ...p.freed.map((f) => `  ${f.folder.padEnd(20)} ${String(f.files).padStart(5)} files  ${gb(f.bytes).padStart(9)}${f.linked > 0 ? `  (and ${gb(f.linked)} a hard link keeps)` : ''}`),
+        `  ${'total'.padEnd(20)} ${String(files).padStart(5)} files  ${gb(total).padStart(9)}${dry ? ' would be freed' : ' freed'}`,
+        ...(p.broken.length > 0 ? [`  footage, sound, score, titles and unknown sections left alone: a cut does not read (${p.broken.join('; ')})`] : []),
+    ]
+}

package/src/trailer/score/compose.ts

@@ -0,0 +1,256 @@
+// composition helpers for a score's `code` and `play` lines: they only build pattern strings in the grammar of
+// pattern.ts, so a score stays plain note data once evaluated. Chords are written per bar, bars split by '|', a bar
+// holding several chords splits evenly: 'C | Am | F G | C'.
+
+import { noteToMidi } from './pattern.ts'
+
+const NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
+
+export function midiToNote(midi: number): string {
+    const oct = Math.floor(midi / 12) - 1
+    if (oct < 0 || oct > 8) throw new Error(`note ${midi} outside octaves 0..8`)
+    return `${NAMES[midi % 12]}${oct}`
+}
+
+/** joins pattern fragments into one row string */
+export function seq(...parts: string[]): string {
+    return parts.join(' ')
+}
+
+export function rep(part: string, n: number): string {
+    return Array.from({ length: n }, () => part).join(' ')
+}
+
+function splitMods(tok: string): { mods: string; body: string } {
+    const i = tok.lastIndexOf(':')
+    return i === -1 ? { mods: '', body: tok } : { mods: tok.slice(0, i + 1), body: tok.slice(i + 1) }
+}
+
+/** shifts every note token by `semis` (plain rows or `mel` shorthand), modifiers, holds, rests and drums kept */
+export function transpose(text: string, semis: number): string {
+    return text
+        .split(/\s+/)
+        .filter((t) => t !== '')
+        .map((tok) => {
+            const { mods, body } = splitMods(tok)
+            const [note = '', len] = body.split('/')
+            const midis = note.split('+').map(noteToMidi)
+            if (midis.some((m) => m === null)) return tok
+            return mods + midis.map((m) => midiToNote(m! + semis)).join('+') + (len === undefined ? '' : `/${len}`)
+        })
+        .join(' ')
+}
+
+/**
+ * durations shorthand: `E5/4` is E5 held 4 rows, `-/2` two rows of silence,
+ * a bare token lasts `unit` rows. Modifiers glue before the note:
+ * `v10:E5/4`, `@bell:C6/2`. Drum letters work the same way.
+ */
+export function mel(text: string, unit = 1): string {
+    const out: string[] = []
+    for (const tok of text.split(/\s+/)) {
+        if (tok === '' || tok === '|') continue
+        const slash = tok.lastIndexOf('/')
+        const head = slash === -1 ? tok : tok.slice(0, slash)
+        const len = slash === -1 ? unit : Number(tok.slice(slash + 1))
+        if (!Number.isInteger(len) || len < 1) throw new Error(`mel token "${tok}": bad length`)
+        const { body } = splitMods(head)
+        out.push(head)
+        for (let i = 1; i < len; i++) out.push(body === '-' ? '-' : '.')
+    }
+    return out.join(' ')
+}
+
+// chord qualities as semitone stacks above the root
+const QUALITIES: Record<string, number[]> = {
+    '': [0, 4, 7],
+    m: [0, 3, 7],
+    '7': [0, 4, 7, 10],
+    m7: [0, 3, 7, 10],
+    maj7: [0, 4, 7, 11],
+    dim: [0, 3, 6],
+    dim7: [0, 3, 6, 9],
+    aug: [0, 4, 8],
+    sus4: [0, 5, 7],
+    sus2: [0, 2, 7],
+    add9: [0, 4, 7, 14],
+    m9: [0, 3, 7, 10, 14],
+    '6': [0, 4, 7, 9],
+    m6: [0, 3, 7, 9],
+    '5': [0, 7],
+}
+
+export interface Chord {
+    /** pitch class 0..11 of the bass note (the slash note when given) */
+    bass: number
+    root: number
+    tones: number[]
+}
+
+/** 'C', 'F#m7', 'Bbmaj7', 'G/B' */
+export function parseChord(sym: string): Chord {
+    const [main = '', slash] = sym.split('/')
+    const m = /^([A-G])([#b]?)(.*)$/.exec(main)
+    if (!m) throw new Error(`chord "${sym}": no root`)
+    const pc = (l: string, a: string) => ((noteToMidi(`${l}${a}4`) ?? 0) + 120) % 12
+    const root = pc(m[1] ?? 'C', m[2] ?? '')
+    const q = QUALITIES[m[3] ?? '']
+    if (!q) throw new Error(`chord "${sym}": unknown quality "${m[3]}"`)
+    let bass = root
+    if (slash !== undefined) {
+        const s = /^([A-G])([#b]?)$/.exec(slash)
+        if (!s) throw new Error(`chord "${sym}": bad slash bass`)
+        bass = pc(s[1] ?? 'C', s[2] ?? '')
+    }
+    return { root, bass, tones: q }
+}
+
+interface Seg {
+    chord: Chord
+    rows: number
+}
+
+/** the chord chart as segments; `bar` is rows per bar */
+export function chart(text: string, bar = 16): Seg[] {
+    const segs: Seg[] = []
+    for (const b of text.split('|')) {
+        const syms = b.split(/\s+/).filter((s) => s !== '')
+        if (syms.length === 0) continue
+        if (bar % syms.length !== 0) throw new Error(`chart bar "${b}" does not split ${bar} rows evenly`)
+        for (const s of syms) segs.push({ chord: parseChord(s), rows: bar / syms.length })
+    }
+    return segs
+}
+
+/** lowest midi of pitch class `pc` at or above the C of `oct` */
+function at(pc: number, oct: number): number {
+    return 12 * (oct + 1) + pc
+}
+
+export type BassStyle =
+    | 'hold' // root held the whole segment
+    | 'half' // root, then fifth at half
+    | 'quarter' // root on every beat
+    | 'octave' // eighths bouncing root, octave
+    | 'drive' // straight eighths on the root, octave jump on the last
+    | 'gallop' // eighth + two sixteenths per beat
+    | 'walk' // quarters root, third, fifth, a step to the next root
+    | 'waltz' // root on the beat, chord fifth on beats 2 and 3 (3 beat bars)
+    | 'pulse' // root on beats 1 and 3, rests between
+
+/** a bass line over a chart, in octave `oct` (2 = the usual register) */
+export function bass(text: string, style: BassStyle, oct = 2, bar = 16, beat = 4): string {
+    const segs = chart(text, bar)
+    const out: string[] = []
+    segs.forEach((seg, i) => {
+        const r = at(seg.chord.bass, oct)
+        const fifth = at(seg.chord.root, oct) + 7
+        const third = at(seg.chord.root, oct) + (seg.chord.tones[1] ?? 4)
+        const next = segs[(i + 1) % segs.length]?.chord.bass ?? seg.chord.bass
+        const rows: string[] = []
+        const put = (row: number, midi: number | '-') => {
+            rows[row] = midi === '-' ? '-' : midiToNote(midi)
+        }
+        for (let k = 0; k < seg.rows; k++) rows.push('.')
+        switch (style) {
+            case 'hold':
+                put(0, r)
+                break
+            case 'half':
+                put(0, r)
+                if (seg.rows >= 2) put(seg.rows / 2, fifth > r + 9 ? fifth - 12 : fifth)
+                break
+            case 'quarter':
+                for (let k = 0; k < seg.rows; k += beat) put(k, r)
+                break
+            case 'octave':
+                for (let k = 0; k < seg.rows; k += beat / 2) put(k, (k / (beat / 2)) % 2 === 0 ? r : r + 12)
+                break
+            case 'drive':
+                for (let k = 0; k < seg.rows; k += beat / 2) put(k, k === seg.rows - beat / 2 && seg.rows >= bar ? r + 12 : r)
+                break
+            case 'gallop':
+                for (let k = 0; k < seg.rows; k += beat) {
+                    put(k, r)
+                    if (k + 2 < seg.rows) put(k + 2, r)
+                    if (k + 3 < seg.rows) put(k + 3, k + beat >= seg.rows ? r + 12 : r)
+                }
+                break
+            case 'walk': {
+                const target = at(next, oct)
+                const approach = target > r ? target - 1 : target + 1
+                const steps = [r, third, fifth > r + 9 ? fifth - 12 : fifth, approach]
+                for (let k = 0, j = 0; k < seg.rows; k += beat, j++) put(k, steps[Math.min(j, 3)] ?? r)
+                if (seg.rows <= beat * 2) {
+                    rows.fill('.')
+                    put(0, r)
+                    if (seg.rows > beat) put(beat, approach)
+                }
+                break
+            }
+            case 'waltz':
+                for (let k = 0; k < seg.rows; k += beat) put(k, k === 0 ? r : fifth > r + 9 ? fifth - 12 : fifth)
+                break
+            case 'pulse':
+                for (let k = 0; k < seg.rows; k += beat * 2) {
+                    put(k, r)
+                    if (k + beat < seg.rows) put(k + beat, '-')
+                }
+                break
+        }
+        out.push(...rows)
+    })
+    return out.join(' ')
+}
+
+/**
+ * an arpeggio over a chart: `shape` indexes the chord tones upward (0 root,
+ * 1 third, 2 fifth, 3 the root an octave up for a triad...), one index per
+ * step of `step` rows, cycling through the segment.
+ */
+export function arp(text: string, shape: number[], oct = 4, step = 2, bar = 16): string {
+    const out: string[] = []
+    for (const seg of chart(text, bar)) {
+        const n = seg.chord.tones.length
+        for (let k = 0, j = 0; k < seg.rows; k += step, j++) {
+            const idx = shape[j % shape.length] ?? 0
+            const iv = (seg.chord.tones[idx % n] ?? 0) + 12 * Math.floor(idx / n)
+            out.push(midiToNote(at(seg.chord.root, oct) + iv))
+            for (let h = 1; h < step && k + h < seg.rows; h++) out.push('.')
+        }
+    }
+    return out.join(' ')
+}
+
+/**
+ * one voice of a held chord: tone `which` of each chord, placed at or above
+ * `floor` (a midi note), re-struck per segment. Stack two or three pad tracks
+ * on different tones for a full chord.
+ */
+export function voice(text: string, which: number, floor: number, bar = 16, restrike = 0): string {
+    const out: string[] = []
+    for (const seg of chart(text, bar)) {
+        const n = seg.chord.tones.length
+        const iv = (seg.chord.tones[which % n] ?? 0) + 12 * Math.floor(which / n)
+        let m = seg.chord.root + iv
+        while (m < floor) m += 12
+        const note = midiToNote(m)
+        for (let k = 0; k < seg.rows; k++) out.push(k === 0 || (restrike > 0 && k % restrike === 0) ? note : '.')
+    }
+    return out.join(' ')
+}
+
+/**
+ * each chord of a chart whole, as one chord token (`D4+F4+A4`): every tone placed at or above `floor` (a midi note),
+ * stacked upward, re-struck per segment and every `restrike` rows. For strings, brass, an organ or a stab.
+ */
+export function chords(text: string, floor: number, bar = 16, restrike = 0): string {
+    const out: string[] = []
+    for (const seg of chart(text, bar)) {
+        let m = seg.chord.root
+        while (m < floor) m += 12
+        const tok = seg.chord.tones.map((iv) => midiToNote(m + iv)).join('+')
+        for (let k = 0; k < seg.rows; k++) out.push(k === 0 || (restrike > 0 && k % restrike === 0) ? tok : '.')
+    }
+    return out.join(' ')
+}