@aeonentertainment/mixer 0.4.0 → 0.5.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.5.0/aeonentertainment-mixer-0.5.0.tgz
 ```
 
 ## Use
@@ -52,7 +52,9 @@ await engine.close();
   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.
+  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

@@ -73,7 +73,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 +94,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 +170,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;
@@ -202,6 +220,9 @@ interface SlotParamsInput {
   corrector: CorrectorInput;
   reverb: ReverbInput;
   voice: VoiceInput;
+  echoCancel: SwitchInput;
+  cleanup: CleanupInput;
+  howlGuard: SwitchInput;
   guideOffsetMs: number;
 }
 /** `SlotStats` as JavaScript reads it. */
@@ -209,16 +230,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;
@@ -245,7 +275,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 {
@@ -308,6 +341,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 +373,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 +385,21 @@ 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. */
+  playoutDelayMs: number;
+  /** How often the howl guard has ducked this slot. */
+  howlCatches: number;
 }
 type EngineEvents = {
   fault: (error: Error) => void;

package/dist/index.mjs

@@ -234,6 +234,9 @@ function defaultSlotParams() {
 			enabled: false,
 			formantSemitones: 0
 		},
+		echoCancel: { enabled: false },
+		cleanup: { enabled: false },
+		howlGuard: { enabled: false },
 		guideOffsetMs: 0
 	};
 }
@@ -316,10 +319,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);
 	}
@@ -498,11 +510,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) {
@@ -551,7 +566,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 +574,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 +588,7 @@ var Engine = class {
 			this.#native = new NativeEngine({
 				clock: "device",
 				periodFrames,
-				playoutDelayFrames,
+				...pinned,
 				...device === void 0 ? {} : { device }
 			}, deliver);
 		}

package/native/binding/index.d.ts

@@ -86,7 +86,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 +109,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 +129,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 +170,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 {
@@ -207,6 +227,9 @@ export interface SlotParamsInput {
   corrector: CorrectorInput
   reverb: ReverbInput
   voice: VoiceInput
+  echoCancel: SwitchInput
+  cleanup: CleanupInput
+  howlGuard: SwitchInput
   guideOffsetMs: number
 }
 
@@ -215,11 +238,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 +255,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.5.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": {