@memberjunction/livekit-room-server 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/room-audio/room-audio-player.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview {@link RoomAudioPlayer} — joins a LiveKit room as a small publish-only bot and plays audio into it:
+ * contact-center hold music, with spoken announcements ducked over the top ("you are caller number three").
+ *
+ * The audio comes from an `MJ: Files` row, an https URL, raw PCM, or the built-in comfort tone. It is decoded once
+ * (WAV or MP3), resampled to {@link ROOM_AUDIO_SAMPLE_RATE}, cached by source, and paced into the room in 20 ms
+ * frames by a {@link PcmFramePump}. Each playback is a {@link RoomAudioHandle} the caller pauses, resumes, announces
+ * through and stops; the player keeps a registry so a room's playbacks can be found and stopped together (the
+ * `room_finished` webhook does this), and a playback whose bot is disconnected by the server removes itself.
+ *
+ * It reuses the agent bridge's plumbing rather than its own: bot tokens from {@link LiveKitTokenService}, the native
+ * room client through `@memberjunction/ai-bridge-livekit`'s module loader at the same specifier the agent coordinator
+ * resolves, and the PCM16 resampler from `@memberjunction/ai-bridge-base`.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { BaseSingleton } from '@memberjunction/global';
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { type NativeModuleLoader } from '@memberjunction/ai-bridge-livekit';
+import { LiveKitTokenService } from '../livekit-token-service.js';
+import { type PumpClock } from './pcm-frame-pump.js';
+import { type RoomAudioFileReader, type RoomAudioUrlFetcher } from './room-audio-sources.js';
+import type { IRoomSpeechSynthesizer } from './room-speech-synthesizer.js';
+/** The rate the player publishes at (Hz). Music sounds noticeably duller at the 24 kHz the agent voice uses. */
+export declare const ROOM_AUDIO_SAMPLE_RATE = 48000;
+/** What to play: an `MJ: Files` row, an https URL, raw mono PCM16, or the built-in comfort tone. */
+export type RoomAudioSource = {
+    Kind: 'File';
+    FileID: string;
+} | {
+    Kind: 'Url';
+    Url: string;
+} | {
+    Kind: 'Pcm';
+    Pcm: Int16Array;
+    SampleRate: number;
+} | {
+    Kind: 'ComfortTone';
+};
+/** Parameters for {@link RoomAudioPlayer.Start}. */
+export interface StartRoomAudioParams {
+    /** The LiveKit room to play into. */
+    RoomName: string;
+    /** What to play. */
+    Source: RoomAudioSource;
+    /** Loop the audio until stopped. Default `true`; when `false` the bot leaves the room once the audio ends. */
+    Loop?: boolean;
+    /** The bot's display name in the room. Default `'On hold'`. */
+    DisplayName?: string;
+    /** The bot's participant identity. Default `hold-<playback id>`. */
+    Identity?: string;
+    /** The user the file load (and any announcement synthesis) runs as. */
+    ContextUser: UserInfo;
+    /** The metadata provider for the file load. Default: the global provider. */
+    Provider?: IMetadataProvider;
+}
+/**
+ * Why a playback ended, as reported by {@link RoomAudioHandle.Ended}:
+ * - `Completed`: non-looping audio played to its end (every frame went to the room).
+ * - `Stopped`: {@link RoomAudioHandle.Stop} was called (or {@link RoomAudioPlayer.StopAllInRoom}).
+ * - `Failed`: the bot's audio sink failed mid-playback, so the audio was cut short.
+ * - `Disconnected`: the server dropped the bot (room closed, participant removed) before the audio ended.
+ */
+export type RoomAudioEndReason = 'Completed' | 'Stopped' | 'Failed' | 'Disconnected';
+/** An announcement: text to speak through the speech synthesizer, or ready-made mono PCM16. */
+export type RoomAudioClip = {
+    Text: string;
+} | {
+    Pcm: Int16Array;
+    SampleRate: number;
+};
+/** A live playback in one room. */
+export interface RoomAudioHandle {
+    /** This playback's id (also the default identity suffix of its bot). */
+    readonly PlaybackID: string;
+    /** The room it plays into. */
+    readonly RoomName: string;
+    /** True while audio is being sent (false once paused or stopped). */
+    readonly IsPlaying: boolean;
+    /** Why the playback ended, or `null` while it is still live. */
+    readonly EndReason: RoomAudioEndReason | null;
+    /**
+     * Resolves once the playback has ended and its bot has left the room, with the reason. Only `Completed` means the
+     * whole clip reached the room — use it to gate anything that must follow a full play, e.g. starting a recording
+     * only after a recording disclosure has been heard. A looping playback never completes on its own; it resolves
+     * `Stopped` when stopped. The first reason wins. Never rejects.
+     */
+    readonly Ended: Promise<RoomAudioEndReason>;
+    /**
+     * Plays a clip over the music, ducking the music while it plays. Resolves `true` once the clip has been sent in
+     * full; `false` when it could not be played (no speech synthesizer installed, synthesis failed, or the playback
+     * stopped first). Never rejects.
+     */
+    Announce(clip: RoomAudioClip): Promise<boolean>;
+    /** Stops sending audio, keeping the position. */
+    Pause(): void;
+    /** Continues after {@link Pause}. */
+    Resume(): void;
+    /** Stops playback and disconnects the bot. Idempotent; never rejects. */
+    Stop(): Promise<void>;
+}
+/** The part of {@link LiveKitTokenService} the player uses — a seam for tests. */
+export type RoomAudioTokenMinter = Pick<LiveKitTokenService, 'MintToken'>;
+/**
+ * Plays audio into LiveKit rooms. A process-wide singleton so the playback registry (and the `room_finished` cleanup
+ * that reads it) is shared by every caller.
+ */
+export declare class RoomAudioPlayer extends BaseSingleton<RoomAudioPlayer> {
+    private readonly active;
+    private readonly decodeCache;
+    private tokenMinter;
+    private loadNativeModule;
+    private nativeModuleSpecifierOverride?;
+    private fileReader;
+    private urlFetcher;
+    private clock;
+    private speechSynthesizer?;
+    private warnedNoSynthesizer;
+    private comfortTone?;
+    /** BaseSingleton requires a protected constructor. */
+    protected constructor();
+    /** The process-wide player. */
+    static get Instance(): RoomAudioPlayer;
+    /**
+     * Installs the text-to-speech used by {@link RoomAudioHandle.Announce} with `{ Text }` — e.g. an
+     * `MJRoomSpeechSynthesizer`. None is installed by default (a voice is vendor-specific); without one a text
+     * announcement returns `false` and the player logs the omission once.
+     *
+     * @param synthesizer The synthesizer, or `undefined` to remove it.
+     */
+    SetSpeechSynthesizer(synthesizer: IRoomSpeechSynthesizer | undefined): void;
+    /** Overrides where bot tokens come from (tests; a host with its own credentials). */
+    SetTokenService(minter: RoomAudioTokenMinter): void;
+    /** Overrides the native room-module loader (tests inject a fake module). */
+    SetNativeModuleLoader(loader: NativeModuleLoader): void;
+    /** Overrides the native room-module specifier; `undefined` returns to `LIVEKIT_NATIVE_MODULE` / the default. */
+    SetNativeModuleSpecifier(specifier: string | undefined): void;
+    /** Overrides how `MJ: Files` bytes are read (tests). */
+    SetFileReader(reader: RoomAudioFileReader): void;
+    /** Overrides how URLs are fetched (tests). */
+    SetUrlFetcher(fetcher: RoomAudioUrlFetcher): void;
+    /** Overrides the pacing clock (tests). */
+    SetClock(clock: PumpClock): void;
+    /** Forgets every cached decode (e.g. after a hold file is replaced under the same id). */
+    ClearDecodeCache(): void;
+    /**
+     * Starts playing `params.Source` into `params.RoomName`: loads and decodes it (cached by source), joins the room as
+     * a publish-only bot, and paces the audio in.
+     *
+     * @returns The live playback.
+     * @throws {Error} when the source cannot be loaded or decoded, LiveKit is not configured, or the bot cannot join.
+     */
+    Start(params: StartRoomAudioParams): Promise<RoomAudioHandle>;
+    /** The live playbacks in a room (room names compare case-insensitively). */
+    GetActive(roomName: string): RoomAudioHandle[];
+    /**
+     * Stops every playback in a room. Never throws.
+     *
+     * @returns How many playbacks were stopped.
+     */
+    StopAllInRoom(roomName: string): Promise<number>;
+    /** Resolves the source to mono PCM16 at {@link ROOM_AUDIO_SAMPLE_RATE}, through the decode cache where it can. */
+    private resolvePcm;
+    private decodeContent;
+    /** Joins the room as the playback's bot, registers the playback, and starts the pump. */
+    private joinAndPlay;
+    /** A publish-only bot token: it never needs to hear the room, and it carries no data channel. */
+    private mintBotToken;
+    /** Connects the bot; on failure always releases the client before rethrowing. */
+    private connectClient;
+    private createPump;
+    private playbackOwner;
+    private deregister;
+    /** The server dropped the bot (room closed, participant removed): stop and forget the playback. */
+    private handleServerDisconnect;
+    private synthesize;
+}
+//# sourceMappingURL=room-audio-player.d.ts.map

package/dist/room-audio/room-audio-player.d.ts.map

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

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

@@ -0,0 +1,404 @@
+/**
+ * @fileoverview {@link RoomAudioPlayer} — joins a LiveKit room as a small publish-only bot and plays audio into it:
+ * contact-center hold music, with spoken announcements ducked over the top ("you are caller number three").
+ *
+ * The audio comes from an `MJ: Files` row, an https URL, raw PCM, or the built-in comfort tone. It is decoded once
+ * (WAV or MP3), resampled to {@link ROOM_AUDIO_SAMPLE_RATE}, cached by source, and paced into the room in 20 ms
+ * frames by a {@link PcmFramePump}. Each playback is a {@link RoomAudioHandle} the caller pauses, resumes, announces
+ * through and stops; the player keeps a registry so a room's playbacks can be found and stopped together (the
+ * `room_finished` webhook does this), and a playback whose bot is disconnected by the server removes itself.
+ *
+ * It reuses the agent bridge's plumbing rather than its own: bot tokens from {@link LiveKitTokenService}, the native
+ * room client through `@memberjunction/ai-bridge-livekit`'s module loader at the same specifier the agent coordinator
+ * resolves, and the PCM16 resampler from `@memberjunction/ai-bridge-base`.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { randomUUID } from 'node:crypto';
+import { BaseSingleton, NormalizeUUID } from '@memberjunction/global';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { ResamplePcm16 } from '@memberjunction/ai-bridge-base';
+import { DefaultNativeLoader } from '@memberjunction/ai-bridge-livekit';
+import { LiveKitTokenService } from '../livekit-token-service.js';
+import { ResolveLiveKitNativeModuleSpecifier } from '../livekit-native-module.js';
+import { AssertAudioDurationWithinCap, DecodeAudio } from './audio-decoder.js';
+import { GenerateComfortTone } from './comfort-tone.js';
+import { PcmFramePump, SystemPumpClock } from './pcm-frame-pump.js';
+import { RoomAudioDecodeCache } from './room-audio-decode-cache.js';
+import { AssertHttpsAudioUrl, FetchRoomAudioUrl, ReadMJFileAudio, } from './room-audio-sources.js';
+/** How often a finished playback checks whether its already-sent audio has played out, in ms. */
+const DRAIN_TICK_MS = 10;
+/** The rate the player publishes at (Hz). Music sounds noticeably duller at the 24 kHz the agent voice uses. */
+export const ROOM_AUDIO_SAMPLE_RATE = 48000;
+/** One playback: its bot's room client and its frame pump. Created only by {@link RoomAudioPlayer}. */
+class RoomAudioPlayback {
+    constructor(PlaybackID, RoomName, client, contextUser, owner) {
+        this.PlaybackID = PlaybackID;
+        this.RoomName = RoomName;
+        this.client = client;
+        this.contextUser = contextUser;
+        this.owner = owner;
+        this.pump = null;
+        this.stopPromise = null;
+        this.endReason = null;
+        this.drainTicker = null;
+        this.resolveEnded = () => undefined;
+        this.Ended = new Promise((resolve) => {
+            this.resolveEnded = resolve;
+        });
+    }
+    get EndReason() {
+        return this.endReason;
+    }
+    get IsPlaying() {
+        return this.stopPromise === null && this.pump !== null && this.pump.IsRunning && !this.pump.IsPaused;
+    }
+    /** True once {@link Stop} has begun. */
+    get IsStopped() {
+        return this.stopPromise !== null;
+    }
+    /** Attaches and starts the pump (once the bot is in the room). */
+    Play(pump) {
+        this.pump = pump;
+        pump.Start();
+    }
+    async Announce(clip) {
+        if (this.IsStopped || !this.pump) {
+            return false;
+        }
+        try {
+            const audio = 'Text' in clip ? await this.owner.Synthesize(clip.Text, this.contextUser) : validateClipPcm(clip);
+            if (!audio || this.IsStopped) {
+                return false;
+            }
+            return await this.pump.InsertClip(ResamplePcm16(audio.Pcm, audio.SampleRate, ROOM_AUDIO_SAMPLE_RATE));
+        }
+        catch (err) {
+            LogError(`[RoomAudioPlayer] announcement in room ${this.RoomName} (playback ${this.PlaybackID}) failed: ${errorText(err)}`);
+            return false;
+        }
+    }
+    Pause() {
+        this.pump?.Pause();
+    }
+    Resume() {
+        this.pump?.Resume();
+    }
+    Stop() {
+        return this.EndWith('Stopped');
+    }
+    /**
+     * Ends the playback for `reason` (the first reason recorded wins), stops the pump, disconnects the bot, and
+     * resolves {@link Ended} once the bot has left. Idempotent; never rejects.
+     */
+    EndWith(reason) {
+        this.endReason ??= reason;
+        this.stopPromise ??= this.stopOnce();
+        return this.stopPromise;
+    }
+    /**
+     * The audio ran out: wait until the frames already sent ahead of real time have played, then end `Completed`, so
+     * the bot does not leave (dropping its queued tail) before the last of the clip is heard. A Stop or server
+     * disconnect during the wait wins instead.
+     */
+    CompleteAfterDrain(clock) {
+        const drainMs = this.pump?.QueuedAheadMs ?? 0;
+        if (drainMs <= 0 || this.IsStopped) {
+            void this.EndWith('Completed');
+            return;
+        }
+        const deadline = clock.Now() + drainMs;
+        this.drainTicker = clock.StartTicker(() => {
+            if (clock.Now() >= deadline) {
+                void this.EndWith('Completed');
+            }
+        }, DRAIN_TICK_MS);
+    }
+    /** Stops the pump, then always disconnects the bot and leaves the registry, whatever failed before. */
+    async stopOnce() {
+        this.drainTicker?.Cancel();
+        this.drainTicker = null;
+        try {
+            this.pump?.Stop();
+        }
+        catch (err) {
+            LogError(`[RoomAudioPlayer] stopping the pump for playback ${this.PlaybackID} failed: ${errorText(err)}`);
+        }
+        finally {
+            try {
+                await this.client.disconnect();
+            }
+            catch (err) {
+                LogError(`[RoomAudioPlayer] disconnecting playback ${this.PlaybackID} from room ${this.RoomName} failed: ${errorText(err)}`);
+            }
+            finally {
+                this.owner.Deregister(this);
+                this.resolveEnded(this.endReason ?? 'Stopped');
+            }
+        }
+    }
+}
+/**
+ * Plays audio into LiveKit rooms. A process-wide singleton so the playback registry (and the `room_finished` cleanup
+ * that reads it) is shared by every caller.
+ */
+export class RoomAudioPlayer extends BaseSingleton {
+    /** BaseSingleton requires a protected constructor. */
+    constructor() {
+        super();
+        this.active = new Map();
+        this.decodeCache = new RoomAudioDecodeCache();
+        this.tokenMinter = new LiveKitTokenService();
+        this.loadNativeModule = DefaultNativeLoader;
+        this.fileReader = ReadMJFileAudio;
+        this.urlFetcher = FetchRoomAudioUrl;
+        this.clock = SystemPumpClock;
+        this.warnedNoSynthesizer = false;
+    }
+    /** The process-wide player. */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /**
+     * Installs the text-to-speech used by {@link RoomAudioHandle.Announce} with `{ Text }` — e.g. an
+     * `MJRoomSpeechSynthesizer`. None is installed by default (a voice is vendor-specific); without one a text
+     * announcement returns `false` and the player logs the omission once.
+     *
+     * @param synthesizer The synthesizer, or `undefined` to remove it.
+     */
+    SetSpeechSynthesizer(synthesizer) {
+        this.speechSynthesizer = synthesizer;
+        this.warnedNoSynthesizer = false;
+    }
+    /** Overrides where bot tokens come from (tests; a host with its own credentials). */
+    SetTokenService(minter) {
+        this.tokenMinter = minter;
+    }
+    /** Overrides the native room-module loader (tests inject a fake module). */
+    SetNativeModuleLoader(loader) {
+        this.loadNativeModule = loader;
+    }
+    /** Overrides the native room-module specifier; `undefined` returns to `LIVEKIT_NATIVE_MODULE` / the default. */
+    SetNativeModuleSpecifier(specifier) {
+        this.nativeModuleSpecifierOverride = specifier;
+    }
+    /** Overrides how `MJ: Files` bytes are read (tests). */
+    SetFileReader(reader) {
+        this.fileReader = reader;
+    }
+    /** Overrides how URLs are fetched (tests). */
+    SetUrlFetcher(fetcher) {
+        this.urlFetcher = fetcher;
+    }
+    /** Overrides the pacing clock (tests). */
+    SetClock(clock) {
+        this.clock = clock;
+    }
+    /** Forgets every cached decode (e.g. after a hold file is replaced under the same id). */
+    ClearDecodeCache() {
+        this.decodeCache.Clear();
+    }
+    /**
+     * Starts playing `params.Source` into `params.RoomName`: loads and decodes it (cached by source), joins the room as
+     * a publish-only bot, and paces the audio in.
+     *
+     * @returns The live playback.
+     * @throws {Error} when the source cannot be loaded or decoded, LiveKit is not configured, or the bot cannot join.
+     */
+    async Start(params) {
+        assertStartParams(params);
+        const pcm = await this.resolvePcm(params);
+        return this.joinAndPlay(params, pcm);
+    }
+    /** The live playbacks in a room (room names compare case-insensitively). */
+    GetActive(roomName) {
+        const key = roomKey(roomName);
+        return [...this.active.values()].filter((playback) => roomKey(playback.RoomName) === key);
+    }
+    /**
+     * Stops every playback in a room. Never throws.
+     *
+     * @returns How many playbacks were stopped.
+     */
+    async StopAllInRoom(roomName) {
+        const playbacks = this.GetActive(roomName);
+        await Promise.all(playbacks.map((playback) => playback.Stop()));
+        if (playbacks.length > 0) {
+            LogStatus(`[RoomAudioPlayer] stopped ${playbacks.length} playback(s) in room ${roomName}`);
+        }
+        return playbacks.length;
+    }
+    // ── Loading ────────────────────────────────────────────────────────────────────────────────────────────────────
+    /** Resolves the source to mono PCM16 at {@link ROOM_AUDIO_SAMPLE_RATE}, through the decode cache where it can. */
+    async resolvePcm(params) {
+        const source = params.Source;
+        switch (source.Kind) {
+            case 'ComfortTone':
+                this.comfortTone ??= GenerateComfortTone(ROOM_AUDIO_SAMPLE_RATE);
+                return this.comfortTone;
+            case 'Pcm':
+                return resampleToRoomRate(validateClipPcm(source));
+            case 'File':
+                return this.decodeCache.GetOrLoad(`file:${NormalizeUUID(source.FileID)}`, async () => this.decodeContent(await this.fileReader(source.FileID, params.ContextUser, params.Provider)));
+            case 'Url': {
+                const url = AssertHttpsAudioUrl(source.Url).href; // refuse plain http before anything is fetched
+                return this.decodeCache.GetOrLoad(`url:${url}`, async () => this.decodeContent(await this.urlFetcher(url)));
+            }
+            default:
+                return assertNeverSource(source);
+        }
+    }
+    async decodeContent(content) {
+        const decoded = await DecodeAudio(content.Bytes, { MimeType: content.MimeType, FileName: content.FileName });
+        return resampleToRoomRate(decoded);
+    }
+    // ── Joining ────────────────────────────────────────────────────────────────────────────────────────────────────
+    /** Joins the room as the playback's bot, registers the playback, and starts the pump. */
+    async joinAndPlay(params, pcm) {
+        const playbackID = randomUUID();
+        const displayName = params.DisplayName ?? 'On hold';
+        const token = await this.mintBotToken(params.RoomName, params.Identity ?? `hold-${playbackID}`, displayName);
+        const roomModule = await this.loadNativeModule(ResolveLiveKitNativeModuleSpecifier(this.nativeModuleSpecifierOverride));
+        const client = roomModule.createRoomClient({ OutboundSampleRate: ROOM_AUDIO_SAMPLE_RATE, InboundSampleRate: ROOM_AUDIO_SAMPLE_RATE });
+        const playback = new RoomAudioPlayback(playbackID, params.RoomName, client, params.ContextUser, this.playbackOwner());
+        client.onDisconnected(() => this.handleServerDisconnect(playback));
+        await this.connectClient(client, token, displayName);
+        if (playback.IsStopped) {
+            throw new Error(`Room audio bot was disconnected from room ${params.RoomName} as soon as it joined.`);
+        }
+        this.active.set(playbackID, playback);
+        playback.Play(this.createPump(playback, client, pcm, params.Loop ?? true));
+        LogStatus(`[RoomAudioPlayer] playing ${describeSource(params.Source)} into room ${params.RoomName} (playback ${playbackID})`);
+        return playback;
+    }
+    /** A publish-only bot token: it never needs to hear the room, and it carries no data channel. */
+    mintBotToken(roomName, identity, displayName) {
+        return this.tokenMinter.MintToken({
+            RoomName: roomName,
+            Identity: identity,
+            DisplayName: displayName,
+            Role: 'agent',
+            CanSubscribe: false,
+            CanPublishData: false,
+            Metadata: { mjRoomAudio: true },
+        });
+    }
+    /** Connects the bot; on failure always releases the client before rethrowing. */
+    async connectClient(client, token, displayName) {
+        try {
+            await client.connect({ url: token.ServerUrl, token: token.Token, name: displayName });
+        }
+        catch (err) {
+            try {
+                await client.disconnect();
+            }
+            catch (disconnectErr) {
+                LogError(`[RoomAudioPlayer] releasing a client that failed to join room ${token.RoomName} also failed: ${errorText(disconnectErr)}`);
+            }
+            throw new Error(`Room audio could not join room ${token.RoomName}: ${errorText(err)}`);
+        }
+    }
+    createPump(playback, client, pcm, loop) {
+        return new PcmFramePump({
+            Music: pcm,
+            SampleRate: ROOM_AUDIO_SAMPLE_RATE,
+            Loop: loop,
+            Clock: this.clock,
+            Sink: (frame) => client.publishAudio(frame.buffer),
+            OnEnded: (reason) => {
+                // 'Stopped' means the playback stopped the pump itself; otherwise the audio ran out (no loop) or the sink
+                // broke, and the bot leaves the room with that reason.
+                if (reason === 'Completed') {
+                    playback.CompleteAfterDrain(this.clock);
+                }
+                else if (reason === 'SinkError') {
+                    void playback.EndWith('Failed');
+                }
+            },
+        });
+    }
+    // ── Registry + speech ──────────────────────────────────────────────────────────────────────────────────────────
+    playbackOwner() {
+        return {
+            Synthesize: (text, contextUser) => this.synthesize(text, contextUser),
+            Deregister: (playback) => this.deregister(playback),
+        };
+    }
+    deregister(playback) {
+        if (this.active.get(playback.PlaybackID) === playback) {
+            this.active.delete(playback.PlaybackID);
+        }
+    }
+    /** The server dropped the bot (room closed, participant removed): stop and forget the playback. */
+    handleServerDisconnect(playback) {
+        if (!playback.IsStopped) {
+            LogStatus(`[RoomAudioPlayer] playback ${playback.PlaybackID} was disconnected from room ${playback.RoomName}; stopping it`);
+            void playback.EndWith('Disconnected');
+        }
+    }
+    async synthesize(text, contextUser) {
+        if (!this.speechSynthesizer) {
+            if (!this.warnedNoSynthesizer) {
+                this.warnedNoSynthesizer = true;
+                LogError('[RoomAudioPlayer] a text announcement was requested but no speech synthesizer is installed; it was skipped. ' +
+                    'Call RoomAudioPlayer.Instance.SetSpeechSynthesizer(new MJRoomSpeechSynthesizer({ Voice: ... })) at startup.');
+            }
+            return null;
+        }
+        try {
+            return await this.speechSynthesizer.Synthesize(text, contextUser);
+        }
+        catch (err) {
+            LogError(`[RoomAudioPlayer] the speech synthesizer failed: ${errorText(err)}`);
+            return null;
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────────────────────────────────────────
+function assertStartParams(params) {
+    if (!params.RoomName?.trim()) {
+        throw new Error('RoomAudioPlayer.Start needs a RoomName.');
+    }
+    if (!params.ContextUser) {
+        throw new Error('RoomAudioPlayer.Start needs a ContextUser (the user the audio is loaded as).');
+    }
+    if (!params.Source) {
+        throw new Error('RoomAudioPlayer.Start needs a Source.');
+    }
+}
+/** Checks caller-supplied PCM: non-empty, a positive rate, and within the duration cap. */
+function validateClipPcm(clip) {
+    if (!(clip.SampleRate > 0)) {
+        throw new Error(`Room audio PCM needs a positive SampleRate; got ${clip.SampleRate}.`);
+    }
+    if (clip.Pcm.length === 0) {
+        throw new Error('Room audio PCM is empty.');
+    }
+    AssertAudioDurationWithinCap(clip.Pcm.length, clip.SampleRate);
+    return { Pcm: clip.Pcm, SampleRate: clip.SampleRate };
+}
+function resampleToRoomRate(audio) {
+    return ResamplePcm16(audio.Pcm, audio.SampleRate, ROOM_AUDIO_SAMPLE_RATE);
+}
+function describeSource(source) {
+    switch (source.Kind) {
+        case 'File':
+            return `file ${source.FileID}`;
+        case 'Url':
+            return `url ${source.Url}`;
+        case 'Pcm':
+            return 'caller-supplied PCM';
+        default:
+            return 'the comfort tone';
+    }
+}
+function assertNeverSource(source) {
+    throw new Error(`Unknown room audio source kind: ${JSON.stringify(source)}`);
+}
+function roomKey(roomName) {
+    return roomName.trim().toLowerCase();
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=room-audio-player.js.map

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

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

package/dist/room-audio/room-audio-sources.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Where the room audio player gets an audio file's bytes: an `MJ: Files` row (read from its storage
+ * provider through `@memberjunction/storage`), or an https URL (fetched through the SSRF-safe `SafeFetch`, with a
+ * timeout and a byte cap). Both return {@link RoomAudioFileContent}, which `DecodeAudio` turns into PCM.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+/** An audio file's bytes plus what is known about its format. */
+export interface RoomAudioFileContent {
+    /** The file's bytes. */
+    Bytes: Uint8Array;
+    /** The MIME type, when known. */
+    MimeType?: string;
+    /** The file name, when known. */
+    FileName?: string;
+}
+/** Reads an `MJ: Files` row's bytes. The default is {@link ReadMJFileAudio}; tests inject a fake. */
+export type RoomAudioFileReader = (fileID: string, contextUser: UserInfo, provider?: IMetadataProvider) => Promise<RoomAudioFileContent>;
+/** Fetches an https URL's bytes. The default is {@link FetchRoomAudioUrl}; tests inject a fake. */
+export type RoomAudioUrlFetcher = (url: string) => Promise<RoomAudioFileContent>;
+/** The largest file the player will download from a URL, in bytes (25 MB). */
+export declare const MAX_ROOM_AUDIO_URL_BYTES: number;
+/** How long a URL download may take before it is abandoned, in ms. */
+export declare const ROOM_AUDIO_URL_TIMEOUT_MS = 20000;
+/**
+ * Reads an `MJ: Files` row's bytes from its storage provider, as the given user (so the user's read permission on
+ * the file applies).
+ *
+ * @throws {Error} when the row cannot be loaded, no storage account serves its provider, or the download fails.
+ */
+export declare function ReadMJFileAudio(fileID: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<RoomAudioFileContent>;
+/**
+ * Checks that `url` is an absolute https URL. The player refuses plain http: hold audio is fetched by the server, and
+ * a cleartext fetch would let anyone on the path substitute what callers hear.
+ *
+ * @throws {Error} when the URL is malformed or not https.
+ */
+export declare function AssertHttpsAudioUrl(url: string): URL;
+/**
+ * Downloads an https audio URL through `SafeFetch` (every redirect hop re-checked against private/reserved
+ * addresses), abandoning it after {@link ROOM_AUDIO_URL_TIMEOUT_MS} or once it passes {@link MAX_ROOM_AUDIO_URL_BYTES}.
+ *
+ * @throws {Error} on a non-https URL, an HTTP error status, a timeout, or a body over the byte cap.
+ */
+export declare function FetchRoomAudioUrl(url: string): Promise<RoomAudioFileContent>;
+//# sourceMappingURL=room-audio-sources.d.ts.map