realtime-avatar 0.25.0 → 0.26.0

package/README.md

@@ -224,6 +224,7 @@ all), and the `video` policy types are deliberately not one-to-one with the wire
 // calls
 rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, connectionHistory?, transcript?, metadata? })
 rta.endCall(sessionId, { reason? })     // free an abandoned call's slot; idempotent, never throws
+rta.leaveQueue(queueTicketId, { reason? }) // give up a queued call's place in line; idempotent, never throws
 
 // optional recordings; server only, requires recordings:read
 rta.listRecordings({ sessionId, limit?, cursor? })
@@ -294,6 +295,61 @@ call. Policy — `instructions`, `maxSeconds`, `voice`, `video` — is decided i
 your server. A route that spreads the request body into `startCall` hands your caller your
 system prompt and your bill.
 
+### Styling
+
+`AvatarCall` and `AvatarVideoSurface` lay themselves out with inline styles, so they need no
+CSS build and no configuration: no stylesheet to import and no Tailwind `@source` for this
+package. The surface fills its container; give that container a definite size (an aspect
+ratio plus a height, say). `className` on the surface adds your own classes; to change a
+property the surface sets itself, such as its 100% size, pass `style`.
+
+`AvatarCall`'s `children` render in a layer that fills the call's box above the video and
+the live badge, so an absolutely positioned control places itself against the box and stays
+clickable while she is live.
+
+### Microphone and sound
+
+The handle reports the two local failures a "live" call can hide. `call.microphone` says
+whether she can hear the user (`off`, `pending`, `on`, `muted`, `blocked`, `unavailable`; the
+last two carry `reason`, `message` and `hint`), and `onMicrophoneProblem` fires once per new
+problem. A device that stops mid-call reads `pending` while LiveKit retries the default device,
+and `unavailable` (`device-lost`) only once that fails. `call.retryMicrophone()` asks again after
+the user fixes it, and `call.setMicrophoneEnabled(enabled)` mutes and unmutes. While the call is
+waiting or connecting those only record the choice (nothing is captured before the room
+connects), a mute made then is kept when the call goes live, and after `end()` they do nothing.
+
+`call.audio` says whether the user can hear her (`unknown`, `allowed`, `blocked`; `unknown` again
+once the call ended). While it is `blocked`, `AvatarCall` shows a "Tap to turn on sound" button,
+top-centre in a polite live region, that calls `call.startAudio()`. Pass `audioUnlockPrompt` a
+function to render your own (your words, your placement), or `false` for nothing.
+`startAudio()` must run inside a click or tap handler; it never rejects and resolves whether
+playback is allowed afterwards.
+
+Every state is derived from LiveKit's public events, and LiveKit still owns the device: it
+captures on connect and stops when the room leaves. A microphone error from an earlier call on
+the same room is not reported for the next one. A publish that fails after the microphone was
+captured reaches only the room's `onError` and stays `pending`: that callback also carries
+unrelated failures, so it is not guessed into a microphone problem.
+
+### Ending a call
+
+`call.end()` (and `useRealtimeSession().end()`) is terminal from every phase, including
+`waiting` in the queue and `connecting`. It stops the queue retry and the reconnect ladder,
+releases the held session or the queue ticket, leaves the room (which stops the microphone),
+moves `status` to `"ended"` and fires `onEnded({ reason: "user_ended" })` once. Ending a call
+that is already over does nothing. `sayAndEnd(text)` is the graceful path when she should speak
+a last line first.
+
+**After `end()`, nothing starts a call except you, explicitly.** Changing `avatarId`, `mode` or
+`listen` on an ended `AvatarCall` does not redial; remount it, for example with a `key`:
+
+```tsx
+<AvatarCall key={callId} client={client} avatarId={avatarId} />   // new callId → new call
+```
+
+On the lower-level hooks, `reconnect()` redials (a double tap mints once), and so does setting
+`active` to false and back. `reset()` does not undo an end.
+
 ### Optional connection details
 
 `AvatarCall` provides call status, actions and end reasons for your default UI. To show
@@ -390,6 +446,28 @@ room-wide to whatever you render inside it (`playoutDelaySeconds={false}` opts o
 `attachAvatarTools` runs your functions in the page. Nothing is executed on the platform, and
 a tool has **2.5 seconds** to answer before the call gives up on it and tells her it failed.
 
+A failed registration throws `ToolRegistrationError`, whose `retryable` says whether trying again
+can help: the agent not there or not armed by the deadline (a slow start, or a session minted
+without `client_tools`; one attempt cannot tell which), or an RPC transport failure, is retryable;
+an oversized manifest or a request LiveKit or the agent refused is not.
+
+In React, `useCharacterTools(tools)` registers them while the room is connected and returns
+their state: `idle`, `registering` (with `attempt`), `ready` (`registered`, `rejected`) or
+`error`. A retryable failure is retried twice (after 1s, then 3s) while the room stays
+connected; only then is it `error`. It re-registers when the manifest changes (names,
+descriptions, parameters), not when the `tools` object does, so an inline object is fine and
+each call reaches your latest `execute`. With `AvatarCall`, call it from a component you render
+as a child, which runs inside the call's room, and show its state rather than ignore it:
+
+```tsx
+function Tools() {
+  const tools = useCharacterTools(myTools);
+  return tools.status === "error" ? <p role="status">Tools are off for this call: {tools.error}</p> : null;
+}
+
+<AvatarCall client={client} avatarId="ava_…">{() => <Tools />}</AvatarCall>
+```
+
 ## What `/react` exports, and what it deliberately does not
 
 31 names, down from 82 on 2026-08-26. Two groups came out and are not coming back:

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, P as PlayoutDelayTarget, a as applyAvatarPlayoutDelay, b as applyPlayoutDelay } from './playout-delay-DWOc8iCl.js';
+export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, E as EnableMicrophoneOptions, M as MicrophoneCapableRoom, a as MicrophoneFailureReason, b as MicrophoneProblem, c as MicrophoneProblemReason, d as MicrophoneResult, P as PlayoutDelayTarget, e as applyAvatarPlayoutDelay, f as applyPlayoutDelay, g as describeMicrophoneFailure, h as enableMicrophone } from './playout-delay-CtRZdtsj.js';
 
 type VideoSupport = {
     supported: true;
@@ -10,91 +10,6 @@ type VideoSupport = {
 /** Check before starting a billed video session; this does not prove negotiated playback. */
 declare function checkVideoSupport(codec?: string): VideoSupport;
 
-/**
- * Turning the microphone on, and saying what went wrong when it does not.
- *
- * WHY THIS EXISTS. `room.localParticipant.setMicrophoneEnabled(true)` is one line, so every
- * integration writes it inline and none of them handle its rejection — the reject path is
- * invisible until a real user is on a real machine. When it fails there is nothing to see:
- * the call is already connected, the page is mid-`await`, and the rejection becomes an
- * unhandled promise nobody is looking at. The reported symptom is always the same sentence —
- * "the mic won't start" — and it covers at least six unrelated causes with different fixes,
- * one of which is not in the browser at all.
- *
- * So this returns a RESULT rather than throwing: the cause becomes a value the caller has to
- * handle, and each one carries the sentence that names its actual fix. `message` is what the
- * browser said; `hint` is what the person should do.
- *
- * It is deliberately structural — it never imports `livekit-client`, so it pins no version
- * and adds no bytes. Anything with a `localParticipant.setMicrophoneEnabled` satisfies it.
- */
-/** The sliver of livekit-client's `Room` this needs. Structural on purpose — see above. */
-interface MicrophoneCapableRoom {
-    localParticipant: {
-        setMicrophoneEnabled(enabled: boolean): Promise<unknown>;
-    };
-}
-/**
- * Why the microphone did not start. Every variant has a DIFFERENT fix, which is the whole
- * reason this is an enum and not a boolean.
- */
-type MicrophoneFailureReason = 
-/** No `navigator.mediaDevices` — the page is not a secure context. */
-"insecure-origin"
-/** The permission prompt was never answered. getUserMedia may never settle; we time out. */
- | "no-answer"
-/** The BROWSER denied it — the site's own permission, resettable from the address bar. */
- | "denied-by-browser"
-/** The OS denied it — macOS System Settings, nothing the page or the site can change. */
- | "denied-by-os"
-/** No input device is connected, or none matches the constraints. */
- | "no-device"
-/** A device exists but something else holds it — another tab, app, or a stale call. */
- | "device-in-use"
-/** Anything unrecognised. `message` still carries what the browser said. */
- | "unknown";
-type MicrophoneResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: MicrophoneFailureReason;
-    /** What the browser reported, verbatim. Show it — it is often exact. */
-    message: string;
-    /** What the person should actually do about it. */
-    hint: string;
-};
-interface EnableMicrophoneOptions {
-    /**
-     * How long to wait before calling it a no-answer. Default 15s.
-     *
-     * This is not belt-and-braces. Per the getUserMedia specification a prompt the user never
-     * dismisses may leave the promise permanently pending — "neither resolve nor reject" — and
-     * a page that awaits it in its connect path hangs on a state that has no error and no end.
-     * A deadline turns that into a reportable outcome.
-     */
-    timeoutMs?: number;
-}
-/**
- * Publish the caller's microphone, and report WHY if it does not start.
- *
- * ```ts
- * const mic = await enableMicrophone(room);
- * if (!mic.ok) {
- *   status.textContent = `Microphone: ${mic.message}`;
- *   help.textContent = mic.hint;          // the sentence that names the fix
- * }
- * ```
- *
- * Never throws. A call that cannot start the microphone is an ordinary outcome of asking a
- * person for a device, not a programmer error, so it belongs in the return type.
- *
- * Note it does NOT hang up on failure — the call is still live and still billing, and only
- * the caller knows whether a text-only session is useful to them. If it is not, disconnect
- * in the `!ok` branch; leaving a room connected against a device the user never granted is
- * how the retry ends up contending with the call that is still holding it.
- */
-declare function enableMicrophone(room: MicrophoneCapableRoom, options?: EnableMicrophoneOptions): Promise<MicrophoneResult>;
-
 /**
  * Making the character AUDIBLE — the half of "audio works" that has nothing to do with the
  * microphone.
@@ -251,4 +166,4 @@ type BoomerangPlayback = {
  */
 declare function attachBoomerangPlayback(video: HTMLVideoElement, options?: BoomerangPlaybackOptions): BoomerangPlayback;
 
-export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type EnableMicrophoneOptions, type MicrophoneCapableRoom, type MicrophoneFailureReason, type MicrophoneResult, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, type VideoSupport, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };
+export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, type VideoSupport, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, prepareAvatarRoom };

package/dist/browser.js

@@ -18,6 +18,7 @@ var HINTS = {
   "denied-by-os": "The operating system is blocking the browser itself, so no site can record. On macOS: System Settings > Privacy & Security > Microphone, enable your browser, then RESTART it \u2014 the change does not apply to a running browser.",
   "no-device": "No microphone is available. Connect one, and if you are on Bluetooth headphones check they are in a mode that has a microphone.",
   "device-in-use": "Another application or browser tab is holding the microphone. Close it \u2014 including any call from this page you did not hang up \u2014 and try again.",
+  "device-lost": "The microphone stopped during the call: it was unplugged, or access to it was turned off. Reconnect it or allow access again, then turn the microphone back on.",
   unknown: "Try again, and if it persists include the message above in your report."
 };
 function isOperatingSystemDenial(message) {
@@ -54,6 +55,10 @@ function classify(error) {
 function fail(reason, message) {
   return { ok: false, reason, message, hint: HINTS[reason] };
 }
+function describeMicrophoneFailure(error) {
+  const { reason, message } = classify(error);
+  return { reason, message, hint: HINTS[reason] };
+}
 async function enableMicrophone(room, options = {}) {
   const timeoutMs = options.timeoutMs ?? 15e3;
   if (typeof navigator === "undefined" || !navigator.mediaDevices) {
@@ -253,4 +258,4 @@ function now() {
   return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
 
-export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };
+export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, describeMicrophoneFailure, enableMicrophone, prepareAvatarRoom };

package/dist/{chunk-GMYGHDY2.js → chunk-HMESE54B.js}

@@ -654,7 +654,7 @@ z.object({
   queue_position: z.number().int().positive().optional(),
   recommended_retry_ms: z.number().int().nonnegative()
 }).strict();
-z.enum([
+var liveKitSessionReleaseReasonSchema = z.enum([
   "page_hide",
   "disconnected",
   "superseded",
@@ -665,7 +665,7 @@ z.enum([
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.25.0";
+var SDK_VERSION = "0.26.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -777,7 +777,25 @@ var RealtimeAvatar = class {
    */
   async endCall(sessionId, options = {}) {
     if (!sessionId) return false;
-    const body = { session_id: sessionId };
+    return this.#release({ session_id: sessionId }, options);
+  }
+  /**
+   * Give up a QUEUED call's place in line, by the `queueTicketId` that `startCall` returned.
+   *
+   * A queued call has no session yet, so {@link endCall} cannot reach it: the release contract
+   * carries the ticket in its own field, and a ticket sent as a session id names nothing and is
+   * acknowledged as an idempotent no-op. The place is then held until its TTL, at the front of
+   * the queue, in front of everyone behind it.
+   *
+   * Same contract as `endCall`: best-effort, `true` only when the platform acknowledged it,
+   * never a throw, and only for tickets YOUR SERVER was handed.
+   */
+  async leaveQueue(queueTicketId, options = {}) {
+    if (!queueTicketId) return false;
+    return this.#release({ queue_ticket_id: queueTicketId }, options);
+  }
+  async #release(target, options) {
+    const body = { ...target };
     if (options.reason !== void 0) body.reason = options.reason;
     if (options.capacityPool !== void 0) body.capacity_pool = options.capacityPool;
     try {
@@ -1281,4 +1299,4 @@ function isQueued(result) {
   return "queued" in result;
 }
 
-export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript };
+export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, sessionModeSchema, verifyTranscript };

package/dist/{chunk-DNHHQ5GZ.js → chunk-XJPGQMEW.js}

@@ -1,4 +1,5 @@
-import { RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-GMYGHDY2.js';
+import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-HMESE54B.js';
+import { z } from 'zod';
 
 // ../http-client/src/generated/error-semantics.ts
 var ERROR_SEMANTICS = {
@@ -38,6 +39,17 @@ var MESSAGE_SHAPE_PATTERNS = { "machine": { "source": "[_=<>{}\\[\\]|\\\\$`]|\\w
 Object.values(MESSAGE_SHAPE_PATTERNS).map(
   (pattern) => new RegExp(pattern.source, pattern.flags)
 );
+var proxyConnectRequestSchema = z.object({
+  avatarId: z.string().min(1),
+  mode: sessionModeSchema.optional()
+});
+var proxyEndRequestSchema = z.object({
+  session_id: z.string().min(1).optional(),
+  queue_ticket_id: z.string().min(1).optional(),
+  reason: liveKitSessionReleaseReasonSchema.optional().catch(void 0)
+}).strict().refine((body) => body.session_id !== void 0 || body.queue_ticket_id !== void 0, {
+  message: "session_id or queue_ticket_id is required"
+});
 
 // ../proxy/src/config.ts
 var MISCONFIGURED = "internal_error";
@@ -97,19 +109,25 @@ function createProxyHandler(config) {
     try {
       if (operation === "avatars") return json({ data: await rta.listAvatars() });
       if (operation === "credits") return json(await rta.creditBalance());
+      const raw = await request.json().catch(() => void 0);
       if (operation === "end") {
-        const ended = await request.json().catch(() => ({}));
-        const sessionId = ended.session_id ?? ended.queue_ticket_id;
-        if (!sessionId) return json({ error: "session_id or queue_ticket_id is required" }, 422);
-        const owns = config.ownsSession ? await config.ownsSession({ request, sessionId }) : minted.delete(sessionId);
-        if (!owns) return new Response(null, { status: 204 });
+        const parsed2 = proxyEndRequestSchema.safeParse(raw);
+        if (!parsed2.success) return json({ error: "session_id or queue_ticket_id is required" }, 422);
+        const ended = parsed2.data;
         const reason = ended.reason === "page_hide" || ended.reason === "unmount" ? ended.reason : "manual";
-        await rta.endCall(sessionId, { reason });
+        const owned = async (id) => config.ownsSession ? await config.ownsSession({ request, sessionId: id }) : minted.delete(id);
+        if (ended.session_id !== void 0 && await owned(ended.session_id)) {
+          await rta.endCall(ended.session_id, { reason });
+        }
+        if (ended.queue_ticket_id !== void 0 && await owned(ended.queue_ticket_id)) {
+          await rta.leaveQueue(ended.queue_ticket_id, { reason });
+        }
         return new Response(null, { status: 204 });
       }
-      const body = await request.json().catch(() => ({}));
-      if (!body.avatarId) return json({ error: "avatarId is required" }, 422);
-      const mode = body.mode === "voice" ? "voice" : "avatar";
+      const parsed = proxyConnectRequestSchema.safeParse(raw);
+      if (!parsed.success) return json({ error: "avatarId is required" }, 422);
+      const body = parsed.data;
+      const mode = body.mode ?? "avatar";
       const decided = await config.session?.({ request, avatarId: body.avatarId, mode });
       if (decided instanceof Response) return decided;
       const call = await rta.startCall({ avatarId: body.avatarId, mode, ...decided ?? {} });

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-DNHHQ5GZ.js';
-import './chunk-GMYGHDY2.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/express.ts

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-DNHHQ5GZ.js';
-import './chunk-GMYGHDY2.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/hono.ts

package/dist/index.d.ts

@@ -82,6 +82,18 @@ declare class RealtimeAvatar {
      * request body lets any visitor hang up any call on your account.
      */
     endCall(sessionId: string, options?: EndCallOptions): Promise<boolean>;
+    /**
+     * Give up a QUEUED call's place in line, by the `queueTicketId` that `startCall` returned.
+     *
+     * A queued call has no session yet, so {@link endCall} cannot reach it: the release contract
+     * carries the ticket in its own field, and a ticket sent as a session id names nothing and is
+     * acknowledged as an idempotent no-op. The place is then held until its TTL, at the front of
+     * the queue, in front of everyone behind it.
+     *
+     * Same contract as `endCall`: best-effort, `true` only when the platform acknowledged it,
+     * never a throw, and only for tickets YOUR SERVER was handed.
+     */
+    leaveQueue(queueTicketId: string, options?: Pick<EndCallOptions, "reason">): Promise<boolean>;
     /**
      * Register a character from a looping clip you host.
      *

package/dist/index.js

@@ -1,2 +1,2 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-GMYGHDY2.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-DNHHQ5GZ.js';
-import './chunk-GMYGHDY2.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/nextjs.ts

package/dist/playout-delay-CtRZdtsj.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Turning the microphone on, and saying what went wrong when it does not.
+ *
+ * WHY THIS EXISTS. `room.localParticipant.setMicrophoneEnabled(true)` is one line, so every
+ * integration writes it inline and none of them handle its rejection — the reject path is
+ * invisible until a real user is on a real machine. When it fails there is nothing to see:
+ * the call is already connected, the page is mid-`await`, and the rejection becomes an
+ * unhandled promise nobody is looking at. The reported symptom is always the same sentence —
+ * "the mic won't start" — and it covers at least six unrelated causes with different fixes,
+ * one of which is not in the browser at all.
+ *
+ * So this returns a RESULT rather than throwing: the cause becomes a value the caller has to
+ * handle, and each one carries the sentence that names its actual fix. `message` is what the
+ * browser said; `hint` is what the person should do.
+ *
+ * It is deliberately structural — it never imports `livekit-client`, so it pins no version
+ * and adds no bytes. Anything with a `localParticipant.setMicrophoneEnabled` satisfies it.
+ */
+/** The sliver of livekit-client's `Room` this needs. Structural on purpose — see above. */
+interface MicrophoneCapableRoom {
+    localParticipant: {
+        setMicrophoneEnabled(enabled: boolean): Promise<unknown>;
+    };
+}
+/**
+ * Why the microphone did not start. Every variant has a DIFFERENT fix, which is the whole
+ * reason this is an enum and not a boolean.
+ */
+type MicrophoneFailureReason = 
+/** No `navigator.mediaDevices` — the page is not a secure context. */
+"insecure-origin"
+/** The permission prompt was never answered. getUserMedia may never settle; we time out. */
+ | "no-answer"
+/** The BROWSER denied it — the site's own permission, resettable from the address bar. */
+ | "denied-by-browser"
+/** The OS denied it — macOS System Settings, nothing the page or the site can change. */
+ | "denied-by-os"
+/** No input device is connected, or none matches the constraints. */
+ | "no-device"
+/** A device exists but something else holds it — another tab, app, or a stale call. */
+ | "device-in-use"
+/** Anything unrecognised. `message` still carries what the browser said. */
+ | "unknown";
+type MicrophoneResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: MicrophoneFailureReason;
+    /** What the browser reported, verbatim. Show it — it is often exact. */
+    message: string;
+    /** What the person should actually do about it. */
+    hint: string;
+};
+interface EnableMicrophoneOptions {
+    /**
+     * How long to wait before calling it a no-answer. Default 15s.
+     *
+     * This is not belt-and-braces. Per the getUserMedia specification a prompt the user never
+     * dismisses may leave the promise permanently pending — "neither resolve nor reject" — and
+     * a page that awaits it in its connect path hangs on a state that has no error and no end.
+     * A deadline turns that into a reportable outcome.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Why a microphone that was WORKING stopped: the device was unplugged, or access was revoked
+ * mid-call. LiveKit tries the default device first and mutes the track when that fails too.
+ * Only a live call can report this; `enableMicrophone` never does.
+ */
+type MicrophoneProblemReason = MicrophoneFailureReason | "device-lost";
+/** A microphone problem as a value: the cause, what the browser said, and what to do. */
+type MicrophoneProblem = {
+    reason: MicrophoneProblemReason;
+    message: string;
+    hint: string;
+};
+/**
+ * Describe a microphone failure, whoever caught it. The one classifier behind both
+ * {@link enableMicrophone} and the React call handle's `microphone` state, so the two can never
+ * give the same failure different advice.
+ */
+declare function describeMicrophoneFailure(error: unknown): MicrophoneProblem;
+/**
+ * Publish the caller's microphone, and report WHY if it does not start.
+ *
+ * ```ts
+ * const mic = await enableMicrophone(room);
+ * if (!mic.ok) {
+ *   status.textContent = `Microphone: ${mic.message}`;
+ *   help.textContent = mic.hint;          // the sentence that names the fix
+ * }
+ * ```
+ *
+ * Never throws. A call that cannot start the microphone is an ordinary outcome of asking a
+ * person for a device, not a programmer error, so it belongs in the return type.
+ *
+ * Note it does NOT hang up on failure — the call is still live and still billing, and only
+ * the caller knows whether a text-only session is useful to them. If it is not, disconnect
+ * in the `!ok` branch; leaving a room connected against a device the user never granted is
+ * how the retry ends up contending with the call that is still holding it.
+ */
+declare function enableMicrophone(room: MicrophoneCapableRoom, options?: EnableMicrophoneOptions): Promise<MicrophoneResult>;
+
+/**
+ * Receiver-side playout delay (SECONDS) for the avatar media tracks.
+ *
+ * The avatar is published from a GPU datacenter and reaches viewers over the
+ * public internet, where a few percent of packet loss is normal. A shallow
+ * receiver buffer stalls (freezes) on every loss while it waits for a
+ * retransmit; a deeper buffer recovers the lost packets BEFORE playout, so the
+ * viewer sees smooth 25fps instead of freezing. Measured at ~5% loss this took
+ * the stream from ~11fps with multi-second freezes to a steady 25fps with zero
+ * freezes.
+ *
+ * 0.5s is applied via the native `RemoteTrack.setPlayoutDelay`, which sets the
+ * receiver's `playoutDelayHint` — the same Chromium jitter-buffer knob the old
+ * hand-rolled `jitterBufferTarget` reached into (the spec renamed
+ * playoutDelayHint→jitterBufferTarget; both influence the same buffer depth),
+ * but typed and SDK-owned so there is no cast or feature-probe. The hint is NOT
+ * free at the open: the receiver holds the FIRST video frame toward the target
+ * (~250-450ms of measured TTFF), a deliberate cost paid once for the freeze-free
+ * steady state above. The open-small-then-ramp variant that tried to dodge that
+ * cost was shipped, failed twice (the rVFC ramp trigger is throttled on the
+ * opacity:0-mounted element, stranding the shallow buffer), and was deliberately
+ * removed in 2262e4c7b — do not re-propose it. No-op on browsers that don't
+ * support the hint (the SDK warns and moves on).
+ *
+ * This lives in the vanilla browser package, not the React one, because the
+ * React surface applies it for you and a plain-DOM page has to be given it.
+ * Until this file existed the helper was only reachable through
+ * `realtime-avatar/react`, so every plain-DOM adopter — every one of this repo's
+ * own demos included — ran with the browser's default shallow buffer and froze on
+ * every lost packet. Nobody should have to know this knob exists: `prepareAvatarRoom`
+ * (and `attachRemoteAudio`, which calls it) applies it to every track the room
+ * subscribes, and `RealtimeAvatarLiveKitRoom` does the same for React. This file is
+ * the one place the number and its reasoning live.
+ * Structural like its siblings: no `livekit-client` import, no version pin.
+ */
+declare const DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS = 0.5;
+/**
+ * A track that can take a native playout-delay hint — livekit-client's subscribed
+ * `RemoteTrack`. Duck-typed on the method rather than `instanceof`, so a
+ * placeholder or local track is skipped and the helper is testable with a fake.
+ */
+interface PlayoutDelayTarget {
+    setPlayoutDelay(delayInSeconds: number): void;
+}
+/**
+ * Apply the receiver playout delay to ONE subscribed track.
+ *
+ * Call it for every track `RoomEvent.TrackSubscribed` hands you, audio and video
+ * alike, before or after `attach()` — WebRTC syncs the pair to the LARGER hint,
+ * so applying it to one stream and not the other lets the lips lag the voice.
+ * Returns `true` when the hint was applied and `false` when the object cannot take
+ * one (a local track, a placeholder, a not-yet-subscribed publication), so a
+ * caller can log the miss without a try/catch. The delay is floored at 0 so a
+ * negative input can never throw.
+ */
+declare function applyPlayoutDelay(track: unknown, delaySeconds?: number): boolean;
+/**
+ * Apply the SAME native playout delay to the avatar's audio + video tracks
+ * (kept equal so the a/v sync stays lip-locked). Pure and exported so the clamp
+ * and the both-tracks-equal invariant are unit-testable without a DOM; the React
+ * hook `useAvatarPlayoutDelay` is a thin effect wrapper around this.
+ */
+declare function applyAvatarPlayoutDelay(videoTrack: unknown, audioTrack: unknown, delaySeconds?: number): void;
+
+export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as D, type EnableMicrophoneOptions as E, type MicrophoneCapableRoom as M, type PlayoutDelayTarget as P, type MicrophoneFailureReason as a, type MicrophoneProblem as b, type MicrophoneProblemReason as c, type MicrophoneResult as d, applyAvatarPlayoutDelay as e, applyPlayoutDelay as f, describeMicrophoneFailure as g, enableMicrophone as h };