@memberjunction/livekit-room-server 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/room-audio/audio-decoder.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview {@link DecodeAudio} — turns an audio file's bytes (WAV or MP3) into mono PCM16, the one shape the
+ * room audio player plays. WAV is parsed here (RIFF chunk walk, integer PCM 8/16/24/32-bit and IEEE float 32/64-bit,
+ * any channel count downmixed); MP3 is decoded by `mpg123-decoder`, a WebAssembly build of libmpg123 with no native
+ * build step. Anything else is refused with an error that names the format it saw.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { MPEGDecoder } from 'mpg123-decoder';
+/** The longest audio {@link DecodeAudio} accepts, in seconds (15 minutes). Hold music loops; a longer file is a mistake. */
+export const MAX_DECODED_AUDIO_SECONDS = 15 * 60;
+const WAV_FORMAT_PCM = 1;
+const WAV_FORMAT_FLOAT = 3;
+const WAV_FORMAT_EXTENSIBLE = 0xfffe;
+/**
+ * Decodes WAV or MP3 bytes into mono PCM16. The format is read from the bytes' own signature first and from the hint
+ * only when the bytes carry none (a bare MP3 frame stream).
+ *
+ * @param bytes The file's bytes.
+ * @param hint The MIME type and/or file name, when known.
+ * @returns Mono PCM16 at the file's own sample rate.
+ * @throws {Error} when the format is not WAV or MP3, the file is malformed or empty, or it is longer than
+ *   {@link MAX_DECODED_AUDIO_SECONDS}.
+ */
+export async function DecodeAudio(bytes, hint) {
+    if (bytes.byteLength === 0) {
+        throw new Error('Cannot decode audio: the file is empty.');
+    }
+    const format = detectFormat(bytes, hint);
+    const decoded = format === 'wav' ? decodeWav(bytes) : await decodeMp3(bytes);
+    AssertAudioDurationWithinCap(decoded.Pcm.length, decoded.SampleRate);
+    return decoded;
+}
+/** Throws when `sampleCount` samples at `sampleRate` run longer than {@link MAX_DECODED_AUDIO_SECONDS}. */
+export function AssertAudioDurationWithinCap(sampleCount, sampleRate) {
+    const seconds = sampleCount / sampleRate;
+    if (seconds > MAX_DECODED_AUDIO_SECONDS) {
+        throw new Error(`Audio is ${Math.round(seconds)} s long; the room audio player accepts at most ${MAX_DECODED_AUDIO_SECONDS} s ` +
+            '(15 minutes). Trim the file — hold music loops, so a few minutes is plenty.');
+    }
+}
+// ── Format detection ─────────────────────────────────────────────────────────────────────────────────────────────
+function ascii(bytes, start, length) {
+    return String.fromCharCode(...bytes.subarray(start, start + length));
+}
+function isMp3Signature(bytes) {
+    if (bytes.byteLength >= 3 && ascii(bytes, 0, 3) === 'ID3') {
+        return true;
+    }
+    // An MPEG audio frame header starts with 11 set sync bits.
+    return bytes.byteLength >= 2 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0;
+}
+/** Names a recognisable but unsupported container from its signature, for the error message. */
+function describeUnsupportedSignature(bytes) {
+    if (bytes.byteLength >= 4 && ascii(bytes, 0, 4) === 'OggS')
+        return 'Ogg (Vorbis/Opus)';
+    if (bytes.byteLength >= 4 && ascii(bytes, 0, 4) === 'fLaC')
+        return 'FLAC';
+    if (bytes.byteLength >= 8 && ascii(bytes, 4, 4) === 'ftyp')
+        return 'MP4/M4A (AAC)';
+    if (bytes.byteLength >= 4 && ascii(bytes, 0, 4) === 'FORM')
+        return 'AIFF';
+    if (bytes.byteLength >= 4 && bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3)
+        return 'WebM/Matroska';
+    return undefined;
+}
+function formatFromHint(hint) {
+    const mime = hint?.MimeType?.toLowerCase().split(';')[0].trim() ?? '';
+    const name = hint?.FileName?.toLowerCase() ?? '';
+    if (['audio/wav', 'audio/x-wav', 'audio/wave', 'audio/vnd.wave'].includes(mime) || name.endsWith('.wav'))
+        return 'wav';
+    if (['audio/mpeg', 'audio/mp3', 'audio/mpeg3', 'audio/x-mpeg-3'].includes(mime) || name.endsWith('.mp3'))
+        return 'mp3';
+    return undefined;
+}
+function detectFormat(bytes, hint) {
+    if (bytes.byteLength >= 12 && ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WAVE') {
+        return 'wav';
+    }
+    if (isMp3Signature(bytes)) {
+        return 'mp3';
+    }
+    const unsupported = describeUnsupportedSignature(bytes);
+    const hinted = unsupported ? undefined : formatFromHint(hint);
+    if (hinted === 'mp3') {
+        return 'mp3'; // an MP3 stream may begin mid-frame; let the decoder resync
+    }
+    const seen = unsupported ?? (hint?.MimeType || hint?.FileName || 'unrecognised bytes');
+    throw new Error(`Unsupported audio format: ${seen}. The room audio player plays WAV (PCM or float) and MP3.`);
+}
+// ── WAV ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+/** Walks the RIFF chunks and returns the `fmt ` description and the `data` byte range. */
+function readWavChunks(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let format;
+    let offset = 12;
+    while (offset + 8 <= bytes.byteLength) {
+        const id = ascii(bytes, offset, 4);
+        const size = view.getUint32(offset + 4, true);
+        const body = offset + 8;
+        if (id === 'fmt ') {
+            format = readWavFormat(view, body, size);
+        }
+        else if (id === 'data') {
+            if (!format) {
+                throw new Error('Malformed WAV: the data chunk comes before the fmt chunk.');
+            }
+            // A streaming writer may leave the size as 0 or 0xFFFFFFFF; clamp to what is actually there.
+            return { Format: format, DataOffset: body, DataLength: Math.min(size, bytes.byteLength - body) };
+        }
+        offset = body + size + (size & 1); // chunks are word-aligned: an odd-sized chunk carries one pad byte
+    }
+    throw new Error(format ? 'Malformed WAV: no data chunk.' : 'Malformed WAV: no fmt chunk.');
+}
+function readWavFormat(view, body, size) {
+    if (size < 16 || body + 16 > view.byteLength) {
+        throw new Error('Malformed WAV: the fmt chunk is truncated.');
+    }
+    let formatCode = view.getUint16(body, true);
+    if (formatCode === WAV_FORMAT_EXTENSIBLE && size >= 40 && body + 26 <= view.byteLength) {
+        formatCode = view.getUint16(body + 24, true); // the first two bytes of the SubFormat GUID are the real code
+    }
+    return {
+        FormatCode: formatCode,
+        Channels: view.getUint16(body + 2, true),
+        SampleRate: view.getUint32(body + 4, true),
+        BitsPerSample: view.getUint16(body + 14, true),
+    };
+}
+function sampleReaderFor(format) {
+    const { FormatCode: code, BitsPerSample: bits } = format;
+    if (code === WAV_FORMAT_PCM && bits === 8)
+        return (v, o) => (v.getUint8(o) - 128) / 128;
+    if (code === WAV_FORMAT_PCM && bits === 16)
+        return (v, o) => v.getInt16(o, true) / 32768;
+    if (code === WAV_FORMAT_PCM && bits === 24) {
+        return (v, o) => ((v.getUint8(o) | (v.getUint8(o + 1) << 8) | (v.getInt8(o + 2) << 16)) / 8388608);
+    }
+    if (code === WAV_FORMAT_PCM && bits === 32)
+        return (v, o) => v.getInt32(o, true) / 2147483648;
+    if (code === WAV_FORMAT_FLOAT && bits === 32)
+        return (v, o) => v.getFloat32(o, true);
+    if (code === WAV_FORMAT_FLOAT && bits === 64)
+        return (v, o) => v.getFloat64(o, true);
+    throw new Error(`Unsupported WAV encoding: format code ${code}, ${bits}-bit. The room audio player plays integer PCM ` +
+        '(8/16/24/32-bit) and IEEE float (32/64-bit) WAV.');
+}
+function decodeWav(bytes) {
+    const { Format: format, DataOffset: dataOffset, DataLength: dataLength } = readWavChunks(bytes);
+    if (format.Channels < 1 || format.SampleRate < 1) {
+        throw new Error(`Malformed WAV: ${format.Channels} channel(s) at ${format.SampleRate} Hz.`);
+    }
+    const read = sampleReaderFor(format);
+    const bytesPerSample = format.BitsPerSample / 8;
+    const frameBytes = bytesPerSample * format.Channels;
+    const frames = Math.floor(dataLength / frameBytes);
+    if (frames === 0) {
+        throw new Error('Cannot decode audio: the WAV data chunk holds no samples.');
+    }
+    AssertAudioDurationWithinCap(frames, format.SampleRate); // before allocating the output for an over-long file
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const pcm = new Int16Array(frames);
+    for (let frame = 0; frame < frames; frame++) {
+        const base = dataOffset + frame * frameBytes;
+        let sum = 0;
+        for (let channel = 0; channel < format.Channels; channel++) {
+            sum += read(view, base + channel * bytesPerSample);
+        }
+        pcm[frame] = FloatToPcm16(sum / format.Channels);
+    }
+    return { Pcm: pcm, SampleRate: format.SampleRate };
+}
+/** Converts one [-1, 1] float sample to PCM16, clamping anything outside the range. */
+export function FloatToPcm16(sample) {
+    const clamped = sample > 1 ? 1 : sample < -1 ? -1 : sample;
+    return clamped < 0 ? Math.round(clamped * 32768) : Math.round(clamped * 32767);
+}
+// ── MP3 ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+async function decodeMp3(bytes) {
+    const decoder = new MPEGDecoder();
+    try {
+        await decoder.ready;
+        const result = decoder.decode(bytes);
+        if (result.samplesDecoded === 0 || result.channelData.length === 0) {
+            const reason = result.errors.length > 0 ? result.errors[0].message : 'no audio frames found';
+            throw new Error(`Cannot decode MP3: ${reason}.`);
+        }
+        return { Pcm: downmixFloatChannels(result.channelData, result.samplesDecoded), SampleRate: result.sampleRate };
+    }
+    finally {
+        decoder.free();
+    }
+}
+function downmixFloatChannels(channels, sampleCount) {
+    const pcm = new Int16Array(sampleCount);
+    for (let i = 0; i < sampleCount; i++) {
+        let sum = 0;
+        for (const channel of channels) {
+            sum += channel[i];
+        }
+        pcm[i] = FloatToPcm16(sum / channels.length);
+    }
+    return pcm;
+}
+//# sourceMappingURL=audio-decoder.js.map

package/dist/room-audio/audio-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-decoder.js","sourceRoot":"","sources":["../../src/room-audio/audio-decoder.ts"],"names":[],"mappings":"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"}

package/dist/room-audio/comfort-tone.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview {@link GenerateComfortTone} — a procedurally generated hold loop for when a queue has no music
+ * configured. Four soft major/minor pads (C – Am – F – G, the progression everyone has heard a thousand times and
+ * nobody minds) with slow raised-cosine swells, a quiet bass an octave below, and a touch of second harmonic for
+ * warmth. Each chord fades fully out before the next fades in, so the loop seam is silent and never clicks.
+ *
+ * Synthesized at runtime: no audio asset ships, so there is nothing to license.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+/** Length of one pass of the comfort tone, in seconds. */
+export declare const COMFORT_TONE_LOOP_SECONDS = 10;
+/** Peak level of the comfort tone as a fraction of full scale (about −15 dBFS — quieter than speech). */
+export declare const COMFORT_TONE_PEAK = 0.18;
+/**
+ * Generates one {@link COMFORT_TONE_LOOP_SECONDS}-second pass of the comfort tone as mono PCM16. Loop it end to end.
+ *
+ * @param sampleRate The rate to synthesize at, in Hz (generate at the playback rate to avoid resampling).
+ * @returns Mono PCM16 samples; every sample's magnitude is at most {@link COMFORT_TONE_PEAK} of full scale.
+ * @throws {Error} when `sampleRate` is not a positive integer.
+ */
+export declare function GenerateComfortTone(sampleRate: number): Int16Array;
+//# sourceMappingURL=comfort-tone.d.ts.map

package/dist/room-audio/comfort-tone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comfort-tone.d.ts","sourceRoot":"","sources":["../../src/room-audio/comfort-tone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,yGAAyG;AACzG,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAiBtC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAQlE"}

package/dist/room-audio/comfort-tone.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview {@link GenerateComfortTone} — a procedurally generated hold loop for when a queue has no music
+ * configured. Four soft major/minor pads (C – Am – F – G, the progression everyone has heard a thousand times and
+ * nobody minds) with slow raised-cosine swells, a quiet bass an octave below, and a touch of second harmonic for
+ * warmth. Each chord fades fully out before the next fades in, so the loop seam is silent and never clicks.
+ *
+ * Synthesized at runtime: no audio asset ships, so there is nothing to license.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+/** Length of one pass of the comfort tone, in seconds. */
+export const COMFORT_TONE_LOOP_SECONDS = 10;
+/** Peak level of the comfort tone as a fraction of full scale (about −15 dBFS — quieter than speech). */
+export const COMFORT_TONE_PEAK = 0.18;
+/** One chord of the progression: the frequencies of its voices, root first. */
+const CHORDS = [
+    [261.63, 329.63, 392.0], // C major (C4 E4 G4)
+    [220.0, 261.63, 329.63], // A minor (A3 C4 E4)
+    [174.61, 220.0, 261.63], // F major (F3 A3 C4)
+    [196.0, 246.94, 293.66], // G major (G3 B3 D4)
+];
+/** Fraction of each chord spent swelling in (and, symmetrically, fading out). */
+const SWELL_FRACTION = 0.3;
+/** Relative weight of the bass voice (the chord root an octave down) and of each voice's second harmonic. */
+const BASS_WEIGHT = 0.5;
+const HARMONIC_WEIGHT = 0.15;
+/**
+ * Generates one {@link COMFORT_TONE_LOOP_SECONDS}-second pass of the comfort tone as mono PCM16. Loop it end to end.
+ *
+ * @param sampleRate The rate to synthesize at, in Hz (generate at the playback rate to avoid resampling).
+ * @returns Mono PCM16 samples; every sample's magnitude is at most {@link COMFORT_TONE_PEAK} of full scale.
+ * @throws {Error} when `sampleRate` is not a positive integer.
+ */
+export function GenerateComfortTone(sampleRate) {
+    if (!Number.isInteger(sampleRate) || sampleRate <= 0) {
+        throw new Error(`GenerateComfortTone needs a positive integer sample rate; got ${sampleRate}.`);
+    }
+    const chordSamples = Math.round((COMFORT_TONE_LOOP_SECONDS / CHORDS.length) * sampleRate);
+    const out = new Int16Array(chordSamples * CHORDS.length);
+    CHORDS.forEach((chord, index) => renderChord(out, index * chordSamples, chordSamples, chord, sampleRate));
+    return out;
+}
+/** Writes one enveloped chord into `out` starting at `start`. */
+function renderChord(out, start, length, chord, sampleRate) {
+    const voices = [...chord, chord[0] / 2];
+    const weights = [...chord.map(() => 1), BASS_WEIGHT];
+    // Normalise so the worst case (every voice and harmonic in phase at the envelope peak) stays at COMFORT_TONE_PEAK.
+    const worstCase = weights.reduce((total, weight) => total + weight * (1 + HARMONIC_WEIGHT), 0);
+    const scale = (COMFORT_TONE_PEAK * 32767) / worstCase;
+    for (let i = 0; i < length; i++) {
+        const t = i / sampleRate;
+        let sample = 0;
+        for (let v = 0; v < voices.length; v++) {
+            const phase = 2 * Math.PI * voices[v] * t;
+            sample += weights[v] * (Math.sin(phase) + HARMONIC_WEIGHT * Math.sin(2 * phase));
+        }
+        out[start + i] = Math.round(sample * swellEnvelope(i / length) * scale);
+    }
+}
+/** A raised-cosine swell: 0 at both ends of the chord, 1 across the middle. */
+function swellEnvelope(position) {
+    if (position < SWELL_FRACTION) {
+        return 0.5 - 0.5 * Math.cos((Math.PI * position) / SWELL_FRACTION);
+    }
+    if (position > 1 - SWELL_FRACTION) {
+        return 0.5 - 0.5 * Math.cos((Math.PI * (1 - position)) / SWELL_FRACTION);
+    }
+    return 1;
+}
+//# sourceMappingURL=comfort-tone.js.map

package/dist/room-audio/comfort-tone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comfort-tone.js","sourceRoot":"","sources":["../../src/room-audio/comfort-tone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C,yGAAyG;AACzG,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,+EAA+E;AAC/E,MAAM,MAAM,GAAmC;IAC7C,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,qBAAqB;IAC9C,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,qBAAqB;IAC9C,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,qBAAqB;IAC9C,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,qBAAqB;CAC/C,CAAC;AAEF,iFAAiF;AACjF,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,6GAA6G;AAC7G,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,iEAAiE,UAAU,GAAG,CAAC,CAAC;IAClG,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC;IAC1F,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,GAAG,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;IAC1G,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iEAAiE;AACjE,SAAS,WAAW,CAAC,GAAe,EAAE,KAAa,EAAE,MAAc,EAAE,KAAwB,EAAE,UAAkB;IAC/G,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACrD,mHAAmH;IACnH,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/F,MAAM,KAAK,GAAG,CAAC,iBAAiB,GAAG,KAAK,CAAC,GAAG,SAAS,CAAC;IACtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;QACzB,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1C,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;QACnF,CAAC;QACD,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,aAAa,CAAC,QAAgB;IACrC,IAAI,QAAQ,GAAG,cAAc,EAAE,CAAC;QAC9B,OAAO,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,GAAG,cAAc,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,GAAG,cAAc,EAAE,CAAC;QAClC,OAAO,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/room-audio/pcm-frame-pump.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview {@link PcmFramePump} — plays a PCM16 buffer out to a sink in real time, one 20 ms frame at a time.
+ *
+ * The native LiveKit wrapper's `publishAudio` queues whatever it is given and drains it as fast as the WebRTC audio
+ * source accepts it; it does not pace. Handing it a whole song would buffer minutes of audio in memory and make pause,
+ * stop and announcements lag by that much. So the pump paces itself: a fast ticker compares monotonic elapsed time
+ * with frames sent and emits only what is due, plus a small lead (~150 ms) that absorbs timer jitter. The lead is all
+ * that is ever outstanding downstream.
+ *
+ * - **Drift correction** — frames due are computed from the elapsed time since the timeline started, never by
+ *   counting ticks, so a late tick sends two frames and the average rate stays exact.
+ * - **Bounded catch-up** — after a long stall (a blocked event loop) the pump does not burst the backlog; it drops it
+ *   and restarts the timeline, so the downstream queue can never grow past the lead plus a small margin.
+ * - **Loop**, **Pause/Resume** (resume restarts the timeline — no burst), and **InsertClip**: the music fades down to a
+ *   duck level, the clip plays over it, and the music fades back up.
+ *
+ * The clock and ticker are injectable so tests drive time by hand.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+/** A running ticker the pump can cancel. */
+export interface PumpTicker {
+    /** Stops the ticker. Idempotent. */
+    Cancel(): void;
+}
+/** The pump's source of time and ticks — `performance.now()` + `setInterval` in production, a fake in tests. */
+export interface PumpClock {
+    /** Monotonic milliseconds. */
+    Now(): number;
+    /** Calls `callback` every `intervalMs` until cancelled. */
+    StartTicker(callback: () => void, intervalMs: number): PumpTicker;
+}
+/** Why a pump stopped: its (non-looping) audio ran out, it was stopped, or the sink threw. */
+export type PumpEndReason = 'Completed' | 'Stopped' | 'SinkError';
+/** Construction options for {@link PcmFramePump}. */
+export interface PcmFramePumpOptions {
+    /** Mono PCM16 to play, at {@link SampleRate}. Must not be empty. */
+    Music: Int16Array;
+    /** The rate of {@link Music}, of inserted clips, and of the frames handed to {@link Sink}. */
+    SampleRate: number;
+    /** Receives each frame. Every frame is a freshly allocated array the sink may keep. */
+    Sink: (frame: Int16Array<ArrayBuffer>) => void;
+    /** Loop {@link Music} forever. Default `true`. */
+    Loop?: boolean;
+    /** Frame duration in ms. Default 20. */
+    FrameMs?: number;
+    /** How far ahead of real time the pump keeps the sink, in ms. Default 150. */
+    LeadMs?: number;
+    /** How long the music takes to fade down for a clip (and back up after), in ms. Default 150. */
+    DuckMs?: number;
+    /** The music's level while a clip plays, 0–1. Default 0.15. */
+    DuckLevel?: number;
+    /** Time source. Default: {@link SystemPumpClock}. */
+    Clock?: PumpClock;
+    /** Called once when the pump stops, with the reason. */
+    OnEnded?: (reason: PumpEndReason) => void;
+}
+/** The production clock: `performance.now()` and an unref'd `setInterval` (a playing pump never holds the process open). */
+export declare const SystemPumpClock: PumpClock;
+/** Paces mono PCM16 out to a sink in real time. See the file overview. */
+export declare class PcmFramePump {
+    private readonly music;
+    private readonly sampleRate;
+    private readonly sink;
+    private readonly loop;
+    private readonly frameMs;
+    private readonly samplesPerFrame;
+    private readonly leadFrames;
+    private readonly maxBurstFrames;
+    private readonly duckLevel;
+    private readonly gainStep;
+    private readonly clock;
+    private readonly onEnded?;
+    private ticker;
+    private running;
+    private paused;
+    private ended;
+    private timelineStart;
+    private framesOnTimeline;
+    private framesSent;
+    private musicPosition;
+    private musicDone;
+    private gain;
+    private readonly clipQueue;
+    private currentClip;
+    private clipPosition;
+    /** @throws {Error} when the music is empty or a timing option is not positive. */
+    constructor(options: PcmFramePumpOptions);
+    /** True between {@link Start} and the pump ending (including while paused). */
+    get IsRunning(): boolean;
+    /** True while paused. */
+    get IsPaused(): boolean;
+    /** Frames handed to the sink so far. */
+    get FramesSent(): number;
+    /** Samples per frame at the pump's rate. */
+    get SamplesPerFrame(): number;
+    /** Starts playback: sends the lead immediately, then paces in real time. A second call is a no-op. */
+    Start(): void;
+    /** Stops sending frames until {@link Resume}. Playback position, ducking and queued clips are kept. */
+    Pause(): void;
+    /** Continues after {@link Pause} from where it left off, on a fresh timeline (so nothing bursts). */
+    Resume(): void;
+    /**
+     * How much already-sent audio is still ahead of real time, in ms: the pump keeps the sink up to `LeadMs` ahead, so
+     * after the last frame is sent the room is still playing this much. Zero once real time has caught up.
+     */
+    get QueuedAheadMs(): number;
+    /**
+     * Plays `pcm` over the music: the music fades down to the duck level, the clip plays, the music fades back up.
+     * Clips queue behind one another.
+     *
+     * @param pcm Mono PCM16 at the pump's sample rate.
+     * @returns Resolves `true` once the clip has been sent in full, `false` if the pump stopped first or the clip is empty.
+     */
+    InsertClip(pcm: Int16Array): Promise<boolean>;
+    /** Stops the pump for good. Idempotent; pending clips resolve `false`. */
+    Stop(): void;
+    private restartTimeline;
+    private tick;
+    /** Frames owed to the sink now, given elapsed time and the lead. Drops the backlog after a long stall. */
+    private framesDue;
+    private emitFrame;
+    /** The next output sample in [-1, 1]: ducked music plus whatever clip is playing. */
+    private nextSample;
+    /** Moves the music gain one step toward its target: the duck level while a clip is queued or playing, else full. */
+    private advanceGain;
+    private startQueuedClipIfDucked;
+    private nextMusicSample;
+    private nextClipSample;
+    /** Ends the pump once: cancels the ticker, fails any pending clips, reports the reason. */
+    private finish;
+    private failPendingClips;
+}
+//# sourceMappingURL=pcm-frame-pump.d.ts.map

package/dist/room-audio/pcm-frame-pump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pcm-frame-pump.d.ts","sourceRoot":"","sources":["../../src/room-audio/pcm-frame-pump.ts"],"names":[],"mappings":"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"}