@audio/neural-timbre 0.0.0-stage → 0.1.0

package/scripts/voices.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Every DX7 voice in a folder of sysex files, deduplicated by the sound it makes and split by
+// cartridge, for training and benchmarking the timbre encoder.
+//
+//   node scripts/voices.js [dir]          dir: default ~/.cache/audiojs/data/dx7
+//
+// Reads every *.syx under dir (sources.json names the subfolders and their terms), writes
+//   dir/voices.json   one row per distinct sound: name, cartridges it appears in, split, algorithm
+//   dir/patches.u8    155 bytes a row, the VCED voice as first seen
+//
+// Sound key: the 145 voice parameters (names excluded) with what the MSFA engine ignores zeroed
+// (synth-dx7 README, "Not modeled"): amplitude modulation (AMS, AMD), oscillator key sync, the LFO
+// when its pitch depth or sensitivity is 0, pitch-EG rates when its four levels are equal. Then
+// sounds whose raw engine output is identical at four notes and velocities merge too (a silent
+// modulator's envelope, say), and sounds that stay below -78 dBFS there are marked silent.
+//
+// Split by cartridge, never by voice: a cartridge's role comes from a hash of its file, and a
+// sound in any training cartridge is a training sound, in any development cartridge a
+// development one, so held-out sounds appear only in held-out cartridges. (Grouping cartridges
+// that share a sound chains 3,931 of 4,115 into one group through compilations, so the hash is
+// per cartridge.) Yamaha's factory and VRC cartridges always train: they are the catalog a user
+// queries, and the held-out read must come from cartridges the encoder never saw. Near-copies
+// are flagged: `near` is the fewest parameters in which a sound differs from any training sound.
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import os from 'node:os'
+import { parse, render } from '@audio/synth-dx7'
+
+const dir = process.argv[2] ?? path.join(os.homedir(), '.cache/audiojs/data/dx7')
+const ROLES = [['train', 75], ['dev', 5], ['heldout', 20]] // percent of cartridge groups
+const ALWAYS_TRAIN = ['factory/', 'vrc/']
+
+// Every DX7 voice message in a file: VMEM banks (format 9) and VCED voices (format 0) one by one,
+// so a DX7II file's performance and supplement messages don't hide its voices. The byte count is
+// not trusted: a tenth of circulating banks write 10 00 (hexadecimal 0x1000) where the manual's
+// 7-bit count is 20 00; their 4096 data bytes are intact.
+function voicesOf(bytes) {
+	if (bytes[0] !== 0xf0) try { return parse(bytes) } catch { return [] }
+	let out = []
+	for (let i = 0; i + 6 < bytes.length; i++) {
+		if (bytes[i] !== 0xf0 || bytes[i + 1] !== 0x43) continue
+		let format = bytes[i + 3], size = format === 9 ? 4096 : format === 0 ? 155 : 0
+		if (!size || i + 6 + size > bytes.length) continue
+		try { out.push(...parse(bytes.subarray(i + 6, i + 6 + size))) } catch {}
+		i += 6 + size - 1
+	}
+	return out
+}
+
+export const soundKey = patch => createHash('sha1').update(canonical(patch)).digest('hex').slice(0, 16)
+
+function canonical(patch) {
+	let p = Uint8Array.from(patch.subarray(0, 145))
+	for (let op = 0; op < 6; op++) p[op * 21 + 14] = 0 // AMS
+	p[140] = 0 // AMD
+	p[136] = 0 // oscillator key sync
+	if (p[139] === 0 || p[143] === 0) p.fill(0, 137, 144) // LFO inaudible: speed, delay, PMD, AMD, sync, wave, PMS
+	if (p[130] === p[131] && p[131] === p[132] && p[132] === p[133]) p.fill(0, 126, 130) // flat pitch EG: rates unused
+	return p
+}
+
+function* files(root) {
+	for (let name of readdirSync(root).sort()) {
+		let f = path.join(root, name)
+		if (statSync(f).isDirectory()) yield* files(f)
+		else if (/\.syx$/i.test(name)) yield f
+	}
+}
+
+const hash32 = s => parseInt(createHash('sha1').update(s).digest('hex').slice(0, 8), 16)
+
+// Raw int32 output at four keys and velocities, 0.3 s held and 0.2 s released: equal hashes mean
+// equal samples. Peak in int16 steps (2^13 of MSFA's 2^28 full scale is 2^-15 of it, one LSB).
+const PROBES = [[48, 40], [60, 100], [72, 127], [84, 70]]
+function fingerprint(patch) {
+	let h = createHash('sha1'), peak = 0
+	for (let [note, velocity] of PROBES) {
+		let y = render(patch, { note: note + patch[144] - 24, velocity, duration: 0.3, release: 0.2 })
+		h.update(new Uint8Array(y.buffer, y.byteOffset, y.byteLength))
+		for (let v of y) peak = Math.max(peak, Math.abs(v))
+	}
+	return { hash: h.digest('hex').slice(0, 16), peak: peak / 2 ** 13 }
+}
+
+// fewest differing parameters (sound keys' canonical bytes) from each of `rows` to any of `pool`
+function nearest(rows, pool) {
+	return rows.map(a => {
+		let best = 145
+		for (let b of pool) {
+			let d = 0
+			for (let i = 0; i < 145 && d < best; i++) if (a[i] !== b[i]) d++
+			if (d < best) best = d
+		}
+		return best
+	})
+}
+
+function main() {
+	let sources = JSON.parse(readFileSync(path.join(dir, 'sources.json'), 'utf8')).sources
+	let carts = [], byContent = new Map(), unreadable = []
+	for (let src of sources) for (let f of files(path.join(dir, src.dir))) {
+		let rel = path.relative(dir, f), voices = voicesOf(readFileSync(f))
+		if (!voices.length) { unreadable.push(rel); continue }
+		let content = createHash('sha1').update(Buffer.concat(voices.map(v => v.patch))).digest('hex')
+		let c = byContent.get(content)
+		if (c) { c.copies.push(rel); continue }
+		c = { file: rel, source: src.id, copies: [], voices }
+		byContent.set(content, c); carts.push(c)
+	}
+
+	// distinct sounds, and the cartridges holding each
+	let sounds = new Map()
+	carts.forEach((c, ci) => c.voices.forEach((v, vi) => {
+		let key = soundKey(v.patch), s = sounds.get(key)
+		if (!s) sounds.set(key, s = { key, name: v.name, patch: v.patch, at: [] })
+		if (!s.at.some(a => a[0] === ci)) s.at.push([ci, vi])
+	}))
+
+	// identical renders are one sound
+	let byRender = new Map(), silent = new Set()
+	for (let [key, s] of sounds) {
+		let { hash, peak } = fingerprint(s.patch)
+		if (peak < 4) silent.add(key)
+		let first = byRender.get(hash)
+		if (!first) { byRender.set(hash, s); continue }
+		for (let a of s.at) if (!first.at.some(b => b[0] === a[0])) first.at.push(a)
+		sounds.delete(key)
+	}
+
+	let role = carts.map(c => {
+		if (ALWAYS_TRAIN.some(p => c.file.startsWith(p))) return 'train'
+		let h = hash32(c.file) % 100
+		for (let acc = 0, k = 0; k < ROLES.length; k++) if (h < (acc += ROLES[k][1])) return ROLES[k][0]
+	})
+
+	let rows = [], bytes = []
+	for (let s of sounds.values()) {
+		let roles = new Set(s.at.map(([ci]) => role[ci]))
+		let split = roles.has('train') ? 'train' : roles.has('dev') ? 'dev' : 'heldout'
+		let at = s.at.find(([cj]) => role[cj] === split), [ci, vi] = at, c = carts[ci], v = c.voices[vi]
+		rows.push({ id: s.key, name: v.name, split, algorithm: v.patch[134] + 1, source: c.source, cartridge: c.file, index: vi,
+			also: s.at.filter(a => a !== at).map(([cj, vj]) => `${carts[cj].file}#${vj}`) })
+		bytes.push(v.patch)
+	}
+	let train = rows.map((r, i) => r.split === 'train' ? canonical(bytes[i]) : null).filter(Boolean)
+	let other = rows.map((r, i) => [r, i]).filter(([r]) => r.split !== 'train')
+	nearest(other.map(([, i]) => canonical(bytes[i])), train).forEach((d, k) => { other[k][0].near = d })
+	rows.forEach(r => { if (silent.has(r.id)) r.silent = true })
+	writeFileSync(path.join(dir, 'patches.u8'), Buffer.concat(bytes))
+	let count = r => rows.filter(x => x.split === r).length
+	let summary = {
+		files: carts.length + carts.reduce((n, c) => n + c.copies.length, 0) + unreadable.length, unreadable: unreadable.length,
+		cartridges: carts.length, voices: carts.reduce((n, c) => n + c.voices.length, 0), sounds: rows.length,
+		heldoutCartridges: role.filter(r => r === 'heldout').length,
+		train: count('train'), dev: count('dev'), heldout: count('heldout'), silent: silent.size,
+		heldoutNearCopies: rows.filter(r => r.split === 'heldout' && r.near <= 3).length,
+	}
+	writeFileSync(path.join(dir, 'voices.json'), JSON.stringify({ version: 1, created: new Date().toISOString().slice(0, 10), summary, voices: rows }))
+	console.log(JSON.stringify(summary))
+}
+
+// importable for soundKey: the key a catalog entry's `id` is, to find the voice in your own sysex
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()

package/scripts/webgpu.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// The encoder in headless Chromium, on WebGPU and WASM, through this package, @audio/neural-runtime
+// and onnxruntime-web: embeddings of scripts/export.py's parity fixtures against PyTorch's (largest
+// difference, identical top-5).
+//
+//   node scripts/webgpu.js [--chrome path] [--weights dir]
+//
+// Needs onnxruntime-web and playwright-core resolvable from here, and a Chromium with WebGPU
+// (--chrome, else Playwright's own). weights: default ~/.cache/audiojs/neural.
+import http from 'node:http'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+let o = {}
+for (let a = process.argv.slice(2), i = 0; i < a.length; i += 2) o[a[i].replace(/^--/, '')] = a[i + 1]
+const dirOf = spec => path.dirname(fileURLToPath(import.meta.resolve(spec)))
+const roots = {
+	pkg: path.join(path.dirname(fileURLToPath(import.meta.url)), '..'),
+	runtime: dirOf('@audio/neural-runtime'), fft: dirOf('fourier-transform'), sinc: dirOf('@audio/resample-sinc'),
+	ort: path.join(dirOf('onnxruntime-web'), '..'), // dist/
+	cache: path.join(o.weights ?? process.env.AUDIO_NEURAL_CACHE ?? path.join(os.homedir(), '.cache/audiojs/neural'), 'timbre'),
+}
+
+const PAGE = `<!doctype html><meta charset="utf-8"><title>neural-timbre</title>
+<script type="importmap">{ "imports": {
+	"onnxruntime-web/webgpu": "/ort/dist/ort.webgpu.bundle.min.mjs", "onnxruntime-web": "/ort/dist/ort.wasm.bundle.min.mjs",
+	"@audio/neural-runtime": "/runtime/runtime.js", "@audio/resample-sinc": "/sinc/sinc.js", "fourier-transform": "/fft/index.js" } }</script>
+<script type="module">
+import { createEncoder, rank } from '/pkg/timbre.js'
+let out = { adapter: !!(navigator.gpu && await navigator.gpu.requestAdapter()) }
+let fx = await (await fetch('/cache/parity.json')).json(), { bands, frames } = fx.features, size = bands * frames
+let raw = Uint8Array.from(atob(fx.patches), c => c.charCodeAt(0)), half = new Float16Array(raw.buffer)
+let patches = Array.from({ length: fx.rows.length }, (_, i) => Float32Array.from(half.subarray(i * size, (i + 1) * size)))
+for (let name of ['encoder.onnx', 'encoder.int8.onnx']) for (let backend of ['webgpu', 'wasm']) {
+	try {
+		let enc = await createEncoder({ model: new Uint8Array(await (await fetch('/cache/' + name)).arrayBuffer()), backend })
+		await enc.project(patches.slice(0, 1))
+		let t = performance.now(), e = await enc.project(patches), ms = performance.now() - t
+		enc.free()
+		let want = fx[name], max = 0
+		e.forEach((v, i) => v.forEach((x, d) => { max = Math.max(max, Math.abs(x - want.embeddings[i][d])) }))
+		let cat = { vectors: Float32Array.from(want.catalog.flat()), dimensions: want.catalog[0].length }
+		let same = e.filter((v, i) => rank(v, cat, 5).map(r => r.index).join() === want.top5[i].join()).length
+		out[name + ' ' + backend] = { maxDiff: +max.toExponential(2), top5: same + '/' + e.length, msPerNote: +(ms / e.length).toFixed(2) }
+	} catch (err) { out[name + ' ' + backend] = { error: String(err.message).slice(0, 300) } }
+}
+window.result = out; document.title = 'done'
+</script>`
+
+const TYPES = { '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.wasm': 'application/wasm' }
+const server = http.createServer(async (req, res) => {
+	if (req.url === '/') { res.writeHead(200, { 'content-type': 'text/html' }); return res.end(PAGE) }
+	let [, root, ...rest] = decodeURIComponent(req.url.split('?')[0]).split('/')
+	try {
+		let file = path.join(roots[root], ...rest), body = await readFile(file)
+		res.writeHead(200, { 'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream' }); res.end(body)
+	} catch { res.writeHead(404); res.end() }
+})
+await new Promise(r => server.listen(0, r))
+let { chromium } = await import('playwright-core')
+let browser = await chromium.launch({ executablePath: o.chrome, headless: true, args: ['--enable-unsafe-webgpu'] })
+try {
+	let page = await browser.newPage()
+	await page.goto(`http://localhost:${server.address().port}/`)
+	await page.waitForFunction(() => document.title === 'done', null, { timeout: 600000 })
+	console.log(JSON.stringify(await page.evaluate(() => window.result), null, 1))
+} finally { await browser.close(); server.close() }

package/timbre.js

@@ -0,0 +1,233 @@
+// Name the sound in a recording: a small encoder maps one note to a unit vector, and a catalog of
+// reference vectors (one per preset, the mean over its rendered notes) is ranked by cosine. The
+// encoder is trained once; catalogs are swappable, each bound to the encoder bytes that built it
+// (gpu-font's split: the renderer labels, the network only encodes).
+//
+// The int8 encoder and two catalogs are hosted on Hugging Face, not in the package, so a source can
+// come out at its owner's request (README, Catalogs); scripts/ rebuild them.
+
+import { load, tensor, fetchModel } from '@audio/neural-runtime'
+import { features, cqt, FEATURES } from './features.js'
+
+export { features, cqt, FEATURES }
+
+// The commit of audiojs/dx7-timbre this version reads, so a version always gets the files it was
+// tested with.
+export const REVISION = '2dd88e107183463c5a40609a92b0545d8857c635'
+const REPO = 'audiojs/dx7-timbre'
+const HOSTED = `https://huggingface.co/${REPO}/resolve/${REVISION}/`
+
+// The hosted files, laid out as in the repository, each checked against its SHA-256 when read
+const FILES = {
+	encoder: { file: 'encoder.int8.onnx', sha256: 'aaa9fae0337325fc9ae0f15c45f711073255c09264a31a9779da635ec21b8484' },
+	'dx7-factory': { file: 'catalogs/dx7-factory.json', sha256: '7ab9d48c1b90a4ec04af3aeb63737352d63f959db8b1459d6b238cea365a0900' },
+	'dx7-all': { file: 'catalogs/dx7-all.json', sha256: '0dd0fd646e8aef7e417151e8ae76b5c2bec7fde3cb531e01a3bc4e5b964e3671' },
+}
+export const MODEL = new URL(FILES.encoder.file, HOSTED)
+export const catalogs = {
+	'dx7-factory': new URL(FILES['dx7-factory'].file, HOSTED),
+	'dx7-all': new URL(FILES['dx7-all'].file, HOSTED),
+}
+
+const isNode = typeof process !== 'undefined' && !!process.versions?.node
+// a URL scheme has two characters at least, so a Windows drive (C:\) stays a path
+const isUrl = s => /^[a-z][a-z0-9+.-]+:/i.test(s)
+
+// Web Crypto: global in browsers and Node 19+, node:crypto's webcrypto in Node 18
+const subtle = async () => globalThis.crypto?.subtle ?? (await import('node:crypto')).webcrypto.subtle
+export const sha256 = async bytes => Array.from(new Uint8Array(await (await subtle()).digest('SHA-256', bytes)), b => b.toString(16).padStart(2, '0')).join('')
+const canonical = v => Array.isArray(v) ? v.map(canonical) : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])])) : v
+export const featuresSha256 = (f = FEATURES) => sha256(new TextEncoder().encode(JSON.stringify(canonical(f))))
+
+// Bytes of a model or catalog: bytes as given; a URL, or a path in Node, read through
+// @audio/neural-runtime's fetchModel (file: URLs from disk).
+async function bytesOf(src, opts) {
+	if (src instanceof Uint8Array) return src
+	if (src instanceof ArrayBuffer) return new Uint8Array(src)
+	let href = String(src)
+	if (isNode && !isUrl(href)) href = (await import('node:url')).pathToFileURL(href).href
+	return fetchModel(href, opts)
+}
+
+// Base URL of the hosted files: opts.weights (a URL, or a directory in Node) holding a copy laid out
+// as the repository, else the pinned revision
+async function base(w) {
+	if (w == null) return HOSTED
+	w = String(w)
+	if (!isUrl(w)) {
+		if (!isNode) throw new Error(`neural-timbre: opts.weights must be a URL in the browser, got '${w}'`)
+		w = (await import('node:url')).pathToFileURL(w).href
+	}
+	return w.endsWith('/') ? w : w + '/'
+}
+
+// A hosted file's bytes ('encoder', 'dx7-factory', 'dx7-all') from opts.weights or the pinned
+// revision, refused unless of its SHA-256. A local copy is read in place; Node keeps a fetched one
+// in the neural cache, dx7-timbre/<file>, written whole once checked and read while its SHA-256
+// holds, so it loads offline after the first time; the browser keeps it in neural-runtime's Cache API.
+async function hosted(key, opts) {
+	let { file, sha256: want } = FILES[key], url = await base(opts.weights) + file
+	let store = isNode && !url.startsWith('file:') ? await cached(file) : null, bytes = store?.read()
+	if (bytes && await sha256(bytes) === want) return bytes
+	try { bytes = await fetchModel(url, { progress: opts.progress, fetch: opts.fetch, cache: !store }) }
+	catch (e) { throw new Error(`neural-timbre: ${file} not read (${e.message}): opts.weights takes a URL or directory holding a copy of ${HOSTED}`) }
+	let hex = await sha256(bytes)
+	if (hex !== want) throw new Error(`neural-timbre: ${url} has SHA-256 ${hex}, expected ${want}: a partial or altered download${isNode ? '' : " (clear the 'audio-neural' cache)"}, or another build of the file`)
+	store?.write(bytes)
+	return bytes
+}
+
+// <neural cache>/dx7-timbre/<file>: { read() → bytes or null, write(bytes) whole or not at all }
+async function cached(file) {
+	let [fs, path, os] = await Promise.all([import('node:fs'), import('node:path'), import('node:os')])
+	let dest = path.join(process.env.AUDIO_NEURAL_CACHE || path.join(os.homedir(), '.cache', 'audiojs', 'neural'), REPO.split('/')[1], file)
+	return {
+		read() { try { let b = fs.readFileSync(dest); return new Uint8Array(b.buffer, b.byteOffset, b.length) } catch { return null } },
+		write(bytes) {
+			let part = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.part`
+			fs.mkdirSync(path.dirname(dest), { recursive: true })
+			fs.writeFileSync(part, bytes)
+			fs.renameSync(part, dest)
+		},
+	}
+}
+
+// createEncoder({ model, backend, weights }) → { embed(audio, { sampleRate }) → unit Float32Array,
+// project(patches), binding: { encoderSha256, featuresSha256 }, free() }. model: URL, path or
+// bytes, default the hosted encoder (MODEL), the graph the hosted catalogs are built with.
+export async function createEncoder(opts = {}) {
+	let bytes = await (opts.model != null ? bytesOf(opts.model, opts) : hosted('encoder', opts))
+	let binding = { encoderSha256: await sha256(bytes), featuresSha256: await featuresSha256() }
+	let session = await load(bytes, { backend: opts.backend })
+	let input = session.inputs[0]?.name ?? 'features'
+	let output = session.outputs.some(o => o.name === 'embedding') ? 'embedding' : session.outputs[0]?.name
+	// prepared feature patches (bands × frames each) → unit embeddings
+	let project = async patches => {
+		let { bands, frames } = FEATURES, n = patches.length, x = new Float32Array(n * bands * frames)
+		patches.forEach((p, i) => x.set(p, i * bands * frames))
+		let e = (await session.run({ [input]: tensor(x, [n, 1, bands, frames]) }))[output].data, d = e.length / n
+		return Array.from({ length: n }, (_, i) => unit(e.subarray(i * d, (i + 1) * d)))
+	}
+	return {
+		binding, project,
+		// one note (Float32Array, or channels to average) → its unit embedding
+		embed: async (audio, { sampleRate = FEATURES.sampleRate } = {}) => (await project([features(audio, { sampleRate })]))[0],
+		free: () => session.free(),
+	}
+}
+
+export function unit(v) {
+	let s = 0
+	for (let x of v) s += x * x
+	let norm = Math.sqrt(s)
+	if (!(norm > 1e-12)) throw new Error('neural-timbre: zero embedding')
+	return Float32Array.from(v, x => x / norm)
+}
+
+// Catalog vectors: one row per entry, `bits` a number with one scale per row (gpu-font's
+// int8-base64 and int4-base64: signed values in a little-endian bit stream).
+const BITS = { 'int8-base64': 8, 'int4-base64': 4 }
+
+export function pack(values, bits) {
+	let bytes = new Uint8Array(Math.ceil(values.length * bits / 8)), mask = (1 << bits) - 1
+	for (let i = 0, bit = 0; i < values.length; i++, bit += bits) {
+		let word = (values[i] & mask) << (bit & 7)
+		bytes[bit >> 3] |= word
+		if (word > 255) bytes[(bit >> 3) + 1] |= word >> 8
+	}
+	return bytes
+}
+
+export function unpack(bytes, bits, count) {
+	let values = new Int8Array(count), mask = (1 << bits) - 1, sign = 1 << (bits - 1)
+	for (let i = 0, bit = 0; i < count; i++, bit += bits) {
+		let v = ((bytes[bit >> 3] | bytes[(bit >> 3) + 1] << 8) >> (bit & 7)) & mask
+		values[i] = v >= sign ? v - (1 << bits) : v
+	}
+	return values
+}
+
+const toBase64 = bytes => { let s = ''; for (let i = 0; i < bytes.length; i += 0x8000) s += String.fromCharCode(...bytes.subarray(i, i + 0x8000)); return btoa(s) }
+const fromBase64 = text => Uint8Array.from(atob(text), c => c.charCodeAt(0))
+
+// catalog(entries, vectors, binding, info) → catalog JSON: entries are the metadata of each row
+// ({ name, … }), vectors their unit embeddings, binding the encoder's.
+export function catalog(entries, vectors, binding, { encoding = 'int8-base64', ...info } = {}) {
+	let bits = BITS[encoding], top = 2 ** (bits - 1) - 1, d = vectors[0]?.length
+	if (!bits) throw new Error(`neural-timbre: unknown encoding ${encoding}`)
+	if (entries.length !== vectors.length || !d) throw new Error('neural-timbre: one vector per entry')
+	let q = new Int8Array(vectors.length * d), scales = []
+	vectors.forEach((v, r) => {
+		let m = Math.max(...Array.from(v, Math.abs)) || 1, s = m / top
+		scales.push(+s.toPrecision(7))
+		for (let i = 0; i < d; i++) q[r * d + i] = Math.max(-top, Math.min(top, Math.round(v[i] / scales[r])))
+	})
+	return { version: 1, kind: 'timbre-catalog', ...binding, dimensions: d, ...info, entries,
+		vectors: { encoding, shape: [vectors.length, d], scales, data: toBase64(pack(q, bits)) } }
+}
+
+// readCatalog(json, binding) → { entries, vectors: Float32Array (rows unit), dimensions }; refuses a
+// catalog built by another encoder or frontend.
+export function readCatalog(data, binding) {
+	if (data?.kind !== 'timbre-catalog' || data.version !== 1) throw new Error('neural-timbre: not a timbre catalog')
+	if (binding && (data.encoderSha256 !== binding.encoderSha256 || data.featuresSha256 !== binding.featuresSha256))
+		throw new Error('neural-timbre: catalog was built with a different model: rebuild it with this one')
+	let { entries, dimensions: d, vectors: v } = data, bits = BITS[v?.encoding]
+	if (!bits || !Array.isArray(entries) || v.shape?.[0] !== entries.length || v.shape[1] !== d || v.scales?.length !== entries.length) throw new Error('neural-timbre: malformed catalog')
+	let bytes = fromBase64(v.data)
+	if (bytes.length !== Math.ceil(entries.length * d * bits / 8)) throw new Error('neural-timbre: truncated catalog vectors')
+	let q = unpack(bytes, bits, entries.length * d), out = new Float32Array(entries.length * d)
+	for (let r = 0; r < entries.length; r++) {
+		let s = 0
+		for (let i = 0; i < d; i++) { let x = q[r * d + i] * v.scales[r]; out[r * d + i] = x; s += x * x }
+		let n = Math.sqrt(s) || 1
+		for (let i = 0; i < d; i++) out[r * d + i] /= n
+	}
+	return { entries, vectors: out, dimensions: d }
+}
+
+// rank(embedding, catalog, top) → [{ index, score }] best first; ties by index
+export function rank(e, { vectors, dimensions: d }, top = 10) {
+	let n = vectors.length / d, scores = new Float32Array(n)
+	for (let r = 0; r < n; r++) { let s = 0; for (let i = 0; i < d; i++) s += e[i] * vectors[r * d + i]; scores[r] = s }
+	let order = Array.from({ length: n }, (_, i) => i).sort((a, b) => scores[b] - scores[a] || a - b)
+	return order.slice(0, top).map(index => ({ index, score: scores[index] }))
+}
+
+// A catalog's JSON: parsed JSON as given; a hosted catalog by name; a URL, or a path in Node.
+async function catalogJson(c, opts) {
+	let text = bytes => JSON.parse(new TextDecoder().decode(bytes))
+	if (typeof c === 'string' && !/[/\\.:]/.test(c)) {
+		if (!Object.hasOwn(catalogs, c)) throw new Error(`neural-timbre: no catalog '${c}' is hosted (${Object.keys(catalogs).join(', ')}): pass a URL, a path or parsed JSON`)
+		return text(await hosted(c, opts))
+	}
+	return typeof c === 'string' || c instanceof URL ? text(await bytesOf(c, { cache: false })) : c
+}
+
+// createMatcher(catalog, { model, backend, weights }) → { match(audio, { sampleRate, top }), catalog,
+// encoder, free }. catalog: a hosted one by name ('dx7-factory', the default, or 'dx7-all'), a URL,
+// a path in Node, or parsed JSON. It loads while the encoder does and must carry the encoder's binding.
+export async function createMatcher(catalog = 'dx7-factory', opts = {}) {
+	let data = catalogJson(catalog, opts)
+	data.catch(() => {}) // awaited once the encoder is up
+	let encoder = await createEncoder(opts)
+	try {
+		let cat = readCatalog(await data, encoder.binding)
+		return {
+			catalog: cat, encoder,
+			// best first: { ...entry, score } with score the cosine, -1 to 1
+			async match(audio, { sampleRate, top = 5 } = {}) {
+				let e = await encoder.embed(audio, { sampleRate })
+				return rank(e, cat, top).map(({ index, score }) => ({ ...cat.entries[index], score }))
+			},
+			free: encoder.free,
+		}
+	} catch (e) { encoder.free(); throw e }
+}
+
+// identify(audio, { sampleRate, top, catalog, model, backend }) → matches; loads and frees a
+// matcher per call.
+export default async function identify(audio, opts = {}) {
+	let m = await createMatcher(opts.catalog, opts)
+	try { return await m.match(audio, opts) } finally { m.free() }
+}