rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/sound/eleven.ts

@@ -0,0 +1,72 @@
+// ElevenLabs, the paid voice: one line spoken by a voice id, and the account's characters left. The key comes from
+// ELEVENLABS_API_KEY, else from the argv the brand names (`trailer.elevenKey`, a secret manager read), and is never
+// printed
+const API = 'https://api.elevenlabs.io'
+const FORMAT = 'mp3_44100_128'
+export const ELEVEN_MODEL = 'eleven_v3'
+
+/** the key: ELEVENLABS_API_KEY, else what `command` prints */
+export function elevenKey(command: readonly string[] | undefined): string {
+    const env = process.env.ELEVENLABS_API_KEY?.trim()
+    if (env) return env
+    if (!command?.length) throw new Error('no ElevenLabs key: set ELEVENLABS_API_KEY, or name the argv that prints it in the brand (trailer.elevenKey)')
+    const r = Bun.spawnSync([...command], { stdout: 'pipe', stderr: 'pipe' })
+    const k = r.stdout.toString().trim()
+    if (r.exitCode !== 0 || !k) throw new Error(`no ElevenLabs key: ${command.join(' ')} printed none (exit ${r.exitCode})`)
+    return k
+}
+
+/** a call that has not answered in this long fails, loud */
+const CALL_TIMEOUT_MS = 120_000
+
+/** a fetch that gives up after CALL_TIMEOUT_MS with a line that says so */
+async function call(url: string, init: RequestInit, what: string): Promise<Response> {
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(CALL_TIMEOUT_MS) })
+    } catch (e) {
+        if ((e as Error).name === 'TimeoutError') throw new Error(`ElevenLabs ${what} did not answer in ${CALL_TIMEOUT_MS / 1000} s`)
+        throw e
+    }
+}
+
+async function ok(r: Response, what: string): Promise<Response> {
+    if (!r.ok) throw new Error(`ElevenLabs ${what}: ${r.status} ${(await r.text()).slice(0, 300)}`)
+    return r
+}
+
+export interface ElevenLine {
+    key: string
+    voice: string
+    text: string
+    seed: number
+    model?: string
+    stability?: number
+    similarity?: number
+    speed?: number
+    /** the API's language_code: en, fr… */
+    language?: string
+}
+
+/** what makes a line: the request's own words, the key of its kept answer */
+export function elevenAsk(q: ElevenLine): string {
+    const { key: _, ...ask } = q
+    return new Bun.CryptoHasher('sha1').update(JSON.stringify({ ...ask, model: q.model ?? ELEVEN_MODEL })).digest('hex').slice(0, 16)
+}
+
+/** one line as mp3 bytes and the characters it cost */
+export async function elevenSpeak(q: ElevenLine): Promise<{ audio: Uint8Array; chars: number }> {
+    const settings = { ...(q.stability !== undefined ? { stability: q.stability } : {}), ...(q.similarity !== undefined ? { similarity_boost: q.similarity } : {}), ...(q.speed !== undefined ? { speed: q.speed } : {}) }
+    const body = { text: q.text, model_id: q.model ?? ELEVEN_MODEL, seed: q.seed, ...(q.language ? { language_code: q.language } : {}), ...(Object.keys(settings).length ? { voice_settings: settings } : {}) }
+    const r = await ok(
+        await call(`${API}/v1/text-to-speech/${encodeURIComponent(q.voice)}?output_format=${FORMAT}`, { method: 'POST', headers: { 'xi-api-key': q.key, 'Content-Type': 'application/json' }, body: JSON.stringify(body) }, 'text to speech'),
+        'text to speech',
+    )
+    return { audio: new Uint8Array(await r.arrayBuffer()), chars: Number(r.headers.get('character-cost') ?? q.text.length) }
+}
+
+/** the characters used and allowed this billing period */
+export async function elevenCredits(key: string): Promise<{ used: number; limit: number }> {
+    const r = await ok(await call(`${API}/v1/user/subscription`, { headers: { 'xi-api-key': key } }, 'subscription'), 'subscription')
+    const d = (await r.json()) as { character_count: number; character_limit: number }
+    return { used: d.character_count, limit: d.character_limit }
+}

package/src/trailer/sound/fluid.ts

@@ -0,0 +1,71 @@
+// FluidSynth through a General MIDI soundfont: a .mid to a float wav, and that wav read back as samples. The machine's
+// fluidsynth and the house soundfont, SK_SOUNDFONT names another. Used by the score's GM tracks (score/gm-render.ts)
+// and by `sk sound midi`
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const FLUID = ['/opt/homebrew/bin/fluidsynth', '/usr/local/bin/fluidsynth', '/usr/bin/fluidsynth']
+
+/** the fluidsynth binary, or a loud error naming the install */
+export function fluidsynth(): string {
+    const found = FLUID.find((f) => existsSync(f)) ?? Bun.which('fluidsynth')
+    if (!found) throw new Error('no fluidsynth on this machine: brew install fluid-synth')
+    return found
+}
+
+/** the soundfont: SK_SOUNDFONT, else GeneralUser GS in ~/.local/share/soundfonts */
+export function soundfont(): string {
+    const f = process.env.SK_SOUNDFONT ?? join(homedir(), '.local/share/soundfonts/GeneralUser-GS.sf2')
+    if (!existsSync(f)) throw new Error(`no soundfont ${f}: put GeneralUser-GS.sf2 there, or name one in SK_SOUNDFONT`)
+    return f
+}
+
+let version: string | null = null
+/** what a GM render is keyed on beside its notes: the soundfont by path, size and time, and fluidsynth's version */
+export function fluidIdentity(): string {
+    version ??= Bun.spawnSync([fluidsynth(), '--version'], { stdout: 'pipe' }).stdout.toString().split('\n')[0] ?? ''
+    const sf = soundfont()
+    const st = statSync(sf)
+    return `${version} ${sf} ${st.size} ${st.mtimeMs}`
+}
+
+/** a .mid to a 32 bit float stereo wav at `rate`; `room`: fluidsynth's own reverb and chorus on (a song alone), off for
+ *  a stem the score's room takes */
+export function fluidRender(mid: string, out: string, o: { rate: number; room: boolean; gain?: number }): void {
+    // prettier-ignore
+    const args = [fluidsynth(), '-ni', '-q', '-g', String(o.gain ?? 1), '-r', String(o.rate), '-R', o.room ? '1' : '0', '-C', o.room ? '1' : '0', '-O', 'float', '-T', 'wav', '-F', out, soundfont(), mid]
+    const r = Bun.spawnSync(args, { stdout: 'pipe', stderr: 'pipe' })
+    if (r.exitCode !== 0 || !existsSync(out)) throw new Error(`fluidsynth ${mid}: exit ${r.exitCode}: ${r.stderr.toString().trim().split('\n').slice(-3).join(' ')}`)
+}
+
+/** a float or 16 bit pcm wav's two channels (a mono one doubled) */
+export function readWav(file: string): { rate: number; left: Float32Array; right: Float32Array } {
+    const b = readFileSync(file)
+    if (b.toString('latin1', 0, 4) !== 'RIFF' || b.toString('latin1', 8, 12) !== 'WAVE') throw new Error(`${file}: not a wav`)
+    let at = 12
+    let fmt: { format: number; channels: number; rate: number; bits: number } | null = null
+    while (at + 8 <= b.length) {
+        const id = b.toString('latin1', at, at + 4)
+        const size = b.readUInt32LE(at + 4)
+        const body = at + 8
+        if (id === 'fmt ') fmt = { format: b.readUInt16LE(body), channels: b.readUInt16LE(body + 2), rate: b.readUInt32LE(body + 4), bits: b.readUInt16LE(body + 14) }
+        if (id === 'data') {
+            if (!fmt) throw new Error(`${file}: data before fmt`)
+            const float = fmt.format === 3 || (fmt.format === 0xfffe && fmt.bits === 32)
+            const width = fmt.bits / 8
+            const n = Math.floor(Math.min(size, b.length - body) / (width * fmt.channels))
+            const left = new Float32Array(n)
+            const right = new Float32Array(n)
+            for (let i = 0; i < n; i++) {
+                const p = body + i * width * fmt.channels
+                const read = (q: number): number => (float ? b.readFloatLE(q) : fmt!.bits === 16 ? b.readInt16LE(q) / 32768 : b.readInt32LE(q) / 2147483648)
+                left[i] = read(p)
+                right[i] = fmt.channels > 1 ? read(p + width) : left[i]!
+            }
+            return { rate: fmt.rate, left, right }
+        }
+        at = body + size + (size % 2)
+    }
+    throw new Error(`${file}: no data chunk`)
+}

package/src/trailer/sound/gen.ts

@@ -0,0 +1,139 @@
+// the house generators, the bodies of the `sk sound` verbs: a voice line (ElevenLabs, or comfy-ts cloning a clip or a
+// designed voice), a sound effect and a music bed from a prompt (comfy-ts on the GPU box), a MIDI file through the
+// soundfont. Each writes `out` trimmed and set at its level, then says its measures. A made file is the sound cache's
+// to keep (run.ts), so nothing here caches but the reference clip of a designed voice
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { decode, envelope, finish, measure, measureLine, trimOf, waveformPng } from './audio.ts'
+import type { TrailerVoice } from './brand.ts'
+import { comfyModule, comfyRun } from './comfy.ts'
+import { elevenAsk, elevenCredits, elevenKey, elevenSpeak } from './eleven.ts'
+import { fluidRender } from './fluid.ts'
+import { soundCache } from './run.ts'
+
+type Say = (line: string) => void
+
+/** a line read at this loudness, a bed and a MIDI song too */
+const LINE_LUFS = -16
+/** an sfx's sample peak */
+const SFX_PEAK = -3
+
+const scratch = <T>(f: (dir: string) => Promise<T>): Promise<T> => {
+    const dir = mkdtempSync(join(tmpdir(), 'sk-gen-'))
+    return f(dir).finally(() => rmSync(dir, { recursive: true, force: true }))
+}
+
+/** the file written whole or not at all, then its measures said and its waveform beside it as `<out>.png` */
+async function land(tmp: string, out: string, say: Say): Promise<void> {
+    mkdirSync(dirname(out), { recursive: true })
+    renameSync(tmp, out)
+    say(`ok: ${out}: ${measureLine(await measure(out))}`)
+    await waveformPng(out, `${out}.png`)
+}
+
+/** a line for an engine that reads plain text: `[pause]` becomes a breath, the other tags drop */
+export function plain(line: string): string {
+    return line
+        .replace(/[.…]*\s*\[pause\]\s*/g, '... ')
+        .replace(/\[[^\]]+\]\s*/g, '')
+        .replace(/’/g, "'")
+        .trim()
+}
+
+/** comfy-ts takes these language names */
+const LANGUAGE: Readonly<Record<string, string>> = { en: 'English', fr: 'French', de: 'German', es: 'Spanish', it: 'Italian', pt: 'Portuguese', ru: 'Russian', ja: 'Japanese', ko: 'Korean', zh: 'Chinese' }
+const comfyLanguage = (l: string | undefined): string | undefined => (l === undefined ? undefined : (LANGUAGE[l] ?? l))
+
+/** the reference clip of a designed voice, made once: `.shipkit/cache/sound/design-<key>.wav` */
+async function designedClip(root: string, comfy: string | undefined, v: Extract<TrailerVoice, { design: string }>, say: Say): Promise<{ clip: string; transcript: string }> {
+    const line = v.line ?? 'Every story starts somewhere. This one starts right here, with you, and it is only getting better.'
+    const module = comfyModule(comfy, 'tts-voice-design')
+    const key = new Bun.CryptoHasher('sha1').update(JSON.stringify([module, v.design, line, v.seed ?? 7, v.language ?? null])).digest('hex').slice(0, 16)
+    const clip = join(soundCache(root), `design-${key}.wav`)
+    if (!existsSync(clip)) {
+        say(`designing the voice "${v.design.slice(0, 60)}…" (comfy-ts ${module}, about 45 s)`)
+        await scratch(async (dir) => {
+            const raw = join(dir, 'design.flac')
+            await comfyRun(module, { description: v.design, line, seed: v.seed ?? 7, language: comfyLanguage(v.language) }, raw)
+            await finish(raw, join(dir, 'clip.wav'), trimOf(envelope(await decode(raw)), { tailDb: 45 }), { lufs: LINE_LUFS })
+            mkdirSync(soundCache(root), { recursive: true })
+            renameSync(join(dir, 'clip.wav'), clip)
+        })
+    }
+    return { clip, transcript: line }
+}
+
+/** one spoken line in a voice: silence trimmed at both ends, -16 LUFS */
+export async function genVoice(o: { root: string; text: string; voice: TrailerVoice; seed: number; comfy?: string; elevenKey?: string[]; out: string; say: Say }): Promise<void> {
+    const v = o.voice
+    await scratch(async (dir) => {
+        let raw: string
+        if ('eleven' in v) {
+            const key = elevenKey(o.elevenKey)
+            const line = { key, voice: v.eleven, text: o.text, seed: o.seed, model: v.model, stability: v.stability, similarity: v.similarity, speed: v.speed, language: v.language }
+            // the paid answer is kept the moment it lands: a make killed after it never bills again
+            raw = join(soundCache(o.root), `eleven-${elevenAsk(line)}.mp3`)
+            if (existsSync(raw)) o.say('ElevenLabs: the answer kept from an earlier call, no new call')
+            else {
+                const r = await elevenSpeak(line)
+                mkdirSync(soundCache(o.root), { recursive: true })
+                writeFileSync(`${raw}.part`, r.audio)
+                renameSync(`${raw}.part`, raw)
+                const c = await elevenCredits(key).catch((e: Error) => e)
+                o.say(`ElevenLabs: ${r.chars} characters, ${c instanceof Error ? `the characters left unread (${c.message.slice(0, 80)})` : `${(c.limit - c.used).toLocaleString('en')} of ${c.limit.toLocaleString('en')} left this period`}`)
+            }
+        } else {
+            const ref = 'clone' in v ? { clip: join(o.root, v.clone), transcript: v.transcript ?? readTranscript(join(o.root, v.clone)) } : await designedClip(o.root, o.comfy, v, o.say)
+            raw = join(dir, 'line.flac')
+            await comfyRun(comfyModule(o.comfy, 'tts-voice-clone'), { voice: ref.clip, transcript: ref.transcript, prompt: plain(o.text), seed: o.seed, engine: v.engine, language: comfyLanguage(v.language) }, raw)
+        }
+        const t = trimOf(envelope(await decode(raw)), { tailDb: 45 })
+        await finish(raw, join(dir, 'out.wav'), { ...t, start: Math.max(0, t.start - 0.03), end: t.end + 0.05 }, { lufs: LINE_LUFS })
+        await land(join(dir, 'out.wav'), o.out, o.say)
+    })
+}
+
+function readTranscript(clip: string): string {
+    const txt = clip.replace(/\.[a-z0-9]+$/i, '.txt')
+    if (!existsSync(txt)) throw new Error(`the voice clip ${clip} has no transcript: write what it says into ${txt}, or give transcript in the brand`)
+    return readFileSync(txt, 'utf8').trim()
+}
+
+/** a sound effect from a prompt: its silence before cut, its tail cut 45 dB under its peak (`hit`: its first hit
+ *  alone), its peak at -3 dBFS */
+export async function genSfx(o: { prompt: string; seconds: number; seed: number; hit: boolean; comfy?: string; out: string; say: Say }): Promise<void> {
+    await scratch(async (dir) => {
+        const raw = join(dir, 'sfx.flac')
+        await comfyRun(comfyModule(o.comfy, 'stable-audio'), { category: 'SFX', prompt: o.prompt, seconds: o.seconds, seed: o.seed }, raw)
+        await finish(raw, join(dir, 'out.wav'), trimOf(envelope(await decode(raw)), { tailDb: 45, hit: o.hit }), { peak: SFX_PEAK })
+        await land(join(dir, 'out.wav'), o.out, o.say)
+    })
+}
+
+/** a music bed or a song from a prompt: stable-audio plays it, ace-step sings its lyrics (lines after the first),
+ *  else it plays instrumental. -16 LUFS, its tail trimmed and its end faded */
+export async function genMusic(o: { prompt: string; engine: 'stable-audio' | 'ace-step'; seconds: number; seed: number; comfy?: string; out: string; say: Say }): Promise<void> {
+    await scratch(async (dir) => {
+        const raw = join(dir, 'music.flac')
+        if (o.engine === 'ace-step') {
+            const [caption = '', ...lyrics] = o.prompt.split('\n')
+            const prompt = `${caption}\n${lyrics.join('\n').trim() || '[Instrumental]'}`
+            await comfyRun(comfyModule(o.comfy, 'ace-step'), { prompt, seconds: Math.max(10, o.seconds), seed: o.seed }, raw)
+        } else await comfyRun(comfyModule(o.comfy, 'stable-audio'), { category: 'Music', prompt: o.prompt, seconds: Math.min(300, o.seconds), seed: o.seed }, raw)
+        const t = trimOf(envelope(await decode(raw)), { tailDb: 50 })
+        await finish(raw, join(dir, 'out.wav'), { ...t, fade: 0.5 }, { lufs: LINE_LUFS })
+        await land(join(dir, 'out.wav'), o.out, o.say)
+    })
+}
+
+/** a MIDI file through the soundfont, fluidsynth's own room on: -16 LUFS, its tail trimmed */
+export async function genMidi(o: { file: string; out: string; say: Say }): Promise<void> {
+    await scratch(async (dir) => {
+        const raw = join(dir, 'midi.wav')
+        fluidRender(o.file, raw, { rate: 48000, room: true, gain: 0.8 })
+        const t = trimOf(envelope(await decode(raw)), { tailDb: 50 })
+        await finish(raw, join(dir, 'out.wav'), { ...t, start: 0, fade: 0.3 }, { lufs: LINE_LUFS })
+        await land(join(dir, 'out.wav'), o.out, o.say)
+    })
+}

package/src/trailer/sound/index.ts

@@ -0,0 +1,60 @@
+// the trailer's sounds the repo's unit does not make: a line's own `run`, else the house preset its words name, made
+// through the one sound run (run.ts). What the build calls when a sound is no file and no unit answers it, and what
+// `sk trailer check` prints for each
+import { existsSync } from 'node:fs'
+import { isAbsolute, relative } from 'node:path'
+import type { SoundRequest } from '../adapter.ts'
+import type { SoundRun } from '../grammar.ts'
+import type { TrailerSoundInput } from './brand.ts'
+import { paidChars, presetOf, type SoundAsk } from './presets.ts'
+import { runSpec, soundRun } from './run.ts'
+
+async function brandSound(root: string): Promise<TrailerSoundInput | undefined> {
+    const { loadBrand } = await import('../../assets/run-assets.ts')
+    const b = await loadBrand(root)
+    if (typeof b === 'string') throw new Error(b)
+    return b?.trailer
+}
+
+/** the run a request makes: its own, else its preset; a file in the repo named by its repo relative path, so the key
+ *  holds no checkout's place */
+export function runOf(root: string, r: SoundRequest, brand: TrailerSoundInput | undefined): SoundRun {
+    if (r.run) return r.run
+    const inside = isAbsolute(r.text) && !relative(root, r.text).startsWith('..')
+    return presetOf({ ...r, text: inside ? relative(root, r.text) : r.text }, brand)
+}
+
+/** the request's sound file, made when the cache misses */
+export async function resolveSound(root: string, r: SoundRequest, say: (line: string) => void): Promise<string> {
+    const run = runOf(root, r, r.run ? undefined : await brandSound(root))
+    return (await soundRun(run, { root, dir: r.dir, ...(r.seconds !== undefined ? { seconds: r.seconds } : {}) }, say)).file
+}
+
+export interface SoundState {
+    line: number
+    kind: SoundAsk['kind']
+    cmd: string
+    made: boolean
+    /** a paid line not made yet: the characters it will cost */
+    cost: number | null
+}
+
+/** each request's command and whether it is made, for `sk trailer check`; an error is the line's */
+export async function soundStates(root: string, rs: readonly SoundRequest[]): Promise<(SoundState | { line: number; error: string })[]> {
+    const brand = rs.some((r) => !r.run) ? await brandSound(root) : undefined
+    return rs.map((r) => {
+        try {
+            const run = runOf(root, r, brand)
+            const spec = runSpec(run, { root, dir: r.dir, ...(r.seconds !== undefined ? { seconds: r.seconds } : {}) })
+            const made = existsSync(spec.file)
+            return { line: r.line, kind: r.kind, cmd: spec.cmd, made, cost: made ? null : paidChars(run, r.text) }
+        } catch (e) {
+            return { line: r.line, error: e instanceof Error ? e.message : String(e) }
+        }
+    })
+}
+
+/** a state as the check prints it */
+export const stateLine = (s: SoundState | { line: number; error: string }): string =>
+    'error' in s ? `line ${s.line}: ${s.error}` : `line ${s.line} ${s.kind} ${s.made ? 'made' : `to make${s.cost !== null ? ` (ElevenLabs, about ${s.cost} characters)` : ''}`}: ${s.cmd}`
+

package/src/trailer/sound/presets.ts

@@ -0,0 +1,69 @@
+// the house generators as presets of the one sound run: each short form of a .trailer (`voice "<line>"`,
+// `sfx "<prompt>"`, `music "<prompt>"`, `music <file>.mid`) becomes the `sk sound` command that makes it, every input
+// written in its words, so the key holds the voice, the seed and the length (and a .mid's soundfont)
+import { type TrailerSoundInput, type TrailerVoice, voiceOf } from './brand.ts'
+import type { SoundRun } from '../grammar.ts'
+import { ELEVEN_MODEL } from './eleven.ts'
+import { fluidIdentity } from './fluid.ts'
+
+/** what a line of the trailer asks for */
+export interface SoundAsk {
+    kind: 'voice' | 'sfx' | 'music'
+    /** the line read, the prompt, or a .mid file */
+    text: string
+    /** a retake: another seed is another take (default 1) */
+    seed?: number
+    /** voice: a voice of the brand; music: the engine */
+    by?: string
+    /** seconds made: an sfx's length, a music's length */
+    for?: number
+    /** sfx: its first hit alone */
+    hit?: boolean
+    /** music: what its cue covers */
+    seconds?: number
+}
+
+export const SFX_SECONDS = 2
+export const MUSIC_ENGINES = ['stable-audio', 'ace-step'] as const
+
+const q = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`
+const num = (n: number): string => String(+n.toFixed(3))
+const isMidi = (w: string): boolean => /\.midi?$/i.test(w)
+
+/** a music cue's length as the generator makes it: rounded up to 30 s, so a small edit of the cut makes nothing again */
+export const musicSeconds = (s: number | undefined): number => Math.min(300, Math.max(30, Math.ceil((s ?? 0) / 30) * 30))
+
+/** the flags that name a voice for `sk sound voice` */
+export function voiceFlags(v: TrailerVoice): { flags: string[]; reads: string[] } {
+    const opt = (k: string, x: string | number | undefined): string[] => (x === undefined ? [] : [`--${k}`, typeof x === 'number' ? num(x) : q(x)])
+    if ('eleven' in v)
+        return { flags: ['--eleven', q(v.eleven), '--model', q(v.model ?? ELEVEN_MODEL), ...opt('stability', v.stability), ...opt('similarity', v.similarity), ...opt('speed', v.speed), ...opt('language', v.language)], reads: [] }
+    if ('clone' in v) {
+        const txt = v.clone.replace(/\.[a-z0-9]+$/i, '.txt')
+        return { flags: ['--clone', q(v.clone), ...opt('transcript', v.transcript), ...opt('engine', v.engine), ...opt('language', v.language)], reads: v.transcript === undefined ? [v.clone, txt] : [v.clone] }
+    }
+    return { flags: ['--design', q(v.design), ...opt('design-line', v.line), ...opt('design-seed', v.seed), ...opt('engine', v.engine), ...opt('language', v.language)], reads: [] }
+}
+
+/** the run that makes what the line asks for */
+export function presetOf(a: SoundAsk, brand: TrailerSoundInput | undefined): SoundRun {
+    const seed = ['--seed', String(a.seed ?? 1)]
+    // the comfy-ts folder is in the words, so another folder makes the sound again
+    const comfy = brand?.comfy ? ['--comfy', q(brand.comfy)] : []
+    if (a.kind === 'voice') {
+        const voice = voiceOf(brand, a.by)
+        const v = voiceFlags(voice)
+        return { cmd: ['sk sound voice', q(a.text), ...v.flags, ...('eleven' in voice ? [] : comfy), ...seed, '--out {out}'].join(' '), ...(v.reads.length ? { reads: v.reads } : {}) }
+    }
+    if (a.kind === 'sfx') return { cmd: ['sk sound sfx', q(a.text), '--seconds', num(a.for ?? SFX_SECONDS), ...seed, ...(a.hit ? ['--hit'] : []), ...comfy, '--out {out}'].join(' ') }
+    // the soundfont and fluidsynth are in the words as a comment: another one renders the file again
+    if (isMidi(a.text)) return { cmd: `sk sound midi ${q(a.text)} --out {out} # fluid ${new Bun.CryptoHasher('sha1').update(fluidIdentity()).digest('hex').slice(0, 12)}`, reads: [a.text] }
+    const engine = a.by ?? 'stable-audio'
+    if (!(MUSIC_ENGINES as readonly string[]).includes(engine)) throw new Error(`music by ${engine}: the engines are ${MUSIC_ENGINES.join(', ')}`)
+    return { cmd: ['sk sound music', q(a.text), '--engine', engine, '--seconds', num(a.for ?? musicSeconds(a.seconds)), ...seed, ...comfy, '--out {out}'].join(' ') }
+}
+
+/** a paid run: the characters its line costs, else null */
+export function paidChars(r: SoundRun, text: string): number | null {
+    return r.cmd.includes(' --eleven ') ? text.length : null
+}

package/src/trailer/sound/run.ts

@@ -0,0 +1,189 @@
+// THE one way a trailer makes a sound: a command that writes `{out}`, cached on its words and the content of each file
+// it reads. A voice, an sfx, a music bed and a MIDI file are presets of it (presets.ts). The cache is
+// `.shipkit/cache/sound/<key>.wav` with `<key>.json` (the command, its measures) and `<key>.png` (its waveform), out of
+// the trailer's cache so a trailer prune never deletes a paid line. One sound is made at a time, under nice, never
+// while the machine's load is over 16
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs'
+import { loadavg } from 'node:os'
+import { join, relative, resolve } from 'node:path'
+import { ffmpeg } from '../ffmpeg.ts'
+import type { SoundRun } from '../grammar.ts'
+import { measure, measureLine, SOUND_RATE, waveformPng } from './audio.ts'
+
+/** the folder every made sound of the repo is kept in */
+export const soundCache = (root: string): string => join(root, '.shipkit', 'cache', 'sound')
+
+
+export interface RunPlace {
+    root: string
+    /** the .trailer's folder, where a `reads` file is looked for first */
+    dir: string
+    /** a music cue's length: `{seconds}` is it rounded up to 10 s */
+    seconds?: number
+}
+
+/** a music cue's seconds as the command reads them: rounded up to 10, so a small edit makes nothing again */
+export const runSeconds = (s: number | undefined): number => Math.max(10, Math.ceil((s ?? 0) / 10) * 10)
+
+const q = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`
+
+const escape = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** the command with `{seconds}` filled, each read file found (beside the .trailer first, then from the repo root) and
+ *  named in the command by its repo relative path, as a film's `@<file>` is: the command, run at the root, reads the
+ *  file the key hashed. Then the key and the cache file */
+export function runSpec(r: SoundRun, p: RunPlace): { cmd: string; reads: { path: string; abs: string }[]; key: string; file: string } {
+    let cmd = r.cmd.replaceAll('{seconds}', String(runSeconds(p.seconds)))
+    if (!cmd.includes('{out}')) throw new Error(`a sound run writes {out}: ${r.cmd}`)
+    const reads = (r.reads ?? []).map((given) => {
+        const abs = [resolve(p.dir, given), resolve(p.root, given)].find((f) => existsSync(f))
+        if (!abs) throw new Error(`sound run reads ${given}: no such file beside the .trailer or from the repo root`)
+        const rel = relative(p.root, abs)
+        const path = rel.startsWith('..') ? abs : rel
+        if (path !== given) cmd = cmd.replace(new RegExp(`(^|[\\s'"=])${escape(given)}(?=$|[\\s'"])`, 'g'), (_, before: string) => `${before}${path}`)
+        return { path, abs }
+    })
+    const h = new Bun.CryptoHasher('sha1').update(cmd)
+    for (const x of reads) h.update(`\0${x.path}\0`).update(readFileSync(x.abs))
+    const key = h.digest('hex').slice(0, 16)
+    return { cmd, reads, key, file: join(soundCache(p.root), `${key}.wav`) }
+}
+
+let queue: Promise<unknown> = Promise.resolve()
+
+/** the sound's file, made when the cache misses: the command run in the repo root, its output kept as a 48 kHz wav */
+export function soundRun(r: SoundRun, p: RunPlace, say: (line: string) => void): Promise<{ file: string; made: boolean }> {
+    const spec = runSpec(r, p)
+    if (existsSync(spec.file)) return Promise.resolve({ file: spec.file, made: false })
+    const job = queue.then(() => make(spec, p.root, say))
+    queue = job.catch(() => undefined)
+    return job
+}
+
+/** the process holding a lock file: alive, or the lock is stale */
+function holderAlive(lock: string): boolean {
+    let pid = 0
+    try {
+        pid = Number(readFileSync(lock, 'utf8').trim())
+    } catch {
+        return true // written this instant: its pid is not in it yet
+    }
+    if (!Number.isInteger(pid) || pid <= 0) return false
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (e) {
+        return (e as NodeJS.ErrnoException).code === 'EPERM'
+    }
+}
+
+/** `<key>.lock` beside the sound, across processes: taken with O_EXCL, its pid inside; a lock of a dead process is
+ *  taken over. Null when the sound was made while this one waited */
+async function lockSound(spec: ReturnType<typeof runSpec>, say: (line: string) => void): Promise<(() => void) | null> {
+    const lock = `${spec.file.slice(0, -4)}.lock`
+    for (let said = false; ; ) {
+        if (existsSync(spec.file)) return null
+        try {
+            const fd = openSync(lock, 'wx')
+            writeSync(fd, String(process.pid))
+            closeSync(fd)
+            if (existsSync(spec.file)) {
+                rmSync(lock, { force: true })
+                return null
+            }
+            return () => rmSync(lock, { force: true })
+        } catch (e) {
+            if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+        }
+        if (!holderAlive(lock)) {
+            rmSync(lock, { force: true })
+            continue
+        }
+        if (!said) say(`sound: ${spec.key} is being made by another process: waiting for it`)
+        said = true
+        await Bun.sleep(200)
+    }
+}
+
+async function make(spec: ReturnType<typeof runSpec>, root: string, say: (line: string) => void): Promise<{ file: string; made: boolean }> {
+    mkdirSync(soundCache(root), { recursive: true })
+    const unlock = await lockSound(spec, say)
+    if (!unlock) return { file: spec.file, made: false }
+    try {
+        return await makeLocked(spec, root, say)
+    } finally {
+        unlock()
+    }
+}
+
+/** a command that has not answered in this long is killed, loud: a hung box never stalls a build */
+const runTimeoutS = (): number => Number(process.env.SK_SOUND_TIMEOUT_S ?? 30 * 60)
+/** a `.make-*` folder older than this was left by a killed process */
+const STALE_MAKE_MS = 60 * 60 * 1000
+
+/** a process group ended: TERM, then KILL 5 s later */
+export function killGroup(pid: number): void {
+    const kill = (sig: NodeJS.Signals): void => {
+        try {
+            process.kill(-pid, sig)
+        } catch {
+            // already gone
+        }
+    }
+    kill('SIGTERM')
+    setTimeout(() => kill('SIGKILL'), 5000).unref()
+}
+
+const prepared = new Map<string, Promise<void>>()
+
+/** once per process and repo, before the first sound it makes: the folders killed makes left swept, then a wait while
+ *  the machine's load is over 16 */
+async function prepare(root: string, say: (line: string) => void): Promise<void> {
+    const cache = soundCache(root)
+    for (const e of readdirSync(cache)) {
+        const f = join(cache, e)
+        if (e.startsWith('.make-') && Date.now() - statSync(f).mtimeMs > STALE_MAKE_MS) rmSync(f, { recursive: true, force: true })
+    }
+    for (let waited = 0; loadavg()[0]! > 16; waited += 5) {
+        if (waited === 0) say(`sound: the load is ${loadavg()[0]!.toFixed(1)}, over 16: waiting before the first sound`)
+        if (waited > 600) throw new Error('sound: the load stayed over 16 for 10 minutes')
+        await Bun.sleep(5000)
+    }
+}
+
+async function makeLocked(spec: ReturnType<typeof runSpec>, root: string, say: (line: string) => void): Promise<{ file: string; made: boolean }> {
+    let ready = prepared.get(root)
+    if (!ready) prepared.set(root, (ready = prepare(root, say)))
+    await ready
+    const dir = mkdtempSync(join(soundCache(root), '.make-'))
+    try {
+        const out = join(dir, 'out.wav')
+        say(`sound: making ${spec.key}: ${spec.cmd.length > 160 ? `${spec.cmd.slice(0, 157)}…` : spec.cmd}`)
+        const t0 = performance.now()
+        // its own process group: a timeout kills the command and every child holding its pipes
+        const proc = Bun.spawn(['nice', '-n', '15', 'bash', '-c', spec.cmd.replaceAll('{out}', q(out))], { cwd: root, stdout: 'pipe', stderr: 'pipe', detached: true })
+        let timedOut = false
+        const timer = setTimeout(() => {
+            timedOut = true
+            killGroup(proc.pid)
+        }, runTimeoutS() * 1000)
+        const [text, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]).finally(() => clearTimeout(timer))
+        if (timedOut) throw new Error(`sound ${spec.key} did not answer in ${runTimeoutS()} s and was killed: ${spec.cmd}`)
+        for (const l of text.split('\n')) if (/^(ok|ElevenLabs|WARN|designing)/.test(l)) say(`  ${l}`)
+        if (code !== 0 || !existsSync(out)) {
+            const tail = `${err}\n${text}`.trim().split('\n').slice(-4).join('\n  ')
+            throw new Error(`sound ${spec.key} ${code !== 0 ? `exited ${code}` : 'wrote no {out}'}: ${spec.cmd}\n  ${tail}`)
+        }
+        const wav = join(dir, 'kept.wav')
+        await ffmpeg(['-y', '-v', 'error', '-i', out, '-ac', '2', '-ar', String(SOUND_RATE), '-c:a', 'pcm_s16le', wav])
+        const m = await measure(wav)
+        if (existsSync(`${out}.png`)) renameSync(`${out}.png`, `${spec.file.slice(0, -4)}.png`)
+        else await waveformPng(wav, `${spec.file.slice(0, -4)}.png`)
+        writeFileSync(`${spec.file.slice(0, -4)}.json`, `${JSON.stringify({ cmd: spec.cmd, reads: spec.reads.map((x) => x.path), made: new Date().toISOString(), ms: Math.round(performance.now() - t0), measures: m }, null, 1)}\n`)
+        renameSync(wav, spec.file)
+        say(`sound: ${relative(root, spec.file)} in ${((performance.now() - t0) / 1000).toFixed(1)} s: ${measureLine(m)}`)
+        return { file: spec.file, made: true }
+    } finally {
+        rmSync(dir, { recursive: true, force: true })
+    }
+}