@aeonentertainment/mixer 0.1.0 → 0.3.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.1.0/aeonentertainment-mixer-0.1.0.tgz
+npm install https://github.com/aeonentertainment/aeon-mixer/releases/download/v0.3.0/aeonentertainment-mixer-0.3.0.tgz
 ```
 
 ## Use
@@ -51,13 +51,18 @@ 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 and a melody guide.
+  reverb, a pitch reading, a melody guide and pitch correction toward it, whose delay `stats()`
+  reports.
 - **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.
 - **`rtpReturn`** sends the mix to mediasoup's PlainTransport as 10 ms Opus with in-band FEC.
   `host` is an IP address, never a name.
 - **Reactions** play through `engine.reactions.play` between songs and during them.
+- **The timer engine**, `openEngine({ output: { timer: true } })`, is for a box with no sound
+  card. It opens no device; its own thread renders a block at each deadline on the OS's
+  monotonic clock, and the mix leaves on `rtpReturn`. `measure-clock` prints its timing:
+  `cargo run --release -p devices --bin measure-clock` in `native/`.
 - **The offline engine**, `openEngine({ output: { offline: true } })`, opens no device and
   renders only when its caller runs `engine.pump(blocks)`. The tests run on it.
 

package/dist/index.d.mts

@@ -19,7 +19,7 @@ declare class Engine$1 {
    */
   createMixer(kinds: Array<string>, rtpReturn?: RtpReturnInput | undefined | null): Mixer$1;
   get output(): OutputInfo$1;
-  /** The outputs this OS offers, the default marked. Empty on the offline clock. */
+  /** The outputs this OS offers, the default marked. Empty on the offline and timer clocks. */
   outputs(): Array<OutputEntry>;
   /** Offline clock only: renders `blocks` blocks and returns them as interleaved stereo. */
   pump(blocks: number): Float32Array;
@@ -72,7 +72,7 @@ declare class Mixer$1 {
    * recording it for null.
    */
   recordSlot(index: number, path?: string | undefined | null): void;
-  /** Every slot's ingest counters, as the audio thread last published them. */
+  /** Every slot's ingest counters and corrector delay, 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;
@@ -144,9 +144,8 @@ interface NoteInput {
   endFrame: number;
 }
 interface OpenOptions {
-  /** The offline driver, pumped from JavaScript, instead of a device. */
-  offline: boolean;
-  /** An id from `outputs`, or the default output. */
+  clock: 'offline' | 'timer' | 'device';
+  /** A device clock's output: an id from `outputs`, or the default output. */
   device?: string;
   periodFrames: number;
   /** The jitter buffer's playout delay for every `rtp` and `l16` slot. */
@@ -199,6 +198,8 @@ interface SlotStatsInfo {
   concealed: number;
   resyncs: number;
   jitterMs: number;
+  correctorDelayMs: number;
+  correctorMaxDelayMs: number;
 }
 interface StemGainsInput {
   instrumental: number;
@@ -211,9 +212,15 @@ type Capability = "guideVocal" | "key" | "speed" | "seek" | "shortVersion" | "pa
 type IngestKind = "rtp" | "l16" | "push";
 type StemKind = "instrumental" | "guideVocals";
 interface OpenEngineOptions {
+  /**
+   * A device; `timer` for a box with no sound card, whose own thread renders on the OS's clock
+   * and whose mix leaves only on a mixer's `rtpReturn`; `offline` for tests, which pump it.
+   */
   output: {
     device?: string;
     periodFrames?: 64 | 128;
+  } | {
+    timer: true;
   } | {
     offline: true;
   };
@@ -285,6 +292,13 @@ interface SlotStats {
   concealed: number;
   resyncs: number;
   jitterMs: number;
+  /**
+   * How far the corrector holds this slot's voice now; 0 with correction off. It moves with the
+   * voice and one read is a sample of it, so show it and never add it to a budget or a clock.
+   */
+  correctorDelayMs: number;
+  /** The most that delay can reach; 0 with correction off. It holds still, so a budget adds this. */
+  correctorMaxDelayMs: number;
 }
 type EngineEvents = {
   fault: (error: Error) => void;
@@ -424,8 +438,8 @@ export declare class Mixer {
 /** An engine on the test clock. Its caller pumps it; nothing plays. */
 type OfflineEngine = Engine & Required<Pick<Engine, "pump">>;
 /**
- * Opens the engine for the life of the process: the device, or the offline driver, running the
- * silent graph until a mixer starts.
+ * Opens the engine for the life of the process: the device, the timer clock on a box with no
+ * sound card, or the offline driver, running the silent graph until a mixer starts.
  */
 export declare function openEngine(options: OpenEngineOptions & {
   output: {

package/dist/index.mjs

@@ -546,16 +546,21 @@ var Engine = class {
 		};
 		if ("offline" in options.output) {
 			this.#native = new NativeEngine({
-				offline: true,
+				clock: "offline",
 				periodFrames: 128,
 				playoutDelayFrames
 			}, deliver);
 			this.pump = (blocks) => this.#native.pump(integerIn("blocks", blocks, 1, 1 << 20));
-		} else {
+		} 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({
-				offline: false,
+				clock: "device",
 				periodFrames,
 				playoutDelayFrames,
 				...device === void 0 ? {} : { device }

package/native/binding/index.d.ts

@@ -31,7 +31,7 @@ export declare class Engine {
    */
   createMixer(kinds: Array<string>, rtpReturn?: RtpReturnInput | undefined | null): Mixer
   get output(): OutputInfo
-  /** The outputs this OS offers, the default marked. Empty on the offline clock. */
+  /** The outputs this OS offers, the default marked. Empty on the offline and timer clocks. */
   outputs(): Array<OutputEntry>
   /** Offline clock only: renders `blocks` blocks and returns them as interleaved stereo. */
   pump(blocks: number): Float32Array
@@ -85,7 +85,7 @@ export declare class Mixer {
    * recording it for null.
    */
   recordSlot(index: number, path?: string | undefined | null): void
-  /** Every slot's ingest counters, as the audio thread last published them. */
+  /** Every slot's ingest counters and corrector delay, 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
@@ -105,6 +105,16 @@ export interface BackingInput {
   speed: number
 }
 
+/** What drives the audio thread. */
+export declare const enum ClockKind {
+  /** The offline driver, pumped from JavaScript. */
+  Offline = 'offline',
+  /** The timer clock, for a box with no sound card: no device, and nothing to pump. */
+  Timer = 'timer',
+  /** An OS output. */
+  Device = 'device',
+}
+
 export interface CorrectorInput {
   enabled: boolean
   strength: number
@@ -137,9 +147,8 @@ export interface NoteInput {
 }
 
 export interface OpenOptions {
-  /** The offline driver, pumped from JavaScript, instead of a device. */
-  offline: boolean
-  /** An id from `outputs`, or the default output. */
+  clock: 'offline' | 'timer' | 'device'
+  /** A device clock's output: an id from `outputs`, or the default output. */
   device?: string
   periodFrames: number
   /** The jitter buffer's playout delay for every `rtp` and `l16` slot. */
@@ -199,6 +208,8 @@ export interface SlotStatsInfo {
   concealed: number
   resyncs: number
   jitterMs: number
+  correctorDelayMs: number
+  correctorMaxDelayMs: number
 }
 
 export interface StemGainsInput {

package/native/binding/index.js

@@ -838,3 +838,4 @@ module.exports = nativeBinding
 module.exports.BackingRender = nativeBinding.BackingRender
 module.exports.Engine = nativeBinding.Engine
 module.exports.Mixer = nativeBinding.Mixer
+module.exports.ClockKind = nativeBinding.ClockKind

package/package.json

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