@livekit/agents 1.0.11 → 1.0.13

package/dist/voice/background_audio.js

@@ -0,0 +1,301 @@
+import {
+  AudioFrame,
+  AudioSource,
+  LocalAudioTrack,
+  TrackPublishOptions
+} from "@livekit/rtc-node";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { audioFramesFromFile, loopAudioFramesFromFile } from "../audio.js";
+import { log } from "../log.js";
+import { Future, Task, cancelAndWait } from "../utils.js";
+import { AgentSessionEventTypes } from "./events.js";
+const TASK_TIMEOUT_MS = 500;
+var BuiltinAudioClip = /* @__PURE__ */ ((BuiltinAudioClip2) => {
+  BuiltinAudioClip2["OFFICE_AMBIENCE"] = "office-ambience.ogg";
+  BuiltinAudioClip2["KEYBOARD_TYPING"] = "keyboard-typing.ogg";
+  BuiltinAudioClip2["KEYBOARD_TYPING2"] = "keyboard-typing2.ogg";
+  return BuiltinAudioClip2;
+})(BuiltinAudioClip || {});
+function isBuiltinAudioClip(source) {
+  return typeof source === "string" && Object.values(BuiltinAudioClip).includes(source);
+}
+function getBuiltinAudioPath(clip) {
+  const resourcesPath = join(dirname(fileURLToPath(import.meta.url)), "../../resources");
+  return join(resourcesPath, clip);
+}
+const AUDIO_SOURCE_BUFFER_MS = 400;
+class PlayHandle {
+  doneFuture = new Future();
+  stopFuture = new Future();
+  done() {
+    return this.doneFuture.done;
+  }
+  stop() {
+    if (this.done()) return;
+    if (!this.stopFuture.done) {
+      this.stopFuture.resolve();
+    }
+    this._markPlayoutDone();
+  }
+  async waitForPlayout() {
+    return this.doneFuture.await;
+  }
+  _markPlayoutDone() {
+    if (!this.doneFuture.done) {
+      this.doneFuture.resolve();
+    }
+  }
+}
+class BackgroundAudioPlayer {
+  ambientSound;
+  thinkingSound;
+  playTasks = [];
+  audioSource = new AudioSource(48e3, 1, AUDIO_SOURCE_BUFFER_MS);
+  room;
+  agentSession;
+  publication;
+  trackPublishOptions;
+  republishTask;
+  ambientHandle;
+  thinkingHandle;
+  // TODO (Brian): add lock
+  #logger = log();
+  constructor(options) {
+    const { ambientSound, thinkingSound } = options || {};
+    this.ambientSound = ambientSound;
+    this.thinkingSound = thinkingSound;
+    if (this.thinkingSound) {
+      this.#logger.warn("thinkingSound is not yet supported");
+    }
+  }
+  /**
+   * Select a sound from a list of background sound based on probability weights
+   * Return undefined if no sound is selected (when sum of probabilities < 1.0).
+   */
+  selectSoundFromList(sounds) {
+    const totalProbability = sounds.reduce((sum, sound) => sum + (sound.probability ?? 1), 0);
+    if (totalProbability <= 0) {
+      return void 0;
+    }
+    if (totalProbability < 1 && Math.random() > totalProbability) {
+      return void 0;
+    }
+    const normalizeFactor = totalProbability <= 1 ? 1 : totalProbability;
+    const r = Math.random() * Math.min(totalProbability, 1);
+    let cumulative = 0;
+    for (const sound of sounds) {
+      const prob = sound.probability ?? 1;
+      if (prob <= 0) {
+        continue;
+      }
+      const normProb = prob / normalizeFactor;
+      cumulative += normProb;
+      if (r <= cumulative) {
+        return sound;
+      }
+    }
+    return sounds[sounds.length - 1];
+  }
+  normalizeSoundSource(source) {
+    if (source === void 0) {
+      return void 0;
+    }
+    if (typeof source === "string") {
+      return {
+        source: this.normalizeBuiltinAudio(source),
+        volume: 1
+      };
+    }
+    if (Array.isArray(source)) {
+      const selected = this.selectSoundFromList(source);
+      if (selected === void 0) {
+        return void 0;
+      }
+      return {
+        source: selected.source,
+        volume: selected.volume ?? 1
+      };
+    }
+    if (typeof source === "object" && "source" in source) {
+      return {
+        source: this.normalizeBuiltinAudio(source.source),
+        volume: source.volume ?? 1
+      };
+    }
+    return { source, volume: 1 };
+  }
+  normalizeBuiltinAudio(source) {
+    if (isBuiltinAudioClip(source)) {
+      return getBuiltinAudioPath(source);
+    }
+    return source;
+  }
+  play(audio, loop = false) {
+    const normalized = this.normalizeSoundSource(audio);
+    if (normalized === void 0) {
+      const handle = new PlayHandle();
+      handle._markPlayoutDone();
+      return handle;
+    }
+    const { source, volume } = normalized;
+    const playHandle = new PlayHandle();
+    const task = Task.from(async ({ signal }) => {
+      await this.playTask({ playHandle, sound: source, volume, loop, signal });
+    });
+    task.addDoneCallback(() => {
+      playHandle._markPlayoutDone();
+      this.playTasks.splice(this.playTasks.indexOf(task), 1);
+    });
+    this.playTasks.push(task);
+    return playHandle;
+  }
+  /**
+   * Start the background audio system, publishing the audio track
+   * and beginning playback of any configured ambient sound.
+   *
+   * If `ambientSound` is provided (and contains file paths), they will loop
+   * automatically. If `ambientSound` contains AsyncIterators, they are assumed
+   * to be already infinite or looped.
+   *
+   * @param options - Options for starting background audio playback
+   */
+  async start(options) {
+    var _a;
+    const { room, agentSession, trackPublishOptions } = options;
+    this.room = room;
+    this.agentSession = agentSession;
+    this.trackPublishOptions = trackPublishOptions;
+    await this.publishTrack();
+    this.room.on("reconnected", this.onReconnected);
+    (_a = this.agentSession) == null ? void 0 : _a.on(AgentSessionEventTypes.AgentStateChanged, this.onAgentStateChanged);
+    if (!this.ambientSound) return;
+    const normalized = this.normalizeSoundSource(this.ambientSound);
+    if (!normalized) return;
+    const { source, volume } = normalized;
+    const selectedSound = { source, volume, probability: 1 };
+    this.ambientHandle = this.play(selectedSound, typeof source === "string");
+  }
+  /**
+   * Close and cleanup the background audio system
+   */
+  async close() {
+    var _a, _b, _c, _d;
+    await cancelAndWait(this.playTasks, TASK_TIMEOUT_MS);
+    if (this.republishTask) {
+      await this.republishTask.cancelAndWait(TASK_TIMEOUT_MS);
+    }
+    await this.audioSource.close();
+    (_a = this.agentSession) == null ? void 0 : _a.off(AgentSessionEventTypes.AgentStateChanged, this.onAgentStateChanged);
+    (_b = this.room) == null ? void 0 : _b.off("reconnected", this.onReconnected);
+    if (this.publication && this.publication.sid) {
+      await ((_d = (_c = this.room) == null ? void 0 : _c.localParticipant) == null ? void 0 : _d.unpublishTrack(this.publication.sid));
+    }
+  }
+  /**
+   * Get the current track publication
+   */
+  getPublication() {
+    return this.publication;
+  }
+  async publishTrack() {
+    var _a;
+    if (this.publication !== void 0) {
+      return;
+    }
+    const track = LocalAudioTrack.createAudioTrack("background_audio", this.audioSource);
+    if (((_a = this.room) == null ? void 0 : _a.localParticipant) === void 0) {
+      throw new Error("Local participant not available");
+    }
+    const publication = await this.room.localParticipant.publishTrack(
+      track,
+      this.trackPublishOptions ?? new TrackPublishOptions()
+    );
+    this.publication = publication;
+    this.#logger.debug(`Background audio track published: ${this.publication.sid}`);
+  }
+  onReconnected = () => {
+    if (this.republishTask) {
+      this.republishTask.cancel();
+    }
+    this.publication = void 0;
+    this.republishTask = Task.from(async () => {
+      await this.republishTrackTask();
+    });
+  };
+  async republishTrackTask() {
+    await this.publishTrack();
+  }
+  onAgentStateChanged = (ev) => {
+    var _a;
+    if (!this.thinkingSound) {
+      return;
+    }
+    if (ev.newState === "thinking") {
+      if (this.thinkingHandle && !this.thinkingHandle.done()) {
+        return;
+      }
+    } else {
+      (_a = this.thinkingHandle) == null ? void 0 : _a.stop();
+    }
+  };
+  async playTask({
+    playHandle,
+    sound,
+    volume,
+    loop,
+    signal
+  }) {
+    if (isBuiltinAudioClip(sound)) {
+      sound = getBuiltinAudioPath(sound);
+    }
+    if (typeof sound === "string") {
+      sound = loop ? loopAudioFramesFromFile(sound, { abortSignal: signal }) : audioFramesFromFile(sound, { abortSignal: signal });
+    }
+    try {
+      for await (const frame of sound) {
+        if (signal.aborted || playHandle.done()) break;
+        let processedFrame;
+        if (volume !== 1) {
+          const int16Data = new Int16Array(
+            frame.data.buffer,
+            frame.data.byteOffset,
+            frame.data.byteLength / 2
+          );
+          const float32Data = new Float32Array(int16Data.length);
+          for (let i = 0; i < int16Data.length; i++) {
+            float32Data[i] = int16Data[i];
+          }
+          const volumeFactor = 10 ** Math.log10(volume);
+          for (let i = 0; i < float32Data.length; i++) {
+            float32Data[i] *= volumeFactor;
+          }
+          const outputData = new Int16Array(float32Data.length);
+          for (let i = 0; i < float32Data.length; i++) {
+            const clipped = Math.max(-32768, Math.min(32767, float32Data[i]));
+            outputData[i] = Math.round(clipped);
+          }
+          processedFrame = new AudioFrame(
+            outputData,
+            frame.sampleRate,
+            frame.channels,
+            frame.samplesPerChannel
+          );
+        } else {
+          processedFrame = frame;
+        }
+        await this.audioSource.captureFrame(processedFrame);
+      }
+    } finally {
+      playHandle._markPlayoutDone();
+    }
+  }
+}
+export {
+  BackgroundAudioPlayer,
+  BuiltinAudioClip,
+  PlayHandle,
+  getBuiltinAudioPath,
+  isBuiltinAudioClip
+};
+//# sourceMappingURL=background_audio.js.map

package/dist/voice/background_audio.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/voice/background_audio.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport {\n  AudioFrame,\n  AudioSource,\n  LocalAudioTrack,\n  type LocalTrackPublication,\n  type Room,\n  TrackPublishOptions,\n} from '@livekit/rtc-node';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { audioFramesFromFile, loopAudioFramesFromFile } from '../audio.js';\nimport { log } from '../log.js';\nimport { Future, Task, cancelAndWait } from '../utils.js';\nimport type { AgentSession } from './agent_session.js';\nimport { AgentSessionEventTypes, type AgentStateChangedEvent } from './events.js';\n\nconst TASK_TIMEOUT_MS = 500;\n\nexport enum BuiltinAudioClip {\n  OFFICE_AMBIENCE = 'office-ambience.ogg',\n  KEYBOARD_TYPING = 'keyboard-typing.ogg',\n  KEYBOARD_TYPING2 = 'keyboard-typing2.ogg',\n}\n\nexport function isBuiltinAudioClip(\n  source: AudioSourceType | AudioConfig | AudioConfig[],\n): source is BuiltinAudioClip {\n  return (\n    typeof source === 'string' &&\n    Object.values(BuiltinAudioClip).includes(source as BuiltinAudioClip)\n  );\n}\n\nexport function getBuiltinAudioPath(clip: BuiltinAudioClip): string {\n  const resourcesPath = join(dirname(fileURLToPath(import.meta.url)), '../../resources');\n  return join(resourcesPath, clip);\n}\n\nexport type AudioSourceType = string | BuiltinAudioClip | AsyncIterable<AudioFrame>;\n\nexport interface AudioConfig {\n  source: AudioSourceType;\n  volume?: number;\n  probability?: number;\n}\n\nexport interface BackgroundAudioPlayerOptions {\n  /**\n   * Ambient sound to play continuously in the background.\n   * Can be a file path, BuiltinAudioClip, or AudioConfig.\n   * File paths will be looped automatically.\n   */\n  ambientSound?: AudioSourceType | AudioConfig | AudioConfig[];\n\n  /**\n   * Sound to play when the agent is thinking.\n   * TODO (Brian): Implement thinking sound when AudioMixer becomes available\n   */\n  thinkingSound?: AudioSourceType | AudioConfig | AudioConfig[];\n\n  /**\n   * Stream timeout in milliseconds\n   * @defaultValue 200\n   */\n  streamTimeoutMs?: number;\n}\n\nexport interface BackgroundAudioStartOptions {\n  room: Room;\n  agentSession?: AgentSession;\n  trackPublishOptions?: TrackPublishOptions;\n}\n\n// Queue size for AudioSource buffer (400ms)\n// Kept small to avoid abrupt cutoffs when removing sounds\nconst AUDIO_SOURCE_BUFFER_MS = 400;\n\nexport class PlayHandle {\n  private doneFuture = new Future<void>();\n  private stopFuture = new Future<void>();\n\n  done(): boolean {\n    return this.doneFuture.done;\n  }\n\n  stop(): void {\n    if (this.done()) return;\n\n    if (!this.stopFuture.done) {\n      this.stopFuture.resolve();\n    }\n\n    this._markPlayoutDone();\n  }\n\n  async waitForPlayout(): Promise<void> {\n    return this.doneFuture.await;\n  }\n\n  _markPlayoutDone(): void {\n    if (!this.doneFuture.done) {\n      this.doneFuture.resolve();\n    }\n  }\n}\n\n/**\n * Manages background audio playback for LiveKit agent sessions\n *\n * This class handles playing ambient sounds and manages audio track publishing.\n * It supports:\n * - Continuous ambient sound playback with looping\n * - Volume control and probability-based sound selection\n * - Integration with LiveKit rooms and agent sessions\n *\n * Note: Thinking sound not yet supported\n *\n * @example\n * ```typescript\n * const player = new BackgroundAudioPlayer({\n *   ambientSound: { source: BuiltinAudioClip.OFFICE_AMBIENCE, volume: 0.8 },\n * });\n *\n * await player.start({ room, agentSession });\n * ```\n */\nexport class BackgroundAudioPlayer {\n  private ambientSound?: AudioSourceType | AudioConfig | AudioConfig[];\n  private thinkingSound?: AudioSourceType | AudioConfig | AudioConfig[];\n\n  private playTasks: Task<void>[] = [];\n  private audioSource = new AudioSource(48000, 1, AUDIO_SOURCE_BUFFER_MS);\n\n  private room?: Room;\n  private agentSession?: AgentSession;\n  private publication?: LocalTrackPublication;\n  private trackPublishOptions?: TrackPublishOptions;\n  private republishTask?: Task<void>;\n\n  private ambientHandle?: PlayHandle;\n  private thinkingHandle?: PlayHandle;\n\n  // TODO (Brian): add lock\n\n  #logger = log();\n\n  constructor(options?: BackgroundAudioPlayerOptions) {\n    const { ambientSound, thinkingSound } = options || {};\n\n    this.ambientSound = ambientSound;\n    this.thinkingSound = thinkingSound;\n\n    if (this.thinkingSound) {\n      this.#logger.warn('thinkingSound is not yet supported');\n      // TODO: Implement thinking sound when AudioMixer becomes available\n    }\n  }\n\n  /**\n   * Select a sound from a list of background sound based on probability weights\n   * Return undefined if no sound is selected (when sum of probabilities < 1.0).\n   */\n  private selectSoundFromList(sounds: AudioConfig[]): AudioConfig | undefined {\n    const totalProbability = sounds.reduce((sum, sound) => sum + (sound.probability ?? 1.0), 0);\n\n    if (totalProbability <= 0) {\n      return undefined;\n    }\n\n    if (totalProbability < 1.0 && Math.random() > totalProbability) {\n      return undefined;\n    }\n\n    const normalizeFactor = totalProbability <= 1.0 ? 1.0 : totalProbability;\n    const r = Math.random() * Math.min(totalProbability, 1.0);\n    let cumulative = 0.0;\n\n    for (const sound of sounds) {\n      const prob = sound.probability ?? 1.0;\n      if (prob <= 0) {\n        continue;\n      }\n\n      const normProb = prob / normalizeFactor;\n      cumulative += normProb;\n\n      if (r <= cumulative) {\n        return sound;\n      }\n    }\n\n    return sounds[sounds.length - 1];\n  }\n\n  private normalizeSoundSource(\n    source?: AudioSourceType | AudioConfig | AudioConfig[],\n  ): { source: AudioSourceType; volume: number } | undefined {\n    if (source === undefined) {\n      return undefined;\n    }\n\n    if (typeof source === 'string') {\n      return {\n        source: this.normalizeBuiltinAudio(source),\n        volume: 1.0,\n      };\n    }\n\n    if (Array.isArray(source)) {\n      const selected = this.selectSoundFromList(source);\n      if (selected === undefined) {\n        return undefined;\n      }\n\n      return {\n        source: selected.source,\n        volume: selected.volume ?? 1.0,\n      };\n    }\n\n    if (typeof source === 'object' && 'source' in source) {\n      return {\n        source: this.normalizeBuiltinAudio(source.source),\n        volume: source.volume ?? 1.0,\n      };\n    }\n\n    return { source, volume: 1.0 };\n  }\n\n  private normalizeBuiltinAudio(source: AudioSourceType): AudioSourceType {\n    if (isBuiltinAudioClip(source)) {\n      return getBuiltinAudioPath(source);\n    }\n    return source;\n  }\n\n  play(audio: AudioSourceType | AudioConfig | AudioConfig[], loop = false): PlayHandle {\n    const normalized = this.normalizeSoundSource(audio);\n    if (normalized === undefined) {\n      const handle = new PlayHandle();\n      handle._markPlayoutDone();\n      return handle;\n    }\n\n    const { source, volume } = normalized;\n    const playHandle = new PlayHandle();\n\n    const task = Task.from(async ({ signal }) => {\n      await this.playTask({ playHandle, sound: source, volume, loop, signal });\n    });\n\n    task.addDoneCallback(() => {\n      playHandle._markPlayoutDone();\n      this.playTasks.splice(this.playTasks.indexOf(task), 1);\n    });\n\n    this.playTasks.push(task);\n    return playHandle;\n  }\n\n  /**\n   * Start the background audio system, publishing the audio track\n   * and beginning playback of any configured ambient sound.\n   *\n   * If `ambientSound` is provided (and contains file paths), they will loop\n   * automatically. If `ambientSound` contains AsyncIterators, they are assumed\n   * to be already infinite or looped.\n   *\n   * @param options - Options for starting background audio playback\n   */\n  async start(options: BackgroundAudioStartOptions): Promise<void> {\n    const { room, agentSession, trackPublishOptions } = options;\n    this.room = room;\n    this.agentSession = agentSession;\n    this.trackPublishOptions = trackPublishOptions;\n\n    await this.publishTrack();\n\n    // TODO (Brian): check job context is not fake\n\n    // TODO (Brian): start audio mixer task\n    this.room.on('reconnected', this.onReconnected);\n\n    this.agentSession?.on(AgentSessionEventTypes.AgentStateChanged, this.onAgentStateChanged);\n\n    if (!this.ambientSound) return;\n\n    const normalized = this.normalizeSoundSource(this.ambientSound);\n    if (!normalized) return;\n\n    const { source, volume } = normalized;\n    const selectedSound: AudioConfig = { source, volume, probability: 1.0 };\n    this.ambientHandle = this.play(selectedSound, typeof source === 'string');\n  }\n\n  /**\n   * Close and cleanup the background audio system\n   */\n  async close(): Promise<void> {\n    await cancelAndWait(this.playTasks, TASK_TIMEOUT_MS);\n\n    if (this.republishTask) {\n      await this.republishTask.cancelAndWait(TASK_TIMEOUT_MS);\n    }\n\n    // TODO (Brian): cancel audio mixer task and close audio mixer\n\n    await this.audioSource.close();\n\n    this.agentSession?.off(AgentSessionEventTypes.AgentStateChanged, this.onAgentStateChanged);\n    this.room?.off('reconnected', this.onReconnected);\n\n    if (this.publication && this.publication.sid) {\n      await this.room?.localParticipant?.unpublishTrack(this.publication.sid);\n    }\n  }\n\n  /**\n   * Get the current track publication\n   */\n  getPublication(): LocalTrackPublication | undefined {\n    return this.publication;\n  }\n\n  private async publishTrack(): Promise<void> {\n    if (this.publication !== undefined) {\n      return;\n    }\n\n    const track = LocalAudioTrack.createAudioTrack('background_audio', this.audioSource);\n\n    if (this.room?.localParticipant === undefined) {\n      throw new Error('Local participant not available');\n    }\n\n    const publication = await this.room.localParticipant.publishTrack(\n      track,\n      this.trackPublishOptions ?? new TrackPublishOptions(),\n    );\n\n    this.publication = publication;\n    this.#logger.debug(`Background audio track published: ${this.publication.sid}`);\n  }\n\n  private onReconnected = (): void => {\n    if (this.republishTask) {\n      this.republishTask.cancel();\n    }\n\n    this.publication = undefined;\n    this.republishTask = Task.from(async () => {\n      await this.republishTrackTask();\n    });\n  };\n\n  private async republishTrackTask(): Promise<void> {\n    // TODO (Brian): add lock protection when implementing lock\n    await this.publishTrack();\n  }\n\n  private onAgentStateChanged = (ev: AgentStateChangedEvent): void => {\n    if (!this.thinkingSound) {\n      return;\n    }\n\n    if (ev.newState === 'thinking') {\n      if (this.thinkingHandle && !this.thinkingHandle.done()) {\n        return;\n      }\n\n      // TODO (Brian): play thinking sound and assign to thinkingHandle\n    } else {\n      this.thinkingHandle?.stop();\n    }\n  };\n\n  private async playTask({\n    playHandle,\n    sound,\n    volume,\n    loop,\n    signal,\n  }: {\n    playHandle: PlayHandle;\n    sound: AudioSourceType;\n    volume: number;\n    loop: boolean;\n    signal: AbortSignal;\n  }): Promise<void> {\n    if (isBuiltinAudioClip(sound)) {\n      sound = getBuiltinAudioPath(sound);\n    }\n\n    if (typeof sound === 'string') {\n      sound = loop\n        ? loopAudioFramesFromFile(sound, { abortSignal: signal })\n        : audioFramesFromFile(sound, { abortSignal: signal });\n    }\n\n    try {\n      for await (const frame of sound) {\n        if (signal.aborted || playHandle.done()) break;\n\n        let processedFrame: AudioFrame;\n\n        if (volume !== 1.0) {\n          const int16Data = new Int16Array(\n            frame.data.buffer,\n            frame.data.byteOffset,\n            frame.data.byteLength / 2,\n          );\n          const float32Data = new Float32Array(int16Data.length);\n\n          for (let i = 0; i < int16Data.length; i++) {\n            float32Data[i] = int16Data[i]!;\n          }\n\n          const volumeFactor = 10 ** Math.log10(volume);\n          for (let i = 0; i < float32Data.length; i++) {\n            float32Data[i]! *= volumeFactor;\n          }\n\n          const outputData = new Int16Array(float32Data.length);\n          for (let i = 0; i < float32Data.length; i++) {\n            const clipped = Math.max(-32768, Math.min(32767, float32Data[i]!));\n            outputData[i] = Math.round(clipped);\n          }\n\n          processedFrame = new AudioFrame(\n            outputData,\n            frame.sampleRate,\n            frame.channels,\n            frame.samplesPerChannel,\n          );\n        } else {\n          processedFrame = frame;\n        }\n\n        // TODO (Brian): use AudioMixer to add/remove frame streams\n        await this.audioSource.captureFrame(processedFrame);\n      }\n    } finally {\n      // TODO: the waitForPlayout() may be innaccurate by 400ms\n      playHandle._markPlayoutDone();\n    }\n  }\n}\n"],"mappings":"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","names":["BuiltinAudioClip"]}

package/dist/voice/index.cjs

@@ -28,6 +28,7 @@ module.exports = __toCommonJS(voice_exports);
 var import_agent = require("./agent.cjs");
 var import_agent_session = require("./agent_session.cjs");
 __reExport(voice_exports, require("./avatar/index.cjs"), module.exports);
+__reExport(voice_exports, require("./background_audio.cjs"), module.exports);
 __reExport(voice_exports, require("./events.cjs"), module.exports);
 __reExport(voice_exports, require("./room_io/index.cjs"), module.exports);
 var import_run_context = require("./run_context.cjs");
@@ -38,6 +39,7 @@ var import_run_context = require("./run_context.cjs");
   RunContext,
   StopResponse,
   ...require("./avatar/index.cjs"),
+  ...require("./background_audio.cjs"),
   ...require("./events.cjs"),
   ...require("./room_io/index.cjs")
 });

package/dist/voice/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\n\nexport * from './avatar/index.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,mBAA2E;AAC3E,2BAAuD;AAEvD,0BAAc,8BANd;AAOA,0BAAc,wBAPd;AAQA,0BAAc,+BARd;AASA,yBAA2B;","names":[]}
+{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,mBAA2E;AAC3E,2BAAuD;AACvD,0BAAc,8BALd;AAMA,0BAAc,kCANd;AAOA,0BAAc,wBAPd;AAQA,0BAAc,+BARd;AASA,yBAA2B;","names":[]}

package/dist/voice/index.d.cts

@@ -1,6 +1,7 @@
 export { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';
 export { AgentSession, type AgentSessionOptions } from './agent_session.js';
 export * from './avatar/index.js';
+export * from './background_audio.js';
 export * from './events.js';
 export * from './room_io/index.js';
 export { RunContext } from './run_context.js';

package/dist/voice/index.d.ts

@@ -1,6 +1,7 @@
 export { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';
 export { AgentSession, type AgentSessionOptions } from './agent_session.js';
 export * from './avatar/index.js';
+export * from './background_audio.js';
 export * from './events.js';
 export * from './room_io/index.js';
 export { RunContext } from './run_context.js';

package/dist/voice/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/voice/index.js

@@ -1,6 +1,7 @@
 import { Agent, StopResponse } from "./agent.js";
 import { AgentSession } from "./agent_session.js";
 export * from "./avatar/index.js";
+export * from "./background_audio.js";
 export * from "./events.js";
 export * from "./room_io/index.js";
 import { RunContext } from "./run_context.js";

package/dist/voice/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\n\nexport * from './avatar/index.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":"AAGA,SAAS,OAAO,oBAA2D;AAC3E,SAAS,oBAA8C;AAEvD,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;","names":[]}
+{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":"AAGA,SAAS,OAAO,oBAA2D;AAC3E,SAAS,oBAA8C;AACvD,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livekit/agents",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "LiveKit Agents - Node.js",
   "main": "dist/index.js",
   "require": "dist/index.cjs",
@@ -11,8 +11,8 @@
       "default": "./dist/index.js"
     },
     "require": {
-      "types": "./index.d.cts",
-      "default": "./index.cjs"
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
     }
   },
   "author": "LiveKit",
@@ -22,14 +22,18 @@
   "files": [
     "dist",
     "src",
+    "resources",
     "README.md"
   ],
   "devDependencies": {
-    "@livekit/rtc-node": "^0.13.12",
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "@livekit/rtc-node": "^0.13.13",
     "@microsoft/api-extractor": "^7.35.0",
+    "@types/fluent-ffmpeg": "^2.1.28",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^22.5.5",
     "@types/ws": "^8.5.10",
+    "fluent-ffmpeg": "^2.1.3",
     "tsup": "^8.4.0",
     "typescript": "^5.0.0"
   },
@@ -41,8 +45,8 @@
     "commander": "^12.0.0",
     "heap-js": "^2.6.0",
     "json-schema": "^0.4.0",
-    "openai": "^4.91.1",
     "livekit-server-sdk": "^2.13.3",
+    "openai": "^4.91.1",
     "pidusage": "^4.0.1",
     "pino": "^8.19.0",
     "pino-pretty": "^11.0.0",

package/resources/NOTICE

@@ -0,0 +1,2 @@
+keyboard-typing.ogg by Anton -- https://freesound.org/s/137/ -- License: Attribution 4.0
+keyboard-typing2.opg by Anton -- https://freesound.org/s/137/ -- License: Attribution 4.0

package/src/audio.ts

@@ -1,10 +1,27 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import ffmpegInstaller from '@ffmpeg-installer/ffmpeg';
 import { AudioFrame } from '@livekit/rtc-node';
+import ffmpeg from 'fluent-ffmpeg';
+import type { ReadableStream } from 'node:stream/web';
 import { log } from './log.js';
+import { createStreamChannel } from './stream/stream_channel.js';
 import type { AudioBuffer } from './utils.js';
 
+ffmpeg.setFfmpegPath(ffmpegInstaller.path);
+
+export interface AudioDecodeOptions {
+  sampleRate?: number;
+  numChannels?: number;
+  /**
+   * Audio format hint (e.g., 'mp3', 'ogg', 'wav', 'opus')
+   * If not provided, FFmpeg will auto-detect
+   */
+  format?: string;
+  abortSignal?: AbortSignal;
+}
+
 export function calculateAudioDurationSeconds(frame: AudioBuffer) {
   // TODO(AJS-102): use frame.durationMs once available in rtc-node
   return Array.isArray(frame)
@@ -72,3 +89,117 @@ export class AudioByteStream {
     return frames;
   }
 }
+
+/**
+ * Decode an audio file into AudioFrame instances
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects
+ *
+ * @example
+ * ```typescript
+ * for await (const frame of audioFramesFromFile('audio.ogg', { sampleRate: 48000 })) {
+ *   console.log('Frame:', frame.samplesPerChannel, 'samples');
+ * }
+ * ```
+ */
+export function audioFramesFromFile(
+  filePath: string,
+  options: AudioDecodeOptions = {},
+): ReadableStream<AudioFrame> {
+  const sampleRate = options.sampleRate ?? 48000;
+  const numChannels = options.numChannels ?? 1;
+
+  const audioStream = new AudioByteStream(sampleRate, numChannels);
+  const channel = createStreamChannel<AudioFrame>();
+  const logger = log();
+
+  // TODO (Brian): decode WAV using a custom decoder instead of FFmpeg
+  const command = ffmpeg(filePath)
+    .inputOptions([
+      '-probesize',
+      '32',
+      '-analyzeduration',
+      '0',
+      '-fflags',
+      '+nobuffer+flush_packets',
+      '-flags',
+      'low_delay',
+    ])
+    .format('s16le') // signed 16-bit little-endian PCM to be consistent cross-platform
+    .audioChannels(numChannels)
+    .audioFrequency(sampleRate);
+
+  let commandRunning = true;
+
+  const onClose = () => {
+    logger.debug('Audio file playback aborted');
+
+    channel.close();
+    if (commandRunning) {
+      commandRunning = false;
+      command.kill('SIGKILL');
+    }
+  };
+
+  const outputStream = command.pipe();
+  options.abortSignal?.addEventListener('abort', onClose, { once: true });
+
+  outputStream.on('data', (chunk: Buffer) => {
+    const arrayBuffer = chunk.buffer.slice(
+      chunk.byteOffset,
+      chunk.byteOffset + chunk.byteLength,
+    ) as ArrayBuffer;
+
+    const frames = audioStream.write(arrayBuffer);
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+  });
+
+  outputStream.on('end', () => {
+    const frames = audioStream.flush();
+    for (const frame of frames) {
+      channel.write(frame);
+    }
+    commandRunning = false;
+    channel.close();
+  });
+
+  outputStream.on('error', (err: Error) => {
+    logger.error(err);
+    commandRunning = false;
+    onClose();
+  });
+
+  return channel.stream();
+}
+
+/**
+ * Loop audio frames from a file indefinitely
+ *
+ * @param filePath - Path to the audio file
+ * @param options - Decoding options
+ * @returns AsyncGenerator that yields AudioFrame objects in an infinite loop
+ */
+export async function* loopAudioFramesFromFile(
+  filePath: string,
+  options: AudioDecodeOptions = {},
+): AsyncGenerator<AudioFrame, void, unknown> {
+  const frames: AudioFrame[] = [];
+  const logger = log();
+
+  for await (const frame of audioFramesFromFile(filePath, options)) {
+    frames.push(frame);
+    yield frame;
+  }
+
+  while (!options.abortSignal?.aborted) {
+    for (const frame of frames) {
+      yield frame;
+    }
+  }
+
+  logger.debug('Audio file playback loop finished');
+}

package/src/metrics/index.ts

@@ -4,6 +4,7 @@
 
 export type {
   AgentMetrics,
+  EOUMetrics,
   LLMMetrics,
   RealtimeModelMetrics,
   STTMetrics,

package/src/stream/stream_channel.test.ts

@@ -126,4 +126,41 @@ describe('StreamChannel', () => {
     const nextResult = await reader.read();
     expect(nextResult.done).toBe(true);
   });
+
+  it('should gracefully handle close while read is pending', async () => {
+    const channel = createStreamChannel<string>();
+    const reader = channel.stream().getReader();
+
+    const readPromise = reader.read();
+
+    await channel.close();
+
+    const result = await readPromise;
+    expect(result.done).toBe(true);
+    expect(result.value).toBeUndefined();
+  });
+
+  it('should complete all pending reads when closed', async () => {
+    const channel = createStreamChannel<number>();
+    const reader = channel.stream().getReader();
+
+    const read1 = reader.read();
+    const read2 = reader.read();
+    const read3 = reader.read();
+
+    await channel.write(42);
+    await channel.write(43);
+    await channel.close();
+
+    const result1 = await read1;
+    expect(result1.done).toBe(false);
+    expect(result1.value).toBe(42);
+
+    const result2 = await read2;
+    expect(result2.done).toBe(false);
+    expect(result2.value).toBe(43);
+
+    const result3 = await read3;
+    expect(result3.done).toBe(true);
+  });
 });