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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"room-audio-sources.d.ts","sourceRoot":"","sources":["../../src/room-audio/room-audio-sources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,KAAK,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAKjG,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qGAAqG;AACrG,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEzI,mGAAmG;AACnG,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEjF,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAEzD,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAoBxI;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAWpD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAclF"}

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

@@ -0,0 +1,116 @@
+/**
+ * @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 { LogError, Metadata } from '@memberjunction/core';
+import { FileStorageEngine } from '@memberjunction/storage';
+import { SafeFetch } from '@memberjunction/network-utils';
+/** The largest file the player will download from a URL, in bytes (25 MB). */
+export const MAX_ROOM_AUDIO_URL_BYTES = 25 * 1024 * 1024;
+/** How long a URL download may take before it is abandoned, in ms. */
+export const ROOM_AUDIO_URL_TIMEOUT_MS = 20_000;
+/**
+ * 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 async function ReadMJFileAudio(fileID, contextUser, provider) {
+    const md = provider ?? Metadata.Provider;
+    const file = await md.GetEntityObject('MJ: Files', contextUser);
+    const loaded = await file.Load(fileID);
+    if (!loaded) {
+        const detail = file.LatestResult?.CompleteMessage || 'not found, or not readable by this user';
+        throw new Error(`Hold audio file ${fileID} could not be loaded from MJ: Files: ${detail}.`);
+    }
+    await FileStorageEngine.Instance.Config(false, contextUser, provider);
+    const accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+    if (accounts.length === 0) {
+        throw new Error(`Hold audio file ${fileID} ('${file.Name}') is on storage provider ${file.Provider}, which has no configured storage account.`);
+    }
+    const driver = await FileStorageEngine.Instance.GetDriver(accounts[0].ID, contextUser);
+    const buffer = await driver.GetObject({ fullPath: file.ProviderKey ?? file.Name });
+    return {
+        Bytes: new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength),
+        MimeType: file.ContentType ?? undefined,
+        FileName: file.Name,
+    };
+}
+/**
+ * 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 function AssertHttpsAudioUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Hold audio URL is not a valid URL: '${url}'.`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`Hold audio URL must use https; got '${parsed.protocol}' in '${url}'.`);
+    }
+    return parsed;
+}
+/**
+ * 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 async function FetchRoomAudioUrl(url) {
+    const parsed = AssertHttpsAudioUrl(url);
+    const response = await SafeFetch(parsed.href, { signal: AbortSignal.timeout(ROOM_AUDIO_URL_TIMEOUT_MS) });
+    if (!response.ok) {
+        void response.body?.cancel();
+        throw new Error(`Hold audio URL returned HTTP ${response.status}: '${url}'.`);
+    }
+    const declared = Number(response.headers.get('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > MAX_ROOM_AUDIO_URL_BYTES) {
+        void response.body?.cancel();
+        throw new Error(`Hold audio URL is ${declared} bytes; the limit is ${MAX_ROOM_AUDIO_URL_BYTES} bytes: '${url}'.`);
+    }
+    const bytes = await readBodyWithCap(response, url);
+    return { Bytes: bytes, MimeType: response.headers.get('content-type') ?? undefined, FileName: parsed.pathname.split('/').pop() };
+}
+/** Reads a response body, stopping (and cancelling the stream) the moment it passes the byte cap. */
+async function readBodyWithCap(response, url) {
+    if (!response.body) {
+        return new Uint8Array(0);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+            total += chunk.value.byteLength;
+            if (total > MAX_ROOM_AUDIO_URL_BYTES) {
+                throw new Error(`Hold audio URL exceeded the ${MAX_ROOM_AUDIO_URL_BYTES}-byte limit: '${url}'.`);
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        if (total > MAX_ROOM_AUDIO_URL_BYTES) {
+            await reader.cancel().catch((err) => LogError(`[RoomAudioPlayer] cancelling the oversize download of '${url}' failed: ${err.message}`));
+        }
+        reader.releaseLock();
+    }
+    return concatChunks(chunks, total);
+}
+function concatChunks(chunks, total) {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+//# sourceMappingURL=room-audio-sources.js.map

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

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

package/dist/room-audio/room-speech-synthesizer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview The text-to-speech port the room audio player announces through ({@link IRoomSpeechSynthesizer}),
+ * and {@link MJRoomSpeechSynthesizer}, an implementation over MJ's own `AITextToSpeechRunner` (model selection,
+ * credentials, failover and an `MJ: AI Prompt Runs` row, all handled there).
+ *
+ * The player ships with NO synthesizer installed, because a voice is vendor-specific and only the host knows which
+ * one its callers should hear. A host opts in once at startup:
+ *
+ * ```ts
+ * RoomAudioPlayer.Instance.SetSpeechSynthesizer(new MJRoomSpeechSynthesizer({ Voice: 'alloy' }));
+ * ```
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { type UserInfo } from '@memberjunction/core';
+import { AITextToSpeechRunner } from '@memberjunction/ai-prompts';
+import { type DecodedAudio } from './audio-decoder.js';
+/** Turns announcement text into audio. Return `null` when speech could not be produced (and log why). */
+export interface IRoomSpeechSynthesizer {
+    /**
+     * Speaks `text`.
+     *
+     * @param text What to say.
+     * @param contextUser The user the synthesis runs (and is logged) as.
+     * @returns The audio, or `null` when it could not be produced.
+     */
+    Synthesize(text: string, contextUser: UserInfo): Promise<DecodedAudio | null>;
+}
+/** Options for {@link MJRoomSpeechSynthesizer}. */
+export interface MJRoomSpeechSynthesizerOptions {
+    /** The provider-native voice id or name (required: voices belong to a vendor). */
+    Voice: string;
+    /** Pins the TTS model by ID. Recommended whenever the voice matters, since voices are vendor-specific. */
+    ModelID?: string;
+    /** The carrier `MJ: AI Prompts` row whose bindings choose the model. Default: the runner's `Default Text To Speech`. */
+    PromptID?: string;
+    /** The vendor's output format string (e.g. `mp3_44100_128`). Default: the vendor's default (MP3 or WAV decode either way). */
+    OutputFormat?: string;
+}
+/** The part of `AITextToSpeechRunner` the synthesizer uses — a seam so tests inject a fake. */
+export type TextToSpeechRunnerLike = Pick<AITextToSpeechRunner, 'RunTextToSpeech'>;
+/** An {@link IRoomSpeechSynthesizer} backed by MJ's `AITextToSpeechRunner`. Never throws: failures log and return `null`. */
+export declare class MJRoomSpeechSynthesizer implements IRoomSpeechSynthesizer {
+    private readonly options;
+    private readonly runner;
+    /**
+     * @param options The voice and model selection.
+     * @param runner The runner (tests); defaults to a new `AITextToSpeechRunner`.
+     * @throws {Error} when no voice is given.
+     */
+    constructor(options: MJRoomSpeechSynthesizerOptions, runner?: TextToSpeechRunnerLike);
+    /** Speaks `text` through the configured TTS model and decodes the result to PCM. */
+    Synthesize(text: string, contextUser: UserInfo): Promise<DecodedAudio | null>;
+}
+//# sourceMappingURL=room-speech-synthesizer.d.ts.map