realtime-avatar 0.23.0 → 0.24.1

package/README.md

@@ -25,6 +25,47 @@ return call.raw;   // relay to the browser byte-for-byte
 
 That is the whole server half. The client joins with the payload and renders her.
 
+## React Native compatibility
+
+The next release requires **LiveKit React Native 3** for `/react-native`; it does not claim
+compatibility with LiveKit React Native 2. Install the tested group together:
+
+```bash
+npm install --save-exact @livekit/react-native@3.0.0 @livekit/react-native-webrtc@144.2.0 livekit-client@2.22.3 @livekit/components-react@2.9.21
+```
+
+`@livekit/components-react@2.9.21` retains `@livekit/components-core@0.12.13`; both satisfy the
+native 3.0.0 peer contracts. Keep a single resolved components-react instance: the native room
+provides its context and the SDK's shared hooks consume that same context. SDK checks use React
+19.2.7 and React Native 0.81.5. The web binding also uses client 2.22.3; no components upgrade or
+stream-handling patch is required for this tuple. Peer ranges allow compatible updates, but only
+this exact tuple has been checked here. Client 2.22.3 introduces `machina@7.0.1`, whose Node
+engine is `>=22.22`; use Node 22.22 or newer for client/native tooling (verified on 22.23.1).
+This does not change the dependency-free server entry's Node floor. Node 20 tooling is not
+verified for the new LiveKit group.
+
+Call the SDK's re-exported `registerGlobals()` once at app startup, before creating rooms. RN3
+configures iOS audio natively by default; do not reintroduce the deprecated JavaScript audio
+management callback. `RealtimeAvatarLiveKitRoom` retains the existing `AudioSession.startAudioSession`
+and `stopAudioSession` lifecycle while a grant and `connect` intent are present. Apps that own audio
+configuration or coordinate overlapping calls must pass `manageAudioSession={false}` and own that
+lifecycle; the hook is not a shared audio-session lease. Camera publication still requires both the
+server grant's permission and the caller's opt-in. Room callbacks/options continue to use LiveKit's
+public types and implementation; no separate connection state machine is introduced.
+
+**This is a native build upgrade, not an OTA-only change.** Rebuild iOS and Android binaries with
+RN3/WebRTC 144.2.0 before shipping JavaScript that requires them. Retain the previous SDK group for
+installed binaries that still use RN2, and isolate their OTA runtime/channel appropriately.
+
+The packaged-entry regression suite mounts the built `/react-native` adapter with the installed
+RN3 room and audio implementations, real React/LiveKit hooks, and shared contexts. It checks room
+props, microphone/camera policy, callbacks, start/stop intent, redial, and listener cleanup. It mocks
+native module calls, network connection and media capture; it does **not** prove native binary
+linking, `registerGlobals`, RTCView rendering, permissions, Bluetooth/speaker routing, interruption
+recovery, asynchronous OS audio teardown, or overlapping-room ownership. Test these on iOS and
+Android devices, including repeated call/redial and background/foreground transitions, before a
+consumer release.
+
 ## Optional call recordings
 
 Your server decides whether to record after your application obtains consent:

package/dist/{chunk-ICBVEIRK.js → chunk-4PWWEERK.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-6JLDTWL4.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-EODL5S3A.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/{chunk-6JLDTWL4.js → chunk-EODL5S3A.js}

@@ -654,7 +654,7 @@ z.enum([
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.23.0";
+var SDK_VERSION = "0.24.1";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DP4GsT1R.js';
-import './types-C7s0yw8q.js';
+import { P as ProxyConfig } from './types-CpqMHna3.js';
+import './types-D77jgSms.js';
 import 'zod';
 
 type Expressish = {

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-ICBVEIRK.js';
-import './chunk-6JLDTWL4.js';
+import { createProxyHandler } from './chunk-4PWWEERK.js';
+import './chunk-EODL5S3A.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/express.ts

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DP4GsT1R.js';
-import './types-C7s0yw8q.js';
+import { P as ProxyConfig } from './types-CpqMHna3.js';
+import './types-D77jgSms.js';
 import 'zod';
 
 /**

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-ICBVEIRK.js';
-import './chunk-6JLDTWL4.js';
+import { createProxyHandler } from './chunk-4PWWEERK.js';
+import './chunk-EODL5S3A.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/hono.ts

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload } from './types-C7s0yw8q.js';
-export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as RecordingArtifactStatus, x as RecordingMode, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-C7s0yw8q.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload } from './types-D77jgSms.js';
+export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as RecordingArtifactStatus, x as RecordingMode, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-D77jgSms.js';
 import { ConnectionHistoryResponse } from './connection-history.js';
 import { z } from 'zod';
 

package/dist/index.js

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

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DP4GsT1R.js';
-import './types-C7s0yw8q.js';
+import { P as ProxyConfig } from './types-CpqMHna3.js';
+import './types-D77jgSms.js';
 import 'zod';
 
 /**

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-ICBVEIRK.js';
-import './chunk-6JLDTWL4.js';
+import { createProxyHandler } from './chunk-4PWWEERK.js';
+import './chunk-EODL5S3A.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/nextjs.ts

package/dist/react-native.js

@@ -706,32 +706,35 @@ function useLiveKitAvatarGrant(input) {
       warmLiveKitHost(serverUrlHintRef.current ?? readLiveKitUrlHint());
       setState({ status: "requesting", grant: null, busy: null, error: null });
     }
-    void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
-      if (cancelled) {
-        if (result.status !== "busy") {
-          void client.releaseLiveKitSession(result.grant.session_id, "superseded");
-        }
-        return;
-      }
-      if (result.status === "busy") {
-        queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
-        setState({ status: "busy", grant: null, busy: result.busy, error: null });
-        return;
-      }
-      queueTicketRef.current = null;
-      if (heldSessionRef.current && heldSessionRef.current !== result.grant.session_id) {
-        releaseHeld("superseded", false);
-      }
-      heldSessionRef.current = result.grant.session_id;
-      writeLiveKitUrlHint(result.grant.livekit_url);
-      setState({ status: "ready", grant: result.grant, busy: null, error: null });
-    }).catch((error) => {
+    queueMicrotask(() => {
       if (cancelled) return;
-      setState({
-        status: "failed",
-        grant: null,
-        busy: null,
-        error: error instanceof Error ? error : new Error(String(error))
+      void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
+        if (cancelled) {
+          if (result.status !== "busy") {
+            void client.releaseLiveKitSession(result.grant.session_id, "superseded");
+          }
+          return;
+        }
+        if (result.status === "busy") {
+          queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
+          setState({ status: "busy", grant: null, busy: result.busy, error: null });
+          return;
+        }
+        queueTicketRef.current = null;
+        if (heldSessionRef.current && heldSessionRef.current !== result.grant.session_id) {
+          releaseHeld("superseded", false);
+        }
+        heldSessionRef.current = result.grant.session_id;
+        writeLiveKitUrlHint(result.grant.livekit_url);
+        setState({ status: "ready", grant: result.grant, busy: null, error: null });
+      }).catch((error) => {
+        if (cancelled) return;
+        setState({
+          status: "failed",
+          grant: null,
+          busy: null,
+          error: error instanceof Error ? error : new Error(String(error))
+        });
       });
     });
     return () => {

package/dist/react.js

@@ -860,32 +860,35 @@ function useLiveKitAvatarGrant(input) {
       warmLiveKitHost(serverUrlHintRef.current ?? readLiveKitUrlHint());
       setState({ status: "requesting", grant: null, busy: null, error: null });
     }
-    void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
-      if (cancelled) {
-        if (result.status !== "busy") {
-          void client.releaseLiveKitSession(result.grant.session_id, "superseded");
-        }
-        return;
-      }
-      if (result.status === "busy") {
-        queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
-        setState({ status: "busy", grant: null, busy: result.busy, error: null });
-        return;
-      }
-      queueTicketRef.current = null;
-      if (heldSessionRef.current && heldSessionRef.current !== result.grant.session_id) {
-        releaseHeld("superseded", false);
-      }
-      heldSessionRef.current = result.grant.session_id;
-      writeLiveKitUrlHint(result.grant.livekit_url);
-      setState({ status: "ready", grant: result.grant, busy: null, error: null });
-    }).catch((error) => {
+    queueMicrotask(() => {
       if (cancelled) return;
-      setState({
-        status: "failed",
-        grant: null,
-        busy: null,
-        error: error instanceof Error ? error : new Error(String(error))
+      void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
+        if (cancelled) {
+          if (result.status !== "busy") {
+            void client.releaseLiveKitSession(result.grant.session_id, "superseded");
+          }
+          return;
+        }
+        if (result.status === "busy") {
+          queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
+          setState({ status: "busy", grant: null, busy: result.busy, error: null });
+          return;
+        }
+        queueTicketRef.current = null;
+        if (heldSessionRef.current && heldSessionRef.current !== result.grant.session_id) {
+          releaseHeld("superseded", false);
+        }
+        heldSessionRef.current = result.grant.session_id;
+        writeLiveKitUrlHint(result.grant.livekit_url);
+        setState({ status: "ready", grant: result.grant, busy: null, error: null });
+      }).catch((error) => {
+        if (cancelled) return;
+        setState({
+          status: "failed",
+          grant: null,
+          busy: null,
+          error: error instanceof Error ? error : new Error(String(error))
+        });
       });
     });
     return () => {

package/dist/server.d.ts

@@ -1,4 +1,4 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, clipLibraryDeclarationSchema, verifyTranscript } from './index.js';
-export { h as Asset, g as AssetKind, A as Avatar, o as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, p as CallConnection, C as CallMode, a as CallPolicy, q as CallQueued, r as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, s as ClipLibraryPlan, e as ClipLibraryUpdate, t as ClipSource, u as ContextMessage, n as CreditBalance, E as EndCallOptions, v as EndCallReason, k as ListRecordingsQuery, l as ListRecordingsResponse, i as ListSessionsOptions, L as LoopRedirect, m as RecordingAccessResponse, R as RecordingArtifact, w as RecordingArtifactStatus, x as RecordingMode, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-C7s0yw8q.js';
+export { h as Asset, g as AssetKind, A as Avatar, o as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, p as CallConnection, C as CallMode, a as CallPolicy, q as CallQueued, r as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, s as ClipLibraryPlan, e as ClipLibraryUpdate, t as ClipSource, u as ContextMessage, n as CreditBalance, E as EndCallOptions, v as EndCallReason, k as ListRecordingsQuery, l as ListRecordingsResponse, i as ListSessionsOptions, L as LoopRedirect, m as RecordingAccessResponse, R as RecordingArtifact, w as RecordingArtifactStatus, x as RecordingMode, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-D77jgSms.js';
 import './connection-history.js';
 import 'zod';

package/dist/server.js

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

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DP4GsT1R.js';
-import './types-C7s0yw8q.js';
+import { P as ProxyConfig } from './types-CpqMHna3.js';
+import './types-D77jgSms.js';
 import 'zod';
 
 /**

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-ICBVEIRK.js';
-import './chunk-6JLDTWL4.js';
+import { createProxyHandler } from './chunk-4PWWEERK.js';
+import './chunk-EODL5S3A.js';
 import './chunk-MCIXU6XP.js';
 
 // src/tanstack-start.ts

package/dist/{types-DP4GsT1R.d.ts → types-CpqMHna3.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-C7s0yw8q.js';
+import { C as CallMode, a as CallPolicy } from './types-D77jgSms.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/dist/{types-C7s0yw8q.d.ts → types-D77jgSms.d.ts}

@@ -179,6 +179,17 @@ interface components {
             /** @description DEPRECATED, no-op. Accepted and ignored. The faster hesitation ceiling this requested is now the default for every session, so sending it changes nothing. Safe to stop sending; the field is retained only so existing callers do not break. */
             fast_endpointing?: boolean;
             require_ready_clip_library?: boolean;
+            /** @description Preview, enabled per workspace. A prepared scene from POST /v1/scenes, played forward over its full length in place of the avatar's source video; the avatar keeps the voice and persona. Cannot be combined with mode voice, render_backend generative, source_video_url, video_cache_id or a non-empty clip_library. */
+            scene?: {
+                /** @description The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready. */
+                video_cache_id: string;
+                /** @description Frames in the first clip. The loop closes seamlessly at the wrap only when a continuation follows it. */
+                first_frames?: number;
+                /** @description Frames in the whole artifact (first plus continuation). */
+                total_frames?: number;
+                /** @description Preview. Set when this scene is a first clip alone: the joined scene (the same first clip plus its continuation) that this workspace prepares after the mint may then be attached to the live call. Linking needs the first clip's md5 and bytes declared on both prepares. Absent or false plays this scene for the whole call. */
+                attach_continuation?: boolean;
+            };
         };
         LiveKitSessionGrant: {
             /** @description Returned only for X-RTA-Observability: identity-v1 after successful platform billing attachment. The authoritative billing hold tenant ID; never client metadata or provider identity. Omitted by default and on failed or queued responses. Older servers may omit it. */
@@ -695,6 +706,9 @@ interface components {
             portraitUrl?: string;
             sourceAssetId?: string;
             anchorTimeMs?: number;
+            sourceReview?: {
+                reason: string;
+            };
         };
         CreateApiKeyRequest: {
             name: string;
@@ -759,6 +773,81 @@ interface components {
                 [key: string]: unknown;
             };
         };
+        CreateSceneRequest: {
+            /** @description The first clip. Played forward over its full length. */
+            source: {
+                /**
+                 * Format: uri
+                 * @description An https URL the builder can fetch. Hosts are allowlisted by the builder.
+                 */
+                url: string;
+                /** @description MD5 of the clip bytes. With bytes, lets an already-built scene answer ready without a download. */
+                md5?: string;
+                /** @description Clip size in bytes (at most 64 MiB). */
+                bytes?: number;
+            };
+            /** @description Optional return clip appended after the first. When its last frame matches the first clip's first frame, the loop closes seamlessly. */
+            continuation?: {
+                /**
+                 * Format: uri
+                 * @description An https URL the builder can fetch. Hosts are allowlisted by the builder.
+                 */
+                url: string;
+                /** @description MD5 of the clip bytes. With bytes, lets an already-built scene answer ready without a download. */
+                md5?: string;
+                /** @description Clip size in bytes (at most 64 MiB). */
+                bytes?: number;
+            };
+            /** @enum {string} */
+            profile: "scene-v0";
+        };
+        SceneState: {
+            /** @constant */
+            status: "building";
+            /** @description The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready. */
+            scene_id: string;
+            timings?: {
+                download_ms?: number;
+                decode_ms?: number;
+                geometry_ms?: number;
+                write_ms?: number;
+                total_ms?: number;
+            };
+        } | {
+            /** @constant */
+            status: "ready";
+            /** @description The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready. */
+            scene_id: string;
+            /** @description The prepared scene's artifact id, as returned by POST /v1/scenes when status is ready. */
+            video_cache_id?: string;
+            fps?: number;
+            width?: number;
+            height?: number;
+            first_frames?: number;
+            total_frames?: number;
+            duration_s?: number;
+            timings?: {
+                download_ms?: number;
+                decode_ms?: number;
+                geometry_ms?: number;
+                write_ms?: number;
+                total_ms?: number;
+            };
+        } | {
+            /** @constant */
+            status: "failed";
+            /** @description The scene id, or "unresolved" when the download failed before any byte was hashed and the request carried no md5 and bytes. */
+            scene_id: string | "unresolved";
+            /** @enum {string} */
+            error?: "source_unreachable" | "source_unusable" | "source_mismatch" | "build_failed";
+            timings?: {
+                download_ms?: number;
+                decode_ms?: number;
+                geometry_ms?: number;
+                write_ms?: number;
+                total_ms?: number;
+            };
+        };
         CreditBalance: {
             tenantId: string;
             balanceCreditMicros: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",
@@ -118,7 +118,9 @@
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
     "@livekit/components-react": "2.9.21",
-    "@livekit/react-native": "^2.11.1",
+    "@livekit/react-native": "3.0.0",
+    "@livekit/react-native-webrtc": "144.2.0",
+    "livekit-client": "2.22.3",
     "@types/react": "19.2.7",
     "react": "19.2.7",
     "react-dom": "19.2.7",
@@ -127,11 +129,12 @@
   },
   "peerDependencies": {
     "@livekit/components-react": "^2.9.0",
-    "@livekit/react-native": "^2.11.0",
+    "@livekit/react-native": "^3.0.0",
+    "@livekit/react-native-webrtc": "^144.2.0",
     "react": ">=18",
     "react-dom": ">=18",
     "react-native": ">=0.78",
-    "livekit-client": "^2.9.0",
+    "livekit-client": "^2.22.3",
     "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
@@ -141,6 +144,9 @@
     "@livekit/react-native": {
       "optional": true
     },
+    "@livekit/react-native-webrtc": {
+      "optional": true
+    },
     "react-dom": {
       "optional": true
     },