rvlib-shipkit 2.2.0 → 2.3.0

package/src/trailer/plan.ts

@@ -1,16 +1,13 @@
 // 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)
 }
 
@@ -21,20 +18,70 @@ export const isTake = (f: Film | null): f is TakeFilm => f?.kind === 'run' || f?
 /** 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}` */

package/src/trailer/prune.ts

@@ -0,0 +1,193 @@
+// 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 [{ takesOfLoaded }, { trailerCache }, { scoreWavFile }, { scoreModuleFile, scoreModule }, titles, { lookOf }, { loadBrand, identityLogo }] = 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'),
+    ])
+    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)))
+                for (const s of t.shots) for (const ti of s.titles) names.titles.push(basename(titles.titleFile(dir, root, ti.text, ti.style, t.size, titles.placeOf(ti), look, ti.step)))
+            }
+            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,240 @@
+// 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 midi = noteToMidi(note)
+            return midi === null ? tok : mods + midiToNote(midi + semis) + (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(' ')
+}