@aeonentertainment/mixer 0.5.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.5.0/aeonentertainment-mixer-0.5.0.tgz
+npm install https://github.com/aeonentertainment/aeon-mixer/releases/download/v0.6.0/aeonentertainment-mixer-0.6.0.tgz
 ```
 
 ## Use
@@ -50,11 +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. 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.
+  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
@@ -210,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;
@@ -257,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 {
   /**
@@ -291,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;
@@ -396,7 +422,11 @@ interface SlotStats {
     bleedDb: number;
     removedDb: number;
   } | null;
-  /** The delay the stream's earliest packets wait now; zero for a `push` slot. */
+  /**
+   * 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;
@@ -461,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;
@@ -578,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;
@@ -241,13 +265,14 @@ function defaultSlotParams() {
 	};
 }
 /**
-* 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;
@@ -256,6 +281,7 @@ var Mixer = class {
 	#guides;
 	#backing;
 	#offFault;
+	#letGo;
 	#phase = "armed";
 	#failed = false;
 	/**
@@ -267,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);
 			},
@@ -363,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);
@@ -485,6 +514,7 @@ var Mixer = class {
 	#release() {
 		this.#phase = "destroyed";
 		this.#offFault();
+		this.#letGo();
 		this.#native.release();
 	}
 	#command(send) {
@@ -559,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;
@@ -607,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
@@ -630,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);
@@ -646,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
@@ -217,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeonentertainment/mixer",
-  "version": "0.5.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"