@aeonentertainment/mixer 0.4.0 → 0.6.0

package/README.md

@@ -15,7 +15,7 @@ Each [release](https://github.com/aeonentertainment/aeon-mixer/releases) carries
 Depend on its URL, and the lockfile pins its hash:
 
 ```bash
-npm install https://github.com/aeonentertainment/aeon-mixer/releases/download/v0.4.0/aeonentertainment-mixer-0.4.0.tgz
+npm install https://github.com/aeonentertainment/aeon-mixer/releases/download/v0.6.0/aeonentertainment-mixer-0.6.0.tgz
 ```
 
 ## Use
@@ -50,9 +50,11 @@ await engine.close();
 
 - **Slots** are the mics: 8 per engine by default, up to 16 with `openEngine({ slots })`. `rtp`
   takes Opus over UDP from a phone or mediasoup, `l16` takes raw PCM over loopback from a house
-  mic, and `push` takes PCM the host hands to `mixer.push`. Each slot has gain, pan, mute, solo,
-  reverb, a pitch reading, a melody guide and pitch correction toward it, whose delay `stats()`
-  reports.
+  mic's sender, `capture` takes a mic on this machine by an id from `engine.inputDevices()`, and
+  `push` takes PCM the host hands to `mixer.push`. Each slot has gain, pan, mute, solo, reverb,
+  a pitch reading, a melody guide and pitch correction toward it, whose delay `stats()` reports.
+  A slot can also take the room's echo of the mix out of its input and duck itself when its loop
+  through the speakers starts to howl; both add no delay, and `stats()` reports what they found.
 - **The backing** is any format Symphonia decodes, resampled to 48 kHz. The armed key and speed
   are rendered before `start` resolves. Live, it supports seek, pause, resume, a key change and
   stem gains, and `start`, `seek` and `resume` report the position the lyric clock follows.

package/dist/index.d.mts

@@ -13,15 +13,22 @@ declare class Engine$1 {
    */
   constructor(options: OpenOptions, onEvents: (arg: Array<NativeEvent>) => void);
   /**
-   * Builds a mixer with one slot per kind, in order: `"rtp"`, `"l16"` or `"push"`. The rtp
-   * and l16 slots bind their ports here and report them through `Mixer.port`; a return stream
-   * gets its socket and send task here too.
+   * Builds a mixer with one slot per input, in order: `"rtp"`, `"l16"`, `"push"` or
+   * `"capture"`. The rtp and l16 slots bind their ports here and report them through
+   * `Mixer.port`, the capture slots start their inputs here, and a return stream gets its socket
+   * and send task here too.
    */
-  createMixer(kinds: Array<string>, rtpReturn?: RtpReturnInput | undefined | null): Mixer$1;
+  createMixer(slots: Array<SlotInput>, rtpReturn?: RtpReturnInput | undefined | null): Mixer$1;
   /** The output playing now. After a move the events thread sends the same as `outputChanged`. */
   get output(): OutputInfo$1;
   /** The outputs this OS offers, the default marked. Empty on the offline and timer clocks. */
   outputs(): Array<OutputEntry>;
+  /**
+   * The inputs this OS offers, the default marked: the devices a `capture` slot may name. Empty
+   * on the offline clock, which opens none. A box on the timer clock plays nothing locally but
+   * may still have a mic plugged in.
+   */
+  inputs(): Array<OutputEntry>;
   /** Offline clock only: renders `blocks` blocks and returns them as interleaved stereo. */
   pump(blocks: number): Float32Array;
   /** Writes one slot of the snapshot and publishes the whole of it. */
@@ -61,7 +68,7 @@ declare class Engine$1 {
 declare class Mixer$1 {
   /** Moves a finished render's stems into the graph as its backing path, before `swap`. */
   installBacking(render: BackingRender): void;
-  /** The UDP port a slot listens on, or null for a push slot. */
+  /** The UDP port a slot listens on, or null for a push or capture slot. */
   port(index: number): number | null;
   /**
    * Hands interleaved stereo PCM to a push slot, which folds it to mono as every slot is
@@ -73,7 +80,10 @@ declare class Mixer$1 {
    * recording it for null.
    */
   recordSlot(index: number, path?: string | undefined | null): void;
-  /** Every slot's ingest counters and corrector delay, as the audio thread last published them. */
+  /**
+   * Every slot's ingest counters, corrector delay and echo findings, as the audio thread last
+   * published them.
+   */
   stats(): Array<SlotStatsInfo>;
   /** The return stream's counters, or null for a mixer without one. */
   returnStats(): RtpReturnStats | null;
@@ -91,11 +101,23 @@ interface BackingInput {
   /** The armed speed factor, rendered before start. */
   speed: number;
 }
+interface CleanupInput {
+  enabled: boolean;
+}
 interface CorrectorInput {
   enabled: boolean;
   strength: number;
   retuneMs: number;
 }
+/** What a slot's echo canceller has found, as JavaScript reads it. */
+interface EchoInfo {
+  /** From the master being rendered to its echo reaching the slot. */
+  pathMs: number;
+  /** How far under the master the echo arrives, over the last second. */
+  bleedDb: number;
+  /** How much quieter the slot came out than it went in, over the last second. */
+  removedDb: number;
+}
 interface GuideInput {
   notes: Array<NoteInput>;
   /** The key's pitch classes as bits, C in bit 0. */
@@ -155,8 +177,11 @@ interface OpenOptions {
   /** A device clock's output: an id from `outputs` to pin, or none to follow the default output. */
   device?: string;
   periodFrames: number;
-  /** The jitter buffer's playout delay for every `rtp` and `l16` slot. */
-  playoutDelayFrames: number;
+  /**
+   * Pins the jitter buffer's playout delay for every `rtp` and `l16` slot. Without it, each
+   * stream chooses its own.
+   */
+  playoutDelayFrames?: number;
 }
 interface OutputDevice {
   id: string;
@@ -192,6 +217,15 @@ interface RtpReturnStats {
   /** Blocks the audio thread dropped because the network thread had not drained the ring. */
   droppedBlocks: number;
 }
+/**
+ * One slot as `createMixer` asks for it. `device` and `channel` belong to a `capture` slot: an id
+ * from `inputs`, or the default input, and the device's channel from 0.
+ */
+interface SlotInput {
+  kind: string;
+  device?: string;
+  channel?: number;
+}
 interface SlotParamsInput {
   /** Linear amplitude. */
   gain: number;
@@ -202,6 +236,9 @@ interface SlotParamsInput {
   corrector: CorrectorInput;
   reverb: ReverbInput;
   voice: VoiceInput;
+  echoCancel: SwitchInput;
+  cleanup: CleanupInput;
+  howlGuard: SwitchInput;
   guideOffsetMs: number;
 }
 /** `SlotStats` as JavaScript reads it. */
@@ -209,16 +246,25 @@ interface SlotStatsInfo {
   pushed: number;
   lost: number;
   late: number;
+  lateAtOpening: number;
   concealed: number;
   resyncs: number;
   jitterMs: number;
   correctorDelayMs: number;
   correctorMaxDelayMs: number;
+  /** Null while the canceller is off or has yet to find and learn the room's echo. */
+  echo: EchoInfo | null;
+  playoutDelayMs: number;
+  howlCatches: number;
 }
 interface StemGainsInput {
   instrumental: number;
   guide: number;
 }
+/** An effect with no knob but on and off. */
+interface SwitchInput {
+  enabled: boolean;
+}
 interface VoiceInput {
   enabled: boolean;
   formantSemitones: number;
@@ -227,7 +273,7 @@ declare const NativeEngine: typeof Engine$1;
 type NativeEngine = Engine$1;
 type NativeMixer = Mixer$1;
 type Capability = "guideVocal" | "key" | "speed" | "seek" | "shortVersion" | "pause" | "level";
-type IngestKind = "rtp" | "l16" | "push";
+type IngestKind = "rtp" | "l16" | "push" | "capture";
 type StemKind = "instrumental" | "guideVocals";
 interface OpenEngineOptions {
   /**
@@ -245,7 +291,10 @@ interface OpenEngineOptions {
   };
   /** Fixed for the engine's life, default 8, at most 16. */
   slots?: number;
-  /** The ingest jitter buffer, default 15. */
+  /**
+   * Pins the ingest jitter buffer to this delay. Leave it out and each slot chooses its own from
+   * what its stream shows, opening at 15; `stats()` reports where each one is.
+   */
   playoutDelayMs?: number;
 }
 interface OutputInfo {
@@ -258,10 +307,20 @@ interface OutputInfo {
     readonly name: string;
   } | null;
 }
+/**
+ * One slot as a mixer asks for it. A `capture` slot is an input on this machine, a house mic:
+ * `device` is an id from `inputDevices()`, the default input when left out, and `channel` the
+ * device's channel from 0, default 0.
+ */
+type SlotConfig = {
+  kind: Exclude<IngestKind, "capture">;
+} | {
+  kind: "capture";
+  device?: string;
+  channel?: number;
+};
 interface MixerConfig {
-  slots: ReadonlyArray<{
-    kind: IngestKind;
-  }>;
+  slots: ReadonlyArray<SlotConfig>;
   backing?: {
     stems: ReadonlyArray<{
       kind: StemKind;
@@ -308,6 +367,24 @@ type SlotEffect = {
   kind: "voice";
   enabled: boolean;
   formantSemitones: number;
+} |
+/** Takes the room's echo of the mix out of the slot's input, with no added delay. */
+{
+  kind: "echo-cancel";
+  enabled: boolean;
+} |
+/**
+ * A high-pass and gate ahead of the corrector and a compressor after the meter. None reads
+ * ahead or buffers; decision 0012 has their numbers and costs.
+ */
+{
+  kind: "cleanup";
+  enabled: boolean;
+} |
+/** Ducks the slot when its loop through the speakers starts to howl, with no added delay. */
+{
+  kind: "howl-guard";
+  enabled: boolean;
 };
 interface MelodyGuide {
   notes: ReadonlyArray<{
@@ -322,6 +399,8 @@ interface SlotStats {
   pushed: number;
   lost: number;
   late: number;
+  /** Of `late`, the packets that would also have been late had the delay stayed where it opened. */
+  lateAtOpening: number;
   concealed: number;
   resyncs: number;
   jitterMs: number;
@@ -332,6 +411,25 @@ interface SlotStats {
   correctorDelayMs: number;
   /** The most that delay can reach; 0 with correction off. It holds still, so a budget adds this. */
   correctorMaxDelayMs: number;
+  /**
+   * What the echo canceller found: `pathMs` from the mix being rendered to its echo reaching the
+   * slot, `bleedDb` how far under the mix that echo arrives, `removedDb` how much quieter the slot
+   * came out than it went in, both over the last second. Null while it is off, or until it has
+   * found the echo and learned it.
+   */
+  echo: {
+    pathMs: number;
+    bleedDb: number;
+    removedDb: number;
+  } | null;
+  /**
+   * The delay the stream's earliest packets wait now; zero for a `push` slot. A `capture` slot
+   * has no jitter buffer: this is how long its mic's samples wait from the input to the mix, the
+   * input's period included, and zero until it first plays.
+   */
+  playoutDelayMs: number;
+  /** How often the howl guard has ducked this slot. */
+  howlCatches: number;
 }
 type EngineEvents = {
   fault: (error: Error) => void;
@@ -393,25 +491,33 @@ interface MixerHost extends RenderHost {
   swapOut(mixer: Mixer): Promise<void>;
   /** Hears the engine's fault until the returned function is called. */
   onFault(listener: (error: Error) => void): () => void;
+  /**
+   * Holds `release` until the returned function is called, and calls it when the engine closes:
+   * a mixer's capture inputs and ports outlive no engine, whatever state the mixer is in.
+   */
+  hold(release: () => void): () => void;
   isLive(mixer: Mixer): boolean;
   anyLive(): boolean;
   underruns(): number;
 }
 /**
- * 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
+ * One mixing graph for one performance. Its `rtp` and `l16` slots listen on their ports, and its
+ * `capture` slots hold their inputs open, 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.
  */
 export declare class Mixer {
   #private;
-  /** Each slot's kind and, for `rtp` and `l16`, the UDP port it listens on; `null` for `push`. */
+  /** Each slot's kind and, for `rtp` and `l16`, the UDP port it listens on; `null` for the rest. */
   readonly slots: ReadonlyArray<{
     index: number;
     kind: IngestKind;
     port: number | null;
   }>;
-  constructor(host: MixerHost, kinds: ReadonlyArray<IngestKind>, events: Emitter<MixerEvents>, backing: BackingConfig | null, rtpReturn: RtpReturnInput | null);
+  constructor(host: MixerHost, inputs: ReadonlyArray<SlotInput & {
+    kind: IngestKind;
+  }>, events: Emitter<MixerEvents>, backing: BackingConfig | null, rtpReturn: RtpReturnInput | null);
   setSlot(index: number, settings: Partial<SlotSettings>): void;
   /** The slot's whole chain: an effect not in `effects` is disabled. */
   setSlotEffects(index: number, effects: ReadonlyArray<SlotEffect>): void;
@@ -510,9 +616,15 @@ export declare class Engine {
     name: string;
     isDefault: boolean;
   }>>;
+  /** The inputs a `capture` slot may name, the default marked. None on an offline engine. */
+  inputDevices(): Promise<ReadonlyArray<{
+    id: string;
+    name: string;
+    isDefault: boolean;
+  }>>;
   createMixer(config: MixerConfig): Promise<Mixer>;
   on<K extends keyof EngineEvents>(event: K, listener: EngineEvents[K]): () => void;
   /** Destroys the live mixer, stops the clock and joins the events thread. */
   close(): Promise<void>;
 }
-export type { Capability, EngineEvents, IngestKind, MelodyGuide, MixerConfig, MixerEvents, OfflineEngine, OpenEngineOptions, OutputInfo, SlotEffect, SlotSettings, SlotStats, StemKind };
+export type { Capability, EngineEvents, IngestKind, MelodyGuide, MixerConfig, MixerEvents, OfflineEngine, OpenEngineOptions, OutputInfo, SlotConfig, SlotEffect, SlotSettings, SlotStats, StemKind };

package/dist/index.mjs

@@ -72,14 +72,27 @@ function framesToMs(frames) {
 const INGEST_KINDS = [
 	"rtp",
 	"l16",
-	"push"
+	"push",
+	"capture"
 ];
 /** 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}`);
+	if (kind === void 0) throw new RangeError(`${name} must be rtp, l16, push or capture, got ${value}`);
 	return kind;
 }
+/** A slot as the addon takes it: its kind, and for a `capture` slot its device and channel. */
+function slotInput(name, slot) {
+	const kind = ingestKind(`${name}.kind`, slot.kind);
+	if (slot.kind !== "capture") return { kind };
+	const { device, channel = 0 } = slot;
+	if (device !== void 0 && (typeof device !== "string" || device === "")) throw new TypeError(`${name}.device must be an id from inputDevices()`);
+	return {
+		kind,
+		channel: integerIn(`${name}.channel`, channel, 0, 255),
+		...device === void 0 ? {} : { device }
+	};
+}
 /**
 * 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.
@@ -108,6 +121,20 @@ function pcm(name, value, channels) {
 	return value;
 }
 // src/backing.ts
+/**
+* `config` checked, before anything opens: a mixer runs this ahead of its native mixer, so bad
+* backing settings reject `createMixer` with no port bound and no input held.
+*/
+function backingSettings(config) {
+	return {
+		input: toInput(config),
+		stopAtFrames: config.stopAtMs === void 0 ? void 0 : msToFrames(finiteIn("stopAtMs", config.stopAtMs, 0, Number.MAX_SAFE_INTEGER)),
+		stemGains: {
+			instrumental: finiteIn("stemGains.instrumental", config.stemGains.instrumental, 0, 4),
+			guide: finiteIn("stemGains.guideVocals", config.stemGains.guideVocals, 0, 4)
+		}
+	};
+}
 /** `stopAtMs` fades the stems out over this before falling silent: docs/design.md section 4. */
 const STOP_FADE_MS = 3e3;
 /**
@@ -130,18 +157,15 @@ var Backing = class {
 	#render;
 	#graph;
 	/**
-	* Checks `config` and starts its render on the worker thread. The stems move into `graph` as
+	* Starts the render of checked `settings` 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) {
+	constructor(host, settings, graph, report) {
 		this.#graph = graph;
-		const input = toInput(config);
+		const { input, stopAtFrames, stemGains } = settings;
 		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.stopAtFrames = stopAtFrames;
+		this.#stemGains = stemGains;
 		this.#render = host.native.startRender(input);
 		this.rendered = host.watchRender(this.#render.id, (fraction) => {
 			this.#fraction = fraction;
@@ -234,17 +258,21 @@ function defaultSlotParams() {
 			enabled: false,
 			formantSemitones: 0
 		},
+		echoCancel: { enabled: false },
+		cleanup: { enabled: false },
+		howlGuard: { enabled: false },
 		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
+* One mixing graph for one performance. Its `rtp` and `l16` slots listen on their ports, and its
+* `capture` slots hold their inputs open, 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`. */
+	/** Each slot's kind and, for `rtp` and `l16`, the UDP port it listens on; `null` for the rest. */
 	slots;
 	#host;
 	#native;
@@ -253,6 +281,7 @@ var Mixer = class {
 	#guides;
 	#backing;
 	#offFault;
+	#letGo;
 	#phase = "armed";
 	#failed = false;
 	/**
@@ -264,18 +293,20 @@ var Mixer = class {
 		this.#failed = true;
 		this.#events.emit("error", error);
 	};
-	constructor(host, kinds, events, backing, rtpReturn) {
+	constructor(host, inputs, events, backing, rtpReturn) {
 		this.#host = host;
 		this.#events = events;
-		this.#native = host.native.createMixer([...kinds], rtpReturn);
-		this.slots = kinds.map((kind, index) => ({
+		const settings = backing === null ? null : backingSettings(backing);
+		this.#native = host.native.createMixer([...inputs], rtpReturn);
+		this.#letGo = host.hold(() => this.#release());
+		this.slots = inputs.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, {
+		this.#params = inputs.map(defaultSlotParams);
+		this.#guides = inputs.map(() => null);
+		this.#backing = settings === null ? null : new Backing(host, settings, this.#native, {
 			progress: (fraction) => {
 				if (this.#phase !== "destroyed") this.#events.emit("renderProgress", fraction);
 			},
@@ -316,10 +347,19 @@ var Mixer = class {
 					mix: finiteIn("mix", effect.mix, 0, 1)
 				};
 				break;
-			case "voice": next.voice = {
-				enabled: effect.enabled,
-				formantSemitones: finiteIn("formantSemitones", effect.formantSemitones, -12, 12)
-			};
+			case "voice":
+				next.voice = {
+					enabled: effect.enabled,
+					formantSemitones: finiteIn("formantSemitones", effect.formantSemitones, -12, 12)
+				};
+				break;
+			case "echo-cancel":
+				next.echoCancel = { enabled: effect.enabled };
+				break;
+			case "cleanup":
+				next.cleanup = { enabled: effect.enabled };
+				break;
+			case "howl-guard": next.howlGuard = { enabled: effect.enabled };
 		}
 		this.#write(slot, next);
 	}
@@ -351,7 +391,8 @@ var Mixer = class {
 	*/
 	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`);
+		const kind = this.slots[slot]?.kind;
+		if (kind !== "rtp" && kind !== "l16") throw new Error(`slot ${slot} is a ${String(kind)} 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);
@@ -473,6 +514,7 @@ var Mixer = class {
 	#release() {
 		this.#phase = "destroyed";
 		this.#offFault();
+		this.#letGo();
 		this.#native.release();
 	}
 	#command(send) {
@@ -498,11 +540,14 @@ var Mixer = class {
 	}
 };
 function defaultEffects() {
-	const { corrector, reverb, voice } = defaultSlotParams();
+	const { corrector, reverb, voice, cleanup, echoCancel, howlGuard } = defaultSlotParams();
 	return {
 		corrector,
 		reverb,
-		voice
+		voice,
+		cleanup,
+		echoCancel,
+		howlGuard
 	};
 }
 function toGuideInput(guide) {
@@ -544,6 +589,8 @@ var Engine = class {
 	#events = new Emitter();
 	/** Swaps in flight, oldest first; a `retired` event completes the oldest. */
 	#retirements = [];
+	/** Each mixer's release until it is destroyed; `close` calls whatever is left. */
+	#held = /* @__PURE__ */ new Set();
 	/** Render jobs on the worker thread, by the id their progress events carry. */
 	#renders = /* @__PURE__ */ new Map();
 	#live = null;
@@ -551,7 +598,7 @@ var Engine = class {
 	#state = "running";
 	constructor(options) {
 		this.#slots = integerIn("slots", options.slots ?? 8, 1, 16);
-		const playoutDelayFrames = msToFrames(finiteIn("playoutDelayMs", options.playoutDelayMs ?? 15, 5, 100));
+		const pinned = options.playoutDelayMs === void 0 ? {} : { playoutDelayFrames: msToFrames(finiteIn("playoutDelayMs", options.playoutDelayMs, 5, 100)) };
 		const deliver = (batch) => {
 			this.#deliver(batch);
 		};
@@ -559,13 +606,13 @@ var Engine = class {
 			this.#native = new NativeEngine({
 				clock: "offline",
 				periodFrames: 128,
-				playoutDelayFrames
+				...pinned
 			}, 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
+			...pinned
 		}, deliver);
 		else {
 			const { device, periodFrames = 128 } = options.output;
@@ -573,7 +620,7 @@ var Engine = class {
 			this.#native = new NativeEngine({
 				clock: "device",
 				periodFrames,
-				playoutDelayFrames,
+				...pinned,
 				...device === void 0 ? {} : { device }
 			}, deliver);
 		}
@@ -592,6 +639,10 @@ var Engine = class {
 			swapIn: (mixer, graph, events, onTimeout) => this.#swapIn(mixer, graph, events, onTimeout),
 			swapOut: (mixer) => this.#swapOut(mixer),
 			onFault: (listener) => this.#events.on("fault", listener),
+			hold: (release) => {
+				this.#held.add(release);
+				return () => this.#held.delete(release);
+			},
 			isLive: (mixer) => this.#live?.mixer === mixer,
 			anyLive: () => this.#live !== null,
 			underruns: () => this.#underruns
@@ -615,12 +666,17 @@ var Engine = class {
 		this.#assertRunning();
 		return this.#native.outputs();
 	}
+	/** The inputs a `capture` slot may name, the default marked. None on an offline engine. */
+	async inputDevices() {
+		this.#assertRunning();
+		return this.#native.inputs();
+	}
 	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 slots = config.slots.map((slot, i) => slotInput(`slots[${i}]`, slot));
 		const destination = config.rtpReturn === void 0 ? null : rtpReturn(config.rtpReturn);
-		return new Mixer(this.#host, kinds, new Emitter(), config.backing ?? null, destination);
+		return new Mixer(this.#host, slots, new Emitter(), config.backing ?? null, destination);
 	}
 	on(event, listener) {
 		return this.#events.on(event, listener);
@@ -631,6 +687,7 @@ var Engine = class {
 		if (this.#live && this.#state === "running") await this.#live.mixer.destroy();
 		this.#state = "closed";
 		this.#native.close();
+		for (const release of this.#held) release();
 		this.#stop(/* @__PURE__ */ new Error("the engine is closed"));
 	}
 	#swapIn(mixer, graph, events, onTimeout) {

package/native/binding/index.d.ts

@@ -25,15 +25,22 @@ export declare class Engine {
    */
   constructor(options: OpenOptions, onEvents: (arg: Array<NativeEvent>) => void)
   /**
-   * Builds a mixer with one slot per kind, in order: `"rtp"`, `"l16"` or `"push"`. The rtp
-   * and l16 slots bind their ports here and report them through `Mixer.port`; a return stream
-   * gets its socket and send task here too.
+   * Builds a mixer with one slot per input, in order: `"rtp"`, `"l16"`, `"push"` or
+   * `"capture"`. The rtp and l16 slots bind their ports here and report them through
+   * `Mixer.port`, the capture slots start their inputs here, and a return stream gets its socket
+   * and send task here too.
    */
-  createMixer(kinds: Array<string>, rtpReturn?: RtpReturnInput | undefined | null): Mixer
+  createMixer(slots: Array<SlotInput>, rtpReturn?: RtpReturnInput | undefined | null): Mixer
   /** The output playing now. After a move the events thread sends the same as `outputChanged`. */
   get output(): OutputInfo
   /** The outputs this OS offers, the default marked. Empty on the offline and timer clocks. */
   outputs(): Array<OutputEntry>
+  /**
+   * The inputs this OS offers, the default marked: the devices a `capture` slot may name. Empty
+   * on the offline clock, which opens none. A box on the timer clock plays nothing locally but
+   * may still have a mic plugged in.
+   */
+  inputs(): Array<OutputEntry>
   /** Offline clock only: renders `blocks` blocks and returns them as interleaved stereo. */
   pump(blocks: number): Float32Array
   /** Writes one slot of the snapshot and publishes the whole of it. */
@@ -74,7 +81,7 @@ export declare class Engine {
 export declare class Mixer {
   /** Moves a finished render's stems into the graph as its backing path, before `swap`. */
   installBacking(render: BackingRender): void
-  /** The UDP port a slot listens on, or null for a push slot. */
+  /** The UDP port a slot listens on, or null for a push or capture slot. */
   port(index: number): number | null
   /**
    * Hands interleaved stereo PCM to a push slot, which folds it to mono as every slot is
@@ -86,7 +93,10 @@ export declare class Mixer {
    * recording it for null.
    */
   recordSlot(index: number, path?: string | undefined | null): void
-  /** Every slot's ingest counters and corrector delay, as the audio thread last published them. */
+  /**
+   * Every slot's ingest counters, corrector delay and echo findings, as the audio thread last
+   * published them.
+   */
   stats(): Array<SlotStatsInfo>
   /** The return stream's counters, or null for a mixer without one. */
   returnStats(): RtpReturnStats | null
@@ -106,6 +116,10 @@ export interface BackingInput {
   speed: number
 }
 
+export interface CleanupInput {
+  enabled: boolean
+}
+
 /** What drives the audio thread. */
 export declare const enum ClockKind {
   /** The offline driver, pumped from JavaScript. */
@@ -122,6 +136,16 @@ export interface CorrectorInput {
   retuneMs: number
 }
 
+/** What a slot's echo canceller has found, as JavaScript reads it. */
+export interface EchoInfo {
+  /** From the master being rendered to its echo reaching the slot. */
+  pathMs: number
+  /** How far under the master the echo arrives, over the last second. */
+  bleedDb: number
+  /** How much quieter the slot came out than it went in, over the last second. */
+  removedDb: number
+}
+
 export interface GuideInput {
   notes: Array<NoteInput>
   /** The key's pitch classes as bits, C in bit 0. */
@@ -153,8 +177,11 @@ export interface OpenOptions {
   /** A device clock's output: an id from `outputs` to pin, or none to follow the default output. */
   device?: string
   periodFrames: number
-  /** The jitter buffer's playout delay for every `rtp` and `l16` slot. */
-  playoutDelayFrames: number
+  /**
+   * Pins the jitter buffer's playout delay for every `rtp` and `l16` slot. Without it, each
+   * stream chooses its own.
+   */
+  playoutDelayFrames?: number
 }
 
 export interface OutputDevice {
@@ -197,6 +224,16 @@ export interface RtpReturnStats {
   droppedBlocks: number
 }
 
+/**
+ * One slot as `createMixer` asks for it. `device` and `channel` belong to a `capture` slot: an id
+ * from `inputs`, or the default input, and the device's channel from 0.
+ */
+export interface SlotInput {
+  kind: string
+  device?: string
+  channel?: number
+}
+
 export interface SlotParamsInput {
   /** Linear amplitude. */
   gain: number
@@ -207,6 +244,9 @@ export interface SlotParamsInput {
   corrector: CorrectorInput
   reverb: ReverbInput
   voice: VoiceInput
+  echoCancel: SwitchInput
+  cleanup: CleanupInput
+  howlGuard: SwitchInput
   guideOffsetMs: number
 }
 
@@ -215,11 +255,16 @@ export interface SlotStatsInfo {
   pushed: number
   lost: number
   late: number
+  lateAtOpening: number
   concealed: number
   resyncs: number
   jitterMs: number
   correctorDelayMs: number
   correctorMaxDelayMs: number
+  /** Null while the canceller is off or has yet to find and learn the room's echo. */
+  echo: EchoInfo | null
+  playoutDelayMs: number
+  howlCatches: number
 }
 
 export interface StemGainsInput {
@@ -227,6 +272,11 @@ export interface StemGainsInput {
   guide: number
 }
 
+/** An effect with no knob but on and off. */
+export interface SwitchInput {
+  enabled: boolean
+}
+
 export interface VoiceInput {
   enabled: boolean
   formantSemitones: number

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeonentertainment/mixer",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Low-latency LAN audio mixer for Aeon Karaoke: phone and house mics, a backing track, one mix to the room.",
   "bugs": {
     "url": "https://github.com/aeonentertainment/aeon-mixer/issues"
@@ -26,7 +26,7 @@
     "@napi-rs/cli": "^3.10.9",
     "@types/node": "^26.6.6",
     "typescript": "^7.0.2",
-    "vite-plus": "1.4.0"
+    "vite-plus": "1.5.1"
   },
   "devEngines": {
     "packageManager": {