rvlib-shipkit 2.3.0 → 2.4.0

package/src/trailer/sound/brand.ts

@@ -0,0 +1,42 @@
+// the voices a brand declares for its trailers (`.shipkit/identity/brand.ts`, its `trailer.voice` and
+// `trailer.voices`): an ElevenLabs voice, a clip comfy-ts clones, or a voice comfy-ts designs from words. Pure
+export type TrailerVoice =
+    /** ElevenLabs, paid: a voice id of the account or its library */
+    | { eleven: string; model?: string; stability?: number; similarity?: number; speed?: number; language?: string }
+    /** comfy-ts clones a clean 5 to 10 s clip (repo relative); its transcript, default the text of `<clip>.txt` */
+    | { clone: string; transcript?: string; engine?: string; language?: string }
+    /** comfy-ts designs the voice once from its description (the reference reads `line`), then clones it, free */
+    | { design: string; line?: string; seed?: number; engine?: string; language?: string }
+
+export interface TrailerSoundInput {
+    /** the comfy-ts module folder the free generators run (its tts-voice-clone, tts-voice-design, stable-audio,
+     *  ace-step): `comfy-ts run <comfy>/<module>` */
+    comfy?: string
+    /** argv printing the ElevenLabs key on stdout, as a secret manager read (ELEVENLABS_API_KEY wins); never the key */
+    elevenKey?: string[]
+    /** the voice every `voice "<line>"` reads */
+    voice?: TrailerVoice
+    /** more voices, by name, for `voice "<line>" by <name>` */
+    voices?: Record<string, TrailerVoice>
+}
+
+/** a repo with no voice: the house narrator, designed by comfy-ts */
+export const HOUSE_VOICE: TrailerVoice = {
+    design: 'a warm, clear narrator in their thirties, natural and unhurried, close to the microphone, studio quality',
+    line: 'Every story starts somewhere. This one starts right here, with you, and it is only getting better.',
+    seed: 7,
+}
+
+const kinds = (v: TrailerVoice): string[] => ['eleven', 'clone', 'design'].filter((k) => k in v && typeof (v as Record<string, unknown>)[k] === 'string')
+
+/** the voice a line reads with: `by` one of the brand's voices, else its voice, else the house narrator */
+export function voiceOf(brand: TrailerSoundInput | undefined, by?: string): TrailerVoice {
+    const v = by === undefined ? (brand?.voice ?? HOUSE_VOICE) : brand?.voices?.[by]
+    if (!v) {
+        const names = Object.keys(brand?.voices ?? {})
+        throw new Error(`no voice ${by} in the brand: ${names.length ? `its voices are ${names.join(', ')}` : 'it names none (trailer.voices in .shipkit/identity/brand.ts)'}`)
+    }
+    const k = kinds(v)
+    if (k.length !== 1) throw new Error(`the brand's voice${by ? ` ${by}` : ''} names ${k.length ? k.join(' and ') : 'nothing'}: one of eleven (a voice id), clone (a clip) or design (a description)`)
+    return v
+}

package/src/trailer/sound/comfy.ts

@@ -0,0 +1,38 @@
+// a comfy-ts module run on the GPU box: its vars as flags, the file at `out`, its progress on stderr, a loud failure
+// that names the box when it is down. The modules sit in the folder the brand names (`trailer.comfy`)
+import { killGroup } from './run.ts'
+
+/** the module `name` of the folder `comfy`, or a loud error when no folder is named */
+export function comfyModule(comfy: string | undefined, name: string): string {
+    if (!comfy) throw new Error(`no comfy-ts module folder for ${name}: name it in the brand (trailer.comfy) or pass --comfy <folder>`)
+    return `${comfy}/${name}`
+}
+
+/** a module run that has not answered in this long is killed, loud */
+const COMFY_TIMEOUT_S = 15 * 60
+
+export async function comfyRun(module: string, vars: Record<string, string | number | boolean | undefined>, out: string): Promise<void> {
+    const args = ['comfy-ts', 'run', module]
+    for (const [k, v] of Object.entries(vars)) if (v !== undefined) args.push(`--${k}`, String(v))
+    args.push('--out', out, '--json')
+    const p = Bun.spawn(args, { stdout: 'pipe', stderr: 'inherit', detached: true })
+    let timedOut = false
+    const timer = setTimeout(() => {
+        timedOut = true
+        killGroup(p.pid)
+    }, COMFY_TIMEOUT_S * 1000)
+    const text = await new Response(p.stdout).text()
+    const code = await p.exited.finally(() => clearTimeout(timer))
+    if (timedOut) throw new Error(`comfy-ts run ${module} did not answer in ${COMFY_TIMEOUT_S} s and was killed. Is the GPU box up?`)
+    const last = text.trim().split('\n').at(-1) ?? ''
+    let res: { ok?: boolean; error?: string } = {}
+    try {
+        res = JSON.parse(last) as typeof res
+    } catch {
+        // not json: the tail below says what happened
+    }
+    if (code !== 0 || res.ok === false) {
+        const why = res.error ?? text.trim().split('\n').slice(-3).join(' ')
+        throw new Error(`comfy-ts run ${module} failed (exit ${code}): ${why || 'no output'}. Is the GPU box up?`)
+    }
+}

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
+}