@aeonentertainment/mixer 0.0.0-stage → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,722 @@
+import { createRequire } from "node:module";
+import { isIP } from "node:net";
+// src/acks.ts
+/** How long a command may go unacknowledged before its promise rejects (docs/design.md 8.8). */
+const ACK_TIMEOUT_MS = 1e3;
+/** Commands in flight, each resolved by the ack that carries its id. */
+var Acks = class {
+	#pending = /* @__PURE__ */ new Map();
+	/**
+	* `state` describes the engine for the rejection when no ack comes, and `onTimeout` hears the
+	* same error; a command rejected any other way never reaches it.
+	*/
+	wait(id, state, onTimeout) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.#pending.delete(id);
+				const error = /* @__PURE__ */ new Error(`command ${id} was not acknowledged within ${ACK_TIMEOUT_MS} ms; the engine is ${state()}`);
+				reject(error);
+				onTimeout?.(error);
+			}, ACK_TIMEOUT_MS);
+			timer.unref();
+			this.#pending.set(id, {
+				resolve,
+				reject,
+				timer
+			});
+		});
+	}
+	resolve(id, positionFrames) {
+		const pending = this.#pending.get(id);
+		if (!pending) return;
+		clearTimeout(pending.timer);
+		this.#pending.delete(id);
+		pending.resolve(positionFrames);
+	}
+	rejectAll(error) {
+		for (const pending of this.#pending.values()) {
+			clearTimeout(pending.timer);
+			pending.reject(error);
+		}
+		this.#pending.clear();
+	}
+};
+// src/emitter.ts
+/** Typed listeners for one object's events. `on` returns the unsubscribe. */
+var Emitter = class {
+	#listeners = /* @__PURE__ */ new Map();
+	on(event, listener) {
+		let listeners = this.#listeners.get(event);
+		if (!listeners) {
+			listeners = /* @__PURE__ */ new Set();
+			this.#listeners.set(event, listeners);
+		}
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	emit(event, ...args) {
+		for (const listener of this.#listeners.get(event) ?? []) listener(...args);
+	}
+};
+// src/units.ts
+const FRAMES_PER_MS = 48;
+function msToFrames(ms) {
+	return Math.round(ms * FRAMES_PER_MS);
+}
+function framesToMs(frames) {
+	return frames / FRAMES_PER_MS;
+}
+// src/validate.ts
+const INGEST_KINDS = [
+	"rtp",
+	"l16",
+	"push"
+];
+/** A kind as a JavaScript caller may have spelt it, so an unknown one never crosses. */
+function ingestKind(name, value) {
+	const kind = INGEST_KINDS.find((known) => known === value);
+	if (kind === void 0) throw new RangeError(`${name} must be rtp, l16 or push, got ${value}`);
+	return kind;
+}
+/**
+* Where the mix goes: an IP literal, since resolving a name would block the control thread, and a
+* dynamic RTP payload type, since Opus has no static one.
+*/
+function rtpReturn(value) {
+	if (isIP(value.host) === 0) throw new TypeError(`rtpReturn.host must be an IP address, got ${value.host}`);
+	return {
+		host: value.host,
+		port: integerIn("rtpReturn.port", value.port, 1, 65535),
+		payloadType: integerIn("rtpReturn.payloadType", value.payloadType, 96, 127),
+		ssrc: integerIn("rtpReturn.ssrc", value.ssrc, 0, 4294967295)
+	};
+}
+function finiteIn(name, value, min, max) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number, got ${String(value)}`);
+	if (value < min || value > max) throw new RangeError(`${name} must be between ${min} and ${max}, got ${value}`);
+	return value;
+}
+function integerIn(name, value, min, max) {
+	if (!Number.isInteger(value)) throw new TypeError(`${name} must be an integer, got ${String(value)}`);
+	return finiteIn(name, value, min, max);
+}
+function pcm(name, value, channels) {
+	if (!(value instanceof Float32Array) || value.length === 0) throw new TypeError(`${name} must be a non-empty Float32Array`);
+	if (value.length % channels !== 0) throw new RangeError(`${name} must hold whole frames of ${channels} channels`);
+	return value;
+}
+// src/backing.ts
+/** `stopAtMs` fades the stems out over this before falling silent: docs/design.md section 4. */
+const STOP_FADE_MS = 3e3;
+/**
+* One mixer's backing path while it is armed: the render job on the worker thread and the
+* settings held for start. `install` moves the rendered stems into the mixer's graph.
+*/
+var Backing = class {
+	speed;
+	stopAtFrames;
+	/**
+	* Resolves when the render job is done. The stems are in the graph by the time anyone awaiting
+	* this runs, or `install` throws the render's error.
+	*/
+	rendered;
+	#rendering = true;
+	#installed = false;
+	#fraction = 0;
+	#failure = null;
+	#stemGains;
+	#render;
+	#graph;
+	/**
+	* Checks `config` and starts its render on the worker thread. The stems move into `graph` as
+	* soon as the job is done, so a render that fails is reported then and not at `start`.
+	*/
+	constructor(host, config, graph, report) {
+		this.#graph = graph;
+		const input = toInput(config);
+		this.speed = input.speed;
+		this.stopAtFrames = config.stopAtMs === void 0 ? void 0 : msToFrames(finiteIn("stopAtMs", config.stopAtMs, 0, Number.MAX_SAFE_INTEGER));
+		this.#stemGains = {
+			instrumental: finiteIn("stemGains.instrumental", config.stemGains.instrumental, 0, 4),
+			guide: finiteIn("stemGains.guideVocals", config.stemGains.guideVocals, 0, 4)
+		};
+		this.#render = host.native.startRender(input);
+		this.rendered = host.watchRender(this.#render.id, (fraction) => {
+			this.#fraction = fraction;
+			if (fraction < 1) report.progress(fraction);
+		});
+		this.rendered.then(() => {
+			this.#rendering = false;
+			try {
+				this.install();
+			} catch (error) {
+				this.#failure = error instanceof Error ? error : new Error(String(error));
+				report.failed(this.#failure);
+				return;
+			}
+			if (this.#fraction === 1) report.progress(1);
+		}, () => {});
+	}
+	/** Whether `install` would still wait on the worker thread. */
+	get rendering() {
+		return this.#rendering;
+	}
+	get stemGains() {
+		return this.#stemGains;
+	}
+	/**
+	* Moves the rendered stems into the graph, once; the graph keeps them through a refused swap.
+	* Throws the engine's message when the render failed, on every call.
+	*/
+	install() {
+		if (this.#failure) throw this.#failure;
+		if (this.#installed) return;
+		this.#graph.installBacking(this.#render);
+		this.#installed = true;
+	}
+	setStemGain(kind, gain) {
+		const checked = finiteIn(`${kind} gain`, gain, 0, 4);
+		this.#stemGains = kind === "instrumental" ? {
+			...this.#stemGains,
+			instrumental: checked
+		} : {
+			...this.#stemGains,
+			guide: checked
+		};
+		return this.#stemGains;
+	}
+};
+/** Half to double speed: what a speed control offers a singer. */
+const SPEED_RANGE = [.5, 2];
+function toInput(config) {
+	let instrumental;
+	let guide;
+	for (const { kind, path } of config.stems) {
+		if (typeof path !== "string" || path.length === 0) throw new TypeError(`backing.stems: the ${kind} stem needs a path`);
+		switch (kind) {
+			case "instrumental":
+				if (instrumental !== void 0) throw new RangeError("backing.stems holds two instrumental stems");
+				instrumental = path;
+				break;
+			case "guideVocals":
+				if (guide !== void 0) throw new RangeError("backing.stems holds two guideVocals stems");
+				guide = path;
+		}
+	}
+	if (instrumental === void 0) throw new RangeError("backing.stems needs an instrumental stem");
+	return {
+		instrumental,
+		...guide === void 0 ? {} : { guide },
+		semitones: integerIn("key", config.key, -12, 12),
+		speed: finiteIn("speed", config.speed, ...SPEED_RANGE)
+	};
+}
+// src/mixer.ts
+function defaultSlotParams() {
+	return {
+		gain: 1,
+		pan: 0,
+		mute: false,
+		solo: false,
+		corrector: {
+			enabled: false,
+			strength: 0,
+			retuneMs: 0
+		},
+		reverb: {
+			enabled: false,
+			roomSize: 0,
+			mix: 0
+		},
+		guideOffsetMs: 0
+	};
+}
+/**
+* One mixing graph for one performance. Its `rtp` and `l16` slots listen on their ports from
+* here until `destroy`; its return stream sends the mix from `start` until `destroy`. Settings
+* made while armed are kept here and written to the engine when `start` swaps the graph in, so
+* arming the next song never touches the live one.
+*/
+var Mixer = class {
+	/** Each slot's kind and, for `rtp` and `l16`, the UDP port it listens on; `null` for `push`. */
+	slots;
+	#host;
+	#native;
+	#events;
+	#params;
+	#guides;
+	#backing;
+	#offFault;
+	#phase = "armed";
+	#failed = false;
+	/**
+	* The mixer can no longer play its song: docs/design.md section 5. Fires once, and a mixer
+	* being destroyed has no song left to lose.
+	*/
+	#fail = (error) => {
+		if (this.#failed || this.#phase === "destroyed") return;
+		this.#failed = true;
+		this.#events.emit("error", error);
+	};
+	constructor(host, kinds, events, backing, rtpReturn) {
+		this.#host = host;
+		this.#events = events;
+		this.#native = host.native.createMixer([...kinds], rtpReturn);
+		this.slots = kinds.map((kind, index) => ({
+			index,
+			kind,
+			port: this.#native.port(index)
+		}));
+		this.#params = kinds.map(defaultSlotParams);
+		this.#guides = kinds.map(() => null);
+		this.#backing = backing === null ? null : new Backing(host, backing, this.#native, {
+			progress: (fraction) => {
+				if (this.#phase !== "destroyed") this.#events.emit("renderProgress", fraction);
+			},
+			failed: this.#fail
+		});
+		this.#offFault = host.onFault(this.#fail);
+	}
+	setSlot(index, settings) {
+		const slot = this.#slot(index);
+		const current = this.#paramsOf(slot);
+		this.#write(slot, {
+			...current,
+			gain: settings.gain === void 0 ? current.gain : finiteIn("gain", settings.gain, 0, 4),
+			pan: settings.pan === void 0 ? current.pan : finiteIn("pan", settings.pan, -1, 1),
+			mute: settings.mute ?? current.mute,
+			solo: settings.solo ?? current.solo
+		});
+	}
+	/** The slot's whole chain: an effect not in `effects` is disabled. */
+	setSlotEffects(index, effects) {
+		const slot = this.#slot(index);
+		const next = {
+			...this.#paramsOf(slot),
+			...defaultEffects()
+		};
+		for (const effect of effects) switch (effect.kind) {
+			case "pitch-correction":
+				next.corrector = {
+					enabled: effect.enabled,
+					strength: finiteIn("strength", effect.strength, 0, 1),
+					retuneMs: finiteIn("retuneMs", effect.retuneMs, 0, 1e3)
+				};
+				break;
+			case "reverb": next.reverb = {
+				enabled: effect.enabled,
+				roomSize: finiteIn("roomSize", effect.roomSize, 0, 1),
+				mix: finiteIn("mix", effect.mix, 0, 1)
+			};
+		}
+		this.#write(slot, next);
+	}
+	setSlotGuide(index, guide, guideOffsetMs) {
+		const slot = this.#slot(index);
+		const input = guide === null ? null : toGuideInput(guide);
+		if (guideOffsetMs !== void 0) this.#write(slot, {
+			...this.#paramsOf(slot),
+			guideOffsetMs: finiteIn("guideOffsetMs", guideOffsetMs, -1e3, 1e3)
+		});
+		this.#guides[slot] = input;
+		if (this.#host.isLive(this)) this.#host.native.setGuide(slot, input);
+	}
+	/**
+	* Forget the stream a slot was hearing; the next packets, or the next pushed audio, are a new
+	* singer. An armed mixer has heard nothing yet, so there is nothing to forget.
+	*/
+	resetSlot(index) {
+		const slot = this.#slot(index);
+		if (this.#host.isLive(this)) this.#host.native.resetSlot(slot);
+	}
+	/**
+	* Writes every datagram that reaches an `rtp` or `l16` slot's port to a new pcap file at `path`,
+	* with the moment the network thread read it, until `null`, another path or `destroy`. The file
+	* is created here and never over an existing one, so a bad path throws. A recording holds a
+	* singer's voice and their phone's LAN address: it is made only when a person asks for one, and
+	* nothing in this package sends it anywhere. Start it after `start`, so a replay begins where
+	* the live slot did. docs/design.md 8.4.
+	*/
+	recordSlot(index, path) {
+		const slot = this.#slot(index);
+		if (this.slots[slot]?.kind === "push") throw new Error(`slot ${slot} is a push slot; only rtp and l16 slots record`);
+		if (this.#phase === "destroyed") throw new Error("the mixer is destroyed");
+		if (path === "") throw new RangeError("path must name a file");
+		this.#native.recordSlot(slot, path);
+	}
+	/**
+	* Hands interleaved stereo PCM to a push slot, folded to mono as every slot is. Returns the
+	* frames taken; the rest did not fit and is dropped, since late audio is worse than lost audio.
+	* Throws on a slot of another kind.
+	*/
+	push(index, stereo) {
+		const slot = this.#slot(index);
+		const kind = this.slots[slot]?.kind;
+		if (kind !== "push") throw new Error(`slot ${slot} is ${String(kind)}; only a push slot takes pushed audio`);
+		if (this.#phase === "destroyed") throw new Error("the mixer is destroyed");
+		return this.#native.push(slot, pcm("stereo", stereo, 2));
+	}
+	/**
+	* Waits for the backing's render and swaps the graph in; a render that failed rejects with the
+	* message `error` carried. With the render already done, the swap is sent before this returns
+	* to the caller. Nothing is written to the engine while another mixer is live, so a refused
+	* start leaves the song playing untouched.
+	*/
+	async start() {
+		if (this.#phase !== "armed") throw new Error(`the mixer cannot start: it is ${this.#phase}`);
+		this.#phase = "starting";
+		let swapped;
+		try {
+			if (this.#backing?.rendering) await this.#backing.rendered;
+			if (this.#host.anyLive()) throw new Error("another mixer is live; destroy it first");
+			this.#backing?.install();
+			this.#params.forEach((params, slot) => {
+				this.#host.native.setSlotParams(slot, params);
+			});
+			if (this.#backing) this.#host.native.setStemGains(this.#backing.stemGains);
+			swapped = this.#host.swapIn(this, this.#native, this.#events, this.#fail);
+		} catch (error) {
+			if (this.#phase === "starting") this.#phase = "armed";
+			throw error;
+		}
+		this.#phase = "live";
+		this.#guides.forEach((guide, slot) => {
+			if (guide) this.#host.native.setGuide(slot, guide);
+		});
+		const started = this.#command(() => this.#host.native.start());
+		const stopAtFrames = this.#backing?.stopAtFrames;
+		const stopping = stopAtFrames === void 0 ? void 0 : this.#command(() => this.#host.native.stopAt(stopAtFrames, msToFrames(STOP_FADE_MS)));
+		await Promise.all([
+			swapped,
+			started,
+			stopping
+		]);
+		const { latencyMs } = this.#host.output;
+		return {
+			startedAt: Date.now() + latencyMs,
+			backingOffsetMs: latencyMs,
+			speedFactor: this.#backing?.speed ?? 1
+		};
+	}
+	/** Resolves with the position the seek landed on, once its fade out is done. */
+	async seek(toMs) {
+		const toFrame = msToFrames(finiteIn("toMs", toMs, 0, Number.MAX_SAFE_INTEGER));
+		const native = this.#liveBacking();
+		return { positionMs: framesToMs(await this.#command(() => native.seek(toFrame))) };
+	}
+	/** Resolves once the fade out is done and the playhead holds. */
+	async pause() {
+		const native = this.#liveBacking();
+		await this.#command(() => native.pause());
+	}
+	async resume() {
+		const native = this.#liveBacking();
+		return { positionMs: framesToMs(await this.#command(() => native.resume())) };
+	}
+	/** The live key, on top of the armed one; its crossfade follows the ack. */
+	async setBackingKey(semitones) {
+		const checked = integerIn("semitones", semitones, -12, 12);
+		const native = this.#liveBacking();
+		await this.#command(() => native.setKey(checked));
+	}
+	/** A parameter write, held while armed like the slot settings. */
+	setStemGain(kind, gain) {
+		if (!this.#backing) throw new Error("this mixer has no backing");
+		const gains = this.#backing.setStemGain(kind, gain);
+		if (this.#host.isLive(this)) this.#host.native.setStemGains(gains);
+	}
+	on(event, listener) {
+		return this.#events.on(event, listener);
+	}
+	/**
+	* Each slot's ingest counters as the audio thread last published them, the engine's underruns,
+	* and the blocks the return stream dropped, `null` without one.
+	*/
+	stats() {
+		return {
+			slots: this.#native.stats(),
+			underruns: this.#host.underruns(),
+			rtpReturn: this.#native.returnStats()
+		};
+	}
+	/**
+	* Closes the slots' ports, stops the return stream, swaps the silent graph in when this one is
+	* live, and resolves once this graph is back and dropped.
+	*/
+	async destroy() {
+		switch (this.#phase) {
+			case "destroyed": return;
+			case "starting":
+				if (!this.#failed) throw new Error("the mixer is starting; await start before destroying it");
+				this.#release();
+				return;
+			case "armed":
+				this.#release();
+				return;
+			case "live":
+				this.#release();
+				await this.#host.swapOut(this);
+		}
+	}
+	#release() {
+		this.#phase = "destroyed";
+		this.#offFault();
+		this.#native.release();
+	}
+	#command(send) {
+		return this.#host.command(send, this.#fail);
+	}
+	#slot(index) {
+		return integerIn("slot", index, 0, this.slots.length - 1);
+	}
+	/** The engine, once this mixer's backing is the live one. */
+	#liveBacking() {
+		if (!this.#backing) throw new Error("this mixer has no backing");
+		if (!this.#host.isLive(this)) throw new Error(`the backing cannot be steered: the mixer is ${this.#phase}`);
+		return this.#host.native;
+	}
+	#paramsOf(slot) {
+		const params = this.#params[slot];
+		if (!params) throw new RangeError(`no slot ${slot}`);
+		return params;
+	}
+	#write(slot, params) {
+		this.#params[slot] = params;
+		if (this.#host.isLive(this)) this.#host.native.setSlotParams(slot, params);
+	}
+};
+function defaultEffects() {
+	const { corrector, reverb } = defaultSlotParams();
+	return {
+		corrector,
+		reverb
+	};
+}
+function toGuideInput(guide) {
+	return {
+		keyMask: integerIn("keyMask", guide.keyMask, 0, 4095),
+		notes: guide.notes.map((note, i) => {
+			const startMs = finiteIn(`notes[${i}].startMs`, note.startMs, 0, Number.MAX_SAFE_INTEGER);
+			return {
+				midi: integerIn(`notes[${i}].midi`, note.midi, 0, 127),
+				startFrame: msToFrames(startMs),
+				endFrame: msToFrames(finiteIn(`notes[${i}].endMs`, note.endMs, startMs, Number.MAX_SAFE_INTEGER))
+			};
+		})
+	};
+}
+const NativeEngine = createRequire(import.meta.url)("../native/binding/index.js").Engine;
+// src/engine.ts
+async function openEngine(options) {
+	return new Engine(options);
+}
+var Engine = class {
+	capabilities = /* @__PURE__ */ new Set([
+		"guideVocal",
+		"key",
+		"speed",
+		"seek",
+		"shortVersion",
+		"pause",
+		"level"
+	]);
+	output;
+	/** How many slots a mixer may have, fixed at open. */
+	#slots;
+	/** Offline engines only: render blocks and return them as interleaved stereo. */
+	pump;
+	#native;
+	#host;
+	#acks = new Acks();
+	#events = new Emitter();
+	/** Swaps in flight, oldest first; a `retired` event completes the oldest. */
+	#retirements = [];
+	/** Render jobs on the worker thread, by the id their progress events carry. */
+	#renders = /* @__PURE__ */ new Map();
+	#live = null;
+	#underruns = 0;
+	#state = "running";
+	constructor(options) {
+		this.#slots = integerIn("slots", options.slots ?? 8, 1, 16);
+		const playoutDelayFrames = msToFrames(finiteIn("playoutDelayMs", options.playoutDelayMs ?? 15, 5, 100));
+		const deliver = (batch) => {
+			this.#deliver(batch);
+		};
+		if ("offline" in options.output) {
+			this.#native = new NativeEngine({
+				clock: "offline",
+				periodFrames: 128,
+				playoutDelayFrames
+			}, deliver);
+			this.pump = (blocks) => this.#native.pump(integerIn("blocks", blocks, 1, 1 << 20));
+		} else if ("timer" in options.output) this.#native = new NativeEngine({
+			clock: "timer",
+			periodFrames: 128,
+			playoutDelayFrames
+		}, deliver);
+		else {
+			const { device, periodFrames = 128 } = options.output;
+			if (periodFrames !== 64 && periodFrames !== 128) throw new RangeError(`periodFrames must be 64 or 128, got ${String(periodFrames)}`);
+			this.#native = new NativeEngine({
+				clock: "device",
+				periodFrames,
+				playoutDelayFrames,
+				...device === void 0 ? {} : { device }
+			}, deliver);
+		}
+		this.output = outputInfo(this.#native.output);
+		this.#host = {
+			native: this.#native,
+			output: this.output,
+			command: (send, onTimeout) => this.#command(send, onTimeout),
+			watchRender: (id, onProgress) => new Promise((resolve, reject) => {
+				this.#renders.set(id, {
+					onProgress,
+					resolve,
+					reject
+				});
+			}),
+			swapIn: (mixer, graph, events, onTimeout) => this.#swapIn(mixer, graph, events, onTimeout),
+			swapOut: (mixer) => this.#swapOut(mixer),
+			onFault: (listener) => this.#events.on("fault", listener),
+			isLive: (mixer) => this.#live?.mixer === mixer,
+			anyLive: () => this.#live !== null,
+			underruns: () => this.#underruns
+		};
+	}
+	/** Room-lifetime reaction voices, four at once. False when a fifth is dropped while four play. */
+	reactions = { play: (samples, channels) => {
+		if (channels !== 1 && channels !== 2) throw new RangeError(`channels must be 1 or 2, got ${String(channels)}`);
+		pcm("samples", samples, channels);
+		this.#assertRunning();
+		return this.#native.playReaction(channels === 2 ? samples : monoToStereo(samples));
+	} };
+	async outputDevices() {
+		this.#assertRunning();
+		return this.#native.outputs();
+	}
+	async createMixer(config) {
+		this.#assertRunning();
+		if (config.slots.length > this.#slots) throw new RangeError(`the engine has ${this.#slots} slots; the mixer asks for ${config.slots.length}`);
+		const kinds = config.slots.map(({ kind }, i) => ingestKind(`slots[${i}].kind`, kind));
+		const destination = config.rtpReturn === void 0 ? null : rtpReturn(config.rtpReturn);
+		return new Mixer(this.#host, kinds, new Emitter(), config.backing ?? null, destination);
+	}
+	on(event, listener) {
+		return this.#events.on(event, listener);
+	}
+	/** Destroys the live mixer, stops the clock and joins the events thread. */
+	async close() {
+		if (this.#state === "closed") return;
+		if (this.#live && this.#state === "running") await this.#live.mixer.destroy();
+		this.#state = "closed";
+		this.#native.close();
+		this.#stop(/* @__PURE__ */ new Error("the engine is closed"));
+	}
+	#swapIn(mixer, graph, events, onTimeout) {
+		if (this.#live) throw new Error("another mixer is live; destroy it first");
+		const swapped = this.#command(() => this.#native.swap(graph), onTimeout);
+		this.#live = {
+			mixer,
+			events
+		};
+		this.#retirements.push(() => {});
+		return swapped;
+	}
+	async #swapOut(mixer) {
+		if (this.#live?.mixer !== mixer) return;
+		if (this.#state !== "running") {
+			this.#live = null;
+			return;
+		}
+		const swapped = this.#command(() => this.#native.swapSilent());
+		this.#live = null;
+		const retired = new Promise((resolve) => this.#retirements.push(resolve));
+		await swapped;
+		await retired;
+	}
+	#command(send, onTimeout) {
+		this.#assertRunning();
+		return this.#acks.wait(send(), () => this.#state, onTimeout);
+	}
+	#assertRunning() {
+		if (this.#state !== "running") throw new Error(this.#state === "faulted" ? "the engine has faulted; close it and open it again" : "the engine is closed");
+	}
+	#deliver(batch) {
+		if (this.#state === "closed") return;
+		for (const event of batch) switch (event.kind) {
+			case "ack":
+				this.#acks.resolve(event.id, event.positionFrames);
+				break;
+			case "level":
+				this.#live?.events.emit("level", event.slot, event.rmsDb, event.peakDb);
+				break;
+			case "pitch":
+				this.#live?.events.emit("pitch", event.slot, event.positionMs, event.hz, event.confidence);
+				break;
+			case "position":
+				this.#live?.events.emit("position", framesToMs(event.frames));
+				break;
+			case "backingEnded":
+				this.#live?.events.emit("backingEnded");
+				break;
+			case "masterLevel":
+				this.#events.emit("masterLevel", event.rmsDb, event.peakDb);
+				break;
+			case "underrun":
+				this.#underruns += 1;
+				break;
+			case "fault":
+				this.#fault();
+				break;
+			case "retired":
+				this.#retirements.shift()?.();
+				break;
+			case "renderProgress":
+				this.#renders.get(event.job)?.onProgress(event.fraction);
+				break;
+			case "renderFinished": {
+				const render = this.#renders.get(event.job);
+				this.#renders.delete(event.job);
+				render?.resolve();
+				break;
+			}
+		}
+	}
+	/**
+	* A device loss or a caught panic: the host closes and reopens; nothing here recovers. `fault`
+	* reaches the host's listeners and every mixer not yet destroyed, each of which emits `error`.
+	*/
+	#fault() {
+		if (this.#state !== "running") return;
+		this.#state = "faulted";
+		const error = /* @__PURE__ */ new Error("the engine has faulted; close it and open it again");
+		this.#stop(error);
+		this.#events.emit("fault", error);
+	}
+	/** Nothing in flight will be answered: the commands and the renders waited on reject. */
+	#stop(error) {
+		this.#acks.rejectAll(error);
+		for (const render of this.#renders.values()) render.reject(error);
+		this.#renders.clear();
+	}
+};
+function outputInfo(info) {
+	if (info.sampleRate !== 48e3) throw new Error(`the engine runs at 48 kHz; the addon reports ${info.sampleRate}`);
+	return {
+		sampleRate: 48e3,
+		periodFrames: info.periodFrames,
+		latencyMs: info.latencyMs
+	};
+}
+function monoToStereo(mono) {
+	const stereo = new Float32Array(mono.length * 2);
+	mono.forEach((sample, i) => {
+		stereo[2 * i] = sample;
+		stereo[2 * i + 1] = sample;
+	});
+	return stereo;
+}
+export { Engine, Mixer, openEngine };