@craftedxp/voice-js 0.10.0 → 0.12.0

package/README.md

@@ -12,14 +12,14 @@ Companion to [`@craftedxp/voice-rn`](https://www.npmjs.com/package/@craftedxp/vo
 npm install @craftedxp/voice-js
 # Node consumers also need:
 npm install ws
-# Multi-party rooms only (joinRoom) also need:
+# Multi-party rooms (joinRoom) and 1:1 calls on the LiveKit media edge also need:
 npm install livekit-client
 ```
 
 `ws` and `livekit-client` are both declared as OPTIONAL peers:
 
 - `ws` — only needed in Node / Electron-main. Browsers use the native `WebSocket` and skip it.
-- `livekit-client` — only needed if you import from `@craftedxp/voice-js/room`. Since 0.7.0 it is no longer a direct dependency, so assistant / transcribe consumers never download it (the embed widget dropped from ~854 KB to ~100 KB). `joinRoom` lazy-`import()`s it and throws an actionable error if it's missing.
+- `livekit-client` — needed for `@craftedxp/voice-js/room` (multi-party rooms) **or** for 1:1 calls when the server's media edge is LiveKit (`transport: 'livekit'`). `joinRoom` and the LiveKit transport both lazy-`import()` it; `joinRoom` throws an actionable error if it's missing, the 1:1 path falls back to WebSocket audio.
 
 ## Entry points (since 0.7.0)
 
@@ -168,22 +168,23 @@ Returns a `VoiceClientFactory` with one method:
 
 ### `factory.startCall(options)`
 
-| Field              | Type                                           | Notes                                                                                                                                                         |
-| ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agentId`          | `string`                                       | Required.                                                                                                                                                     |
-| `userId`           | `string?`                                      | Round-tripped to fetchToken as `userId`; server uses it for contact memory.                                                                                   |
-| `context`          | `Record<string, unknown>?`                     | Per-call structured context. Merged on top of `defaultContext`. Lowered into the agent's system prompt server-side.                                           |
-| `metadata`         | `Record<string, string>?`                      | Per-call key/value. Merged on top of `defaultMetadata`. Round-tripped on `call.ended` webhook. NOT lowered into the prompt.                                   |
-| `bargeIn`          | `boolean?`                                     | Default `true`. Set `false` for alarm-style flows where the user shouldn't accidentally interrupt the script.                                                 |
-| `clientTools`      | `ClientToolMap?`                               | Per-call client tools the agent's LLM can invoke. See [Client tools](#client-tools) section below. Validated synchronously at `startCall` — bad input throws. |
-| `token`            | `string?`                                      | **Test-only escape hatch** — pre-minted `ct_`, bypasses `fetchToken`. Don't use in production.                                                                |
-| `onStateChange`    | `(state) => void`                              | Fires on every state machine transition.                                                                                                                      |
-| `onTranscript`     | `(entries) => void`                            | Fires on every transcript update.                                                                                                                             |
-| `onInterrupt`      | `() => void`                                   | Server signaled barge-in. Browser bundle auto-flushes built-in playback before this fires. Node consumers should drain their custom playback queue here.      |
-| `onAgentTurnStart` | `() => void`                                   | New agent turn began. Use when you want a precise turn-start anchor without diffing `onStateChange`.                                                          |
-| `onVolume`         | `({ input, output }) => void`                  | 0-1 RMS. ~10 Hz cadence. Browser bundle only.                                                                                                                 |
-| `onError`          | `(err) => void`                                | Stable `code` from `CallErrorCode`; matches `voice-rn` codes where overlap.                                                                                   |
-| `onEnd`            | `({ reason, errorCode?, durationMs }) => void` | Fires once when the call ends.                                                                                                                                |
+| Field               | Type                                           | Notes                                                                                                                                                                                                                                                                                                                                    |
+| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agentId`           | `string`                                       | Required.                                                                                                                                                                                                                                                                                                                                |
+| `userId`            | `string?`                                      | Round-tripped to fetchToken as `userId`; server uses it for contact memory.                                                                                                                                                                                                                                                              |
+| `context`           | `Record<string, unknown>?`                     | Per-call structured context. Merged on top of `defaultContext`. Lowered into the agent's system prompt server-side.                                                                                                                                                                                                                      |
+| `metadata`          | `Record<string, string>?`                      | Per-call key/value. Merged on top of `defaultMetadata`. Round-tripped on `call.ended` webhook. NOT lowered into the prompt.                                                                                                                                                                                                              |
+| `bargeIn`           | `boolean?`                                     | Default `true`. Set `false` for alarm-style flows where the user shouldn't accidentally interrupt the script.                                                                                                                                                                                                                            |
+| `clientTools`       | `ClientToolMap?`                               | Per-call client tools the agent's LLM can invoke. See [Client tools](#client-tools) section below. Validated synchronously at `startCall` — bad input throws.                                                                                                                                                                            |
+| `token`             | `string?`                                      | **Test-only escape hatch** — pre-minted `ct_`, bypasses `fetchToken`. Don't use in production.                                                                                                                                                                                                                                           |
+| `onStateChange`     | `(state) => void`                              | Fires on every state machine transition.                                                                                                                                                                                                                                                                                                 |
+| `onTranscript`      | `(entries) => void`                            | Fires on every transcript update.                                                                                                                                                                                                                                                                                                        |
+| `onInterrupt`       | `() => void`                                   | Server signaled barge-in. Browser bundle auto-flushes built-in playback before this fires. Node consumers should drain their custom playback queue here.                                                                                                                                                                                 |
+| `onAgentTurnStart`  | `() => void`                                   | New agent turn began. Use when you want a precise turn-start anchor without diffing `onStateChange`.                                                                                                                                                                                                                                     |
+| `onVolume`          | `({ input, output }) => void`                  | 0-1 RMS. ~10 Hz cadence. Browser bundle only.                                                                                                                                                                                                                                                                                            |
+| `onError`           | `(err) => void`                                | Stable `code` from `CallErrorCode`; matches `voice-rn` codes where overlap.                                                                                                                                                                                                                                                              |
+| `onEnd`             | `({ reason, errorCode?, durationMs }) => void` | Fires once when the call ends.                                                                                                                                                                                                                                                                                                           |
+| `onTransportChange` | `({ requested, actual, reason? }) => void`     | Fires when the transport actually used for the call differs from the one requested by the mint response — e.g. `requested: 'livekit'`, `actual: 'ws'` when `livekit-client` isn't installed, the room join fails, or the server sends `livekit_fallback`. `reason` is free text; match on `actual !== requested` rather than parsing it. |
 
 Resolves to a `Call` handle:
 
@@ -422,7 +423,8 @@ Renders a floating call button with a Shadow-DOM transcript panel. Pre-mint the
 
 ## Status
 
-- **0.10.0** (current) — `sendImage(data, mimeType)` on `NodeCall`: image input for `channel:'multimodal'` sessions (`user_image` frame). `data` can be a base64 string or buffer; `mimeType` must be one of `image/png`, `image/jpeg`, `image/webp`, `image/gif`. Returns `false` (and sends nothing) if the WS isn't open, data is empty, mimeType is unsupported, or base64-encoded size exceeds 5 MB; never throws. Also updates `sendText` doc to note it works on both `channel:'text'` and `channel:'multimodal'` sessions. Additive — drop-in for 0.9.0 consumers.
+- **0.12.0** (current) — `livekit` transport (phase 35). When the mint response says `transport: 'livekit'`, the browser SDK opens the same call WebSocket with `?media=livekit`, joins the LiveKit room announced by the server's `livekit_join` frame via the optional peer `livekit-client`, publishes the mic and plays the agent's track; every control frame (transcripts, client tools, `interrupt`, …) stays on the WS. **Fallback is automatic:** if `livekit-client` isn't installed, the room join fails, or the server sends `livekit_fallback`, the call continues with WS audio on the same connection and the new `onTransportChange({ requested, actual, reason? })` callback fires (`reason` is free text, match on `actual !== requested`). Node entry, `NodeCall`, and `parseIncomingCall` treat `livekit` as `ws` unless noted. Additive — drop-in for 0.11.0 consumers.
+- 0.10.0 — `sendImage(data, mimeType)` on `NodeCall`: image input for `channel:'multimodal'` sessions (`user_image` frame). `data` can be a base64 string or buffer; `mimeType` must be one of `image/png`, `image/jpeg`, `image/webp`, `image/gif`. Returns `false` (and sends nothing) if the WS isn't open, data is empty, mimeType is unsupported, or base64-encoded size exceeds 5 MB; never throws. Also updates `sendText` doc to note it works on both `channel:'text'` and `channel:'multimodal'` sessions. Additive — drop-in for 0.9.0 consumers.
 - 0.9.0 — `sendText(text)` on `NodeCall`: typed user turns for `channel:'text'` WS sessions (`user_text` frame). Server accepts `user_text` only on text-channel sessions and rejects it on voice-channel sessions (anti-injection). Text is trimmed; returns `false` (and sends nothing) if the WS isn't open or text is empty/whitespace, never throws. Additive — drop-in for 0.8.0 consumers.
 - 0.8.0 — `sendClientEvent(text)` on `NodeCall`: advisory context lines for live calls (`client_event` frame). Server buffers these and prepends them to the next turn's context; never triggers a response by itself. Text is trimmed and truncated to 400 chars; returns `false` if the WS isn't open yet or text is empty. Additive — drop-in for 0.7.0 consumers.
 - 0.7.0 — Per-type entry points + LiveKit goes optional. New subpaths `@craftedxp/voice-js/assistant`, `/room`, `/transcribe` (plus the existing `/node`); import the one matching your [agent `type`](https://www.npmjs.com/package/@craftedxp/sdk-node). `livekit-client` moved from `dependencies` to an **optional peerDependency** — assistant / transcribe consumers no longer download it, and the embed widget dropped from ~854 KB to ~100 KB. `joinRoom` lazy-`import()`s LiveKit and throws an actionable error if it isn't installed, so the deprecated barrel keeps working for non-room consumers. **Breaking for room consumers:** add `npm install livekit-client`. Non-room consumers are drop-in (prefer migrating barrel imports to `/assistant`).

package/dist/assistant.d.mts

@@ -1,6 +1,6 @@
-import { V as VoiceClientConfig, a as VoiceClientFactory } from './config-D2TbvIqT.mjs';
-export { C as Call, b as CallEndEvent, c as CallEndReason, d as CallError, e as CallErrorCode, f as CallState, g as ChatEvent, h as ClientTool, i as ClientToolMap, F as FetchToken, j as FetchTokenArgs, k as FetchTokenResult, P as ProtocolCallbacks, l as ProtocolState, S as ServerMessage, m as StartCallOptions, n as StartTextSessionOpts, T as TextSession, o as TranscriptEntry, p as VolumeEvent, q as buildWsUrl, r as createProtocolState, s as handleServerMessage, t as startTextSession } from './config-D2TbvIqT.mjs';
-export { C as CaptureController, a as CaptureOptions, I as IncomingCallPayload, O as OnAgentSpeakingChange, b as OnChunk, c as OnError, d as OnVolume, P as PlaybackController, e as PlaybackOptions, R as RWSEvent, f as RWSOptions, g as ReconnectingWebSocket, W as WebSocketFactory, h as WebSocketLike, i as createAudioCapture, j as createAudioPlayback, k as createReconnectingWebSocket, p as parseIncomingCall } from './incomingCall-CfRRzj2P.mjs';
+import { V as VoiceClientConfig, a as VoiceClientFactory } from './config-DfbPB1Tq.mjs';
+export { C as Call, b as CallEndEvent, c as CallEndReason, d as CallError, e as CallErrorCode, f as CallState, g as CallTransport, h as ChatEvent, i as ClientTool, j as ClientToolMap, F as FetchToken, k as FetchTokenArgs, l as FetchTokenResult, P as ProtocolCallbacks, m as ProtocolState, S as ServerMessage, n as StartCallOptions, o as StartTextSessionOpts, T as TextSession, p as TranscriptEntry, q as TransportChangeEvent, r as VolumeEvent, s as buildWsUrl, t as createProtocolState, u as handleServerMessage, v as startTextSession } from './config-DfbPB1Tq.mjs';
+export { C as CaptureController, a as CaptureOptions, I as IncomingCallPayload, O as OnAgentSpeakingChange, b as OnChunk, c as OnError, d as OnVolume, P as PlaybackController, e as PlaybackOptions, R as RWSEvent, f as RWSOptions, g as ReconnectingWebSocket, W as WebSocketFactory, h as WebSocketLike, i as createAudioCapture, j as createAudioPlayback, k as createReconnectingWebSocket, p as parseIncomingCall } from './incomingCall-2B3XB8pM.mjs';
 
 /**
  * One-time SDK setup. Returns a factory you call `startCall` on for

package/dist/assistant.d.ts

@@ -1,6 +1,6 @@
-import { V as VoiceClientConfig, a as VoiceClientFactory } from './config-D2TbvIqT.js';
-export { C as Call, b as CallEndEvent, c as CallEndReason, d as CallError, e as CallErrorCode, f as CallState, g as ChatEvent, h as ClientTool, i as ClientToolMap, F as FetchToken, j as FetchTokenArgs, k as FetchTokenResult, P as ProtocolCallbacks, l as ProtocolState, S as ServerMessage, m as StartCallOptions, n as StartTextSessionOpts, T as TextSession, o as TranscriptEntry, p as VolumeEvent, q as buildWsUrl, r as createProtocolState, s as handleServerMessage, t as startTextSession } from './config-D2TbvIqT.js';
-export { C as CaptureController, a as CaptureOptions, I as IncomingCallPayload, O as OnAgentSpeakingChange, b as OnChunk, c as OnError, d as OnVolume, P as PlaybackController, e as PlaybackOptions, R as RWSEvent, f as RWSOptions, g as ReconnectingWebSocket, W as WebSocketFactory, h as WebSocketLike, i as createAudioCapture, j as createAudioPlayback, k as createReconnectingWebSocket, p as parseIncomingCall } from './incomingCall-CfRRzj2P.js';
+import { V as VoiceClientConfig, a as VoiceClientFactory } from './config-DfbPB1Tq.js';
+export { C as Call, b as CallEndEvent, c as CallEndReason, d as CallError, e as CallErrorCode, f as CallState, g as CallTransport, h as ChatEvent, i as ClientTool, j as ClientToolMap, F as FetchToken, k as FetchTokenArgs, l as FetchTokenResult, P as ProtocolCallbacks, m as ProtocolState, S as ServerMessage, n as StartCallOptions, o as StartTextSessionOpts, T as TextSession, p as TranscriptEntry, q as TransportChangeEvent, r as VolumeEvent, s as buildWsUrl, t as createProtocolState, u as handleServerMessage, v as startTextSession } from './config-DfbPB1Tq.js';
+export { C as CaptureController, a as CaptureOptions, I as IncomingCallPayload, O as OnAgentSpeakingChange, b as OnChunk, c as OnError, d as OnVolume, P as PlaybackController, e as PlaybackOptions, R as RWSEvent, f as RWSOptions, g as ReconnectingWebSocket, W as WebSocketFactory, h as WebSocketLike, i as createAudioCapture, j as createAudioPlayback, k as createReconnectingWebSocket, p as parseIncomingCall } from './incomingCall-CYmeQkIw.js';
 
 /**
  * One-time SDK setup. Returns a factory you call `startCall` on for

package/dist/assistant.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/assistant.ts
@@ -512,7 +522,8 @@ function buildWsUrl(args) {
   const base = new URL(args.apiBase);
   const proto = base.protocol === "https:" ? "wss:" : "ws:";
   const bargeQS = args.bargeIn === false ? "&barge=off" : "";
-  return `${proto}//${base.host}/v1/agents/${encodeURIComponent(args.agentId)}/call?token=${encodeURIComponent(args.token)}${bargeQS}`;
+  const mediaQS = args.media === "livekit" ? "&media=livekit" : "";
+  return `${proto}//${base.host}/v1/agents/${encodeURIComponent(args.agentId)}/call?token=${encodeURIComponent(args.token)}${bargeQS}${mediaQS}`;
 }
 
 // src/clientTools.ts
@@ -666,7 +677,75 @@ var createClientMarksBuffer = (args) => {
   };
 };
 
+// src/livekit/createLiveKitMedia.ts
+var toError = (e) => e instanceof Error ? e : new Error(String(e));
+function createLiveKitMedia(lk, opts = {}) {
+  let room = null;
+  let audioEl = null;
+  let muted = false;
+  const attach = (track) => {
+    if (track.kind !== lk.Track.Kind.Audio) return;
+    if (typeof document === "undefined") return;
+    if (!audioEl) {
+      audioEl = document.createElement("audio");
+      audioEl.autoplay = true;
+      audioEl.style.display = "none";
+      document.body.appendChild(audioEl);
+    }
+    track.attach(audioEl);
+  };
+  return {
+    connect: async (url, token) => {
+      const r = new lk.Room({ adaptiveStream: false, dynacast: false });
+      room = r;
+      r.on(lk.RoomEvent.TrackSubscribed, (track) => attach(track));
+      await r.connect(url, token);
+      if (room !== r) {
+        return;
+      }
+      await r.localParticipant.setMicrophoneEnabled(!muted);
+      if (room !== r) {
+        return;
+      }
+      try {
+        await r.startAudio();
+      } catch {
+      }
+    },
+    disconnect: () => {
+      const r = room;
+      room = null;
+      if (r) void r.disconnect().catch(() => void 0);
+      audioEl?.remove();
+      audioEl = null;
+    },
+    setMuted: (m) => {
+      muted = m;
+      const r = room;
+      if (!r) return;
+      void r.localParticipant.setMicrophoneEnabled(!m).catch((e) => opts.onError?.(toError(e)));
+    }
+  };
+}
+
 // src/VoiceClient.ts
+var parseMediaFrame = (raw) => {
+  if (!raw.includes('"livekit_')) return null;
+  try {
+    const m = JSON.parse(raw);
+    if (m.type === "livekit_join" && typeof m.url === "string" && typeof m.token === "string") {
+      return { type: "livekit_join", url: m.url, token: m.token };
+    }
+    if (m.type === "livekit_fallback") {
+      return {
+        type: "livekit_fallback",
+        reason: typeof m.reason === "string" ? m.reason : void 0
+      };
+    }
+  } catch {
+  }
+  return null;
+};
 var BrowserVoiceClient = class {
   constructor(args) {
     this.rws = null;
@@ -678,6 +757,9 @@ var BrowserVoiceClient = class {
     this.startedAt = null;
     this.endedFired = false;
     this.lastError = null;
+    this.mediaMode = "ws";
+    this.lkMedia = null;
+    this.lkJoinSeen = false;
     this.end = () => {
       this.teardown("user_hangup");
     };
@@ -685,11 +767,73 @@ var BrowserVoiceClient = class {
       if (this.muted) return;
       this.muted = true;
       this.capture?.mute(true);
+      this.lkMedia?.setMuted(true);
     };
     this.unmute = () => {
       if (!this.muted) return;
       this.muted = false;
       this.capture?.mute(false);
+      this.lkMedia?.setMuted(false);
+    };
+    this.ensureWsPlayback = async () => {
+      if (this.playback) return;
+      const createPlayback = this.args.audio?.createPlayback ?? createAudioPlayback;
+      this.playback = createPlayback({
+        onVolume: (v) => {
+          this.outputVolume = v;
+          this.args.options.onVolume?.({ input: this.inputVolume, output: v });
+        }
+      });
+      try {
+        await this.playback.resume();
+      } catch {
+      }
+    };
+    // ---------------------------------------------------------------
+    // LiveKit media lifecycle (phase 35)
+    // ---------------------------------------------------------------
+    this.joinLiveKit = async (url, token) => {
+      this.lkJoinSeen = true;
+      const lk = this.args.media?.lk;
+      if (!lk) {
+        this.fallbackToWs("livekit-client unavailable");
+        return;
+      }
+      const media = createLiveKitMedia(lk, {
+        onError: (e) => this.emitError({ code: "mic_start_failed", message: e.message })
+      });
+      this.lkMedia = media;
+      if (this.muted) media.setMuted(true);
+      try {
+        await media.connect(url, token);
+        if (this.lkMedia !== media) return;
+        this.mediaMode = "livekit";
+        this.rws?.send(JSON.stringify({ type: "livekit_ready" }));
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        media.disconnect();
+        if (this.lkMedia === media) this.lkMedia = null;
+        this.rws?.send(JSON.stringify({ type: "livekit_failed", reason }));
+        this.fallbackToWs(reason);
+      }
+    };
+    // Idempotent: whichever side gives up first (client join error, server
+    // livekit_fallback, `connected` without a join) lands here once.
+    this.fallbackToWs = (reason) => {
+      if (this.mediaMode === "ws") return;
+      this.mediaMode = "ws";
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
+      void this.ensureWsPlayback();
+      void this.startCapture();
+      this.args.options.onTransportChange?.({ requested: "livekit", actual: "ws", reason });
+    };
+    this.resetLiveKitForReconnect = () => {
+      if (this.args.media?.kind !== "livekit") return;
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
+      this.lkJoinSeen = false;
+      this.mediaMode = "livekit-pending";
     };
     // ---------------------------------------------------------------
     // Internal
@@ -710,17 +854,27 @@ var BrowserVoiceClient = class {
     this.handleSocketEvent = (ev) => {
       switch (ev.type) {
         case "open":
-          void this.startCapture();
+          if (this.mediaMode === "ws") void this.startCapture();
           break;
         case "reconnected":
           this.proto.transcript = [];
           this.proto.agentBubbleId = null;
           this.args.options.onTranscript?.(this.proto.transcript);
-          void this.startCapture();
+          this.resetLiveKitForReconnect();
+          if (this.mediaMode === "ws") void this.startCapture();
           this.setState("listening");
           break;
         case "message":
           if (typeof ev.data === "string") {
+            const media = parseMediaFrame(ev.data);
+            if (media?.type === "livekit_join") {
+              if (this.mediaMode === "livekit-pending") void this.joinLiveKit(media.url, media.token);
+              break;
+            }
+            if (media?.type === "livekit_fallback") {
+              this.fallbackToWs(media.reason ?? "server_fallback");
+              break;
+            }
             handleServerMessage(ev.data, this.proto, {
               onState: this.setState,
               onTranscript: (entries) => this.args.options.onTranscript?.(entries),
@@ -737,7 +891,12 @@ var BrowserVoiceClient = class {
                 if (typeof seq === "number") this.marks.onAgentTurnEnd(seq);
               },
               onCallEnd: (reason) => this.teardown(reason),
-              onConnected: () => this.sendClientToolsRegister(),
+              onConnected: () => {
+                if (this.mediaMode === "livekit-pending" && !this.lkJoinSeen) {
+                  this.fallbackToWs("server_declined");
+                }
+                this.sendClientToolsRegister();
+              },
               onClientToolCall: (frame) => dispatchClientToolCall(
                 (f) => this.rws?.send(JSON.stringify(f)),
                 this.args.options.clientTools ?? {},
@@ -745,6 +904,8 @@ var BrowserVoiceClient = class {
               )
             });
           } else {
+            if (this.mediaMode === "livekit") break;
+            if (!this.playback) void this.ensureWsPlayback();
             this.marks.markFirstAudibleOutput();
             this.playback?.enqueue(ev.data);
           }
@@ -762,7 +923,8 @@ var BrowserVoiceClient = class {
     };
     this.startCapture = async () => {
       if (this.capture?.isCapturing()) return;
-      this.capture = createAudioCapture({
+      const createCapture = this.args.audio?.createCapture ?? createAudioCapture;
+      this.capture = createCapture({
         onChunk: (pcm) => {
           this.marks.markFirstOutboundAudio();
           this.rws?.send(pcm);
@@ -791,6 +953,8 @@ var BrowserVoiceClient = class {
       }
       this.capture?.stop();
       this.capture = null;
+      this.lkMedia?.disconnect();
+      this.lkMedia = null;
       this.playback?.close();
       this.playback = null;
       try {
@@ -843,28 +1007,17 @@ var BrowserVoiceClient = class {
   async start() {
     this.setState("connecting");
     this.startedAt = Date.now();
+    this.mediaMode = this.args.media?.kind === "livekit" ? "livekit-pending" : "ws";
     const url = buildWsUrl({
       apiBase: this.args.config.apiBase,
       agentId: this.args.options.agentId,
       token: this.args.token,
-      bargeIn: this.args.options.bargeIn
-    });
-    this.playback = createAudioPlayback({
-      onVolume: (v) => {
-        this.outputVolume = v;
-        this.args.options.onVolume?.({ input: this.inputVolume, output: v });
-      }
+      bargeIn: this.args.options.bargeIn,
+      media: this.mediaMode === "ws" ? void 0 : "livekit"
     });
-    try {
-      await this.playback.resume();
-    } catch {
-    }
+    if (this.mediaMode === "ws") await this.ensureWsPlayback();
     this.rws = createReconnectingWebSocket(
-      {
-        url,
-        wsFactory: this.args.wsFactory,
-        maxRetries: 3
-      },
+      { url, wsFactory: this.args.wsFactory, maxRetries: 3 },
       (ev) => this.handleSocketEvent(ev)
     );
   }
@@ -1049,6 +1202,20 @@ async function createWebRtcCall(opts) {
   };
 }
 
+// src/livekit/loadLiveKit.ts
+var lkPromise;
+var loadLiveKit = (requiredBy = "this feature") => {
+  lkPromise ?? (lkPromise = import("livekit-client").catch((e) => {
+    lkPromise = void 0;
+    const wrapped = new Error(
+      `${requiredBy} requires the optional peer dependency 'livekit-client' \u2014 npm install livekit-client`
+    );
+    wrapped.cause = e;
+    throw wrapped;
+  }));
+  return lkPromise;
+};
+
 // src/textSession.ts
 async function startTextSession(opts) {
   const f = opts.fetch ?? fetch;
@@ -1145,7 +1312,7 @@ var parseIncomingCall = (raw) => {
   if (typeof p.agentId !== "string" || p.agentId.length === 0) {
     throw new Error("parseIncomingCall: missing `agentId`");
   }
-  const transport = p.transport === "webrtc" ? "webrtc" : "ws";
+  const transport = p.transport === "webrtc" ? "webrtc" : p.transport === "livekit" ? "livekit" : "ws";
   const out = { token: p.token, agentId: p.agentId, transport };
   if (transport === "webrtc" && typeof p.webrtcGatewayBase === "string") {
     out.webrtcGatewayBase = p.webrtcGatewayBase;
@@ -1202,6 +1369,27 @@ var AssistantVoiceFactory = class {
           clientTools: options.clientTools
         });
       }
+      if (resolved.transport === "livekit") {
+        let lk = null;
+        let loadError = "";
+        try {
+          lk = await loadLiveKit("transport 'livekit'");
+        } catch (e) {
+          loadError = e instanceof Error ? e.message : String(e);
+        }
+        if (!lk) {
+          options.onTransportChange?.({ requested: "livekit", actual: "ws", reason: loadError });
+        }
+        const client2 = new BrowserVoiceClient({
+          config: this.config,
+          options: { ...options, context, metadata },
+          token: resolved.token,
+          wsFactory: browserWsFactory,
+          media: lk ? { kind: "livekit", lk } : void 0
+        });
+        await client2.start();
+        return client2;
+      }
       const client = new BrowserVoiceClient({
         config: this.config,
         // Carry merged context/metadata through to startCall so server can