@runwayml/avatars-react 0.10.0-beta.0 → 0.10.0-beta.1

package/README.md

@@ -57,6 +57,8 @@ The styles use CSS custom properties for easy customization:
 See [`examples/`](./examples) for complete working examples:
 - [`nextjs`](./examples/nextjs) - Next.js App Router
 - [`nextjs-client-events`](./examples/nextjs-client-events) - Client event tools (trivia game)
+- [`nextjs-rpc`](./examples/nextjs-rpc) - Backend RPC + client events (trivia with server-side questions)
+- [`nextjs-rpc-weather`](./examples/nextjs-rpc-weather) - Backend RPC only (weather assistant)
 - [`nextjs-server-actions`](./examples/nextjs-server-actions) - Next.js with Server Actions
 - [`react-router`](./examples/react-router) - React Router v7 framework mode
 - [`express`](./examples/express) - Express + Vite
@@ -151,38 +153,41 @@ import { AvatarCall, AvatarVideo, ControlBar, UserVideo } from '@runwayml/avatar
 
 ### Render Props
 
-All components support render props for complete control:
+All display components support render props for complete control. `AvatarVideo` receives a discriminated union with `status`:
 
 ```tsx
 <AvatarVideo>
-  {({ hasVideo, isConnecting, trackRef }) => (
-    <div>
-      {isConnecting && <Spinner />}
-      {hasVideo && <VideoTrack trackRef={trackRef} />}
-    </div>
-  )}
+  {(avatar) => {
+    switch (avatar.status) {
+      case 'connecting': return <Spinner />;
+      case 'waiting': return <Placeholder />;
+      case 'ready': return <VideoTrack trackRef={avatar.videoTrackRef} />;
+    }
+  }}
 </AvatarVideo>
 ```
 
 ### CSS Styling with Data Attributes
 
-Style connection states with CSS:
+Style components with the namespaced `data-avatar-*` attributes:
 
 ```tsx
 <AvatarCall avatarId="music-superstar" connectUrl="/api/avatar/connect" className="my-avatar" />
 ```
 
 ```css
-.my-avatar[data-state="connecting"] {
+/* Style avatar video by connection status */
+[data-avatar-video][data-avatar-status="connecting"] {
   opacity: 0.5;
 }
 
-.my-avatar[data-state="error"] {
-  border: 2px solid red;
+[data-avatar-video][data-avatar-status="ready"] {
+  opacity: 1;
 }
 
-.my-avatar[data-state="connected"] {
-  border: 2px solid green;
+/* Style control buttons */
+[data-avatar-control][data-avatar-enabled="false"] {
+  opacity: 0.5;
 }
 ```
 
@@ -346,6 +351,8 @@ function MediaControls() {
 
 ## Client Events
 
+> **Compatibility:** Client events (tool calling) are supported on avatars that use a **preset voice**. Custom voice avatars do not currently support client events.
+
 Avatars can trigger UI events via tool calls sent over the data channel. Define tools, pass them when creating a session, and subscribe on the client:
 
 ```ts

package/dist/index.cjs

@@ -170,53 +170,6 @@ function parseClientEvent(payload) {
     return null;
   }
 }
-async function hasMediaDevice(kind, timeoutMs = 1e3) {
-  try {
-    const timeoutPromise = new Promise(
-      (resolve) => setTimeout(() => resolve(false), timeoutMs)
-    );
-    const checkPromise = navigator.mediaDevices.enumerateDevices().then((devices) => devices.some((device) => device.kind === kind));
-    return await Promise.race([checkPromise, timeoutPromise]);
-  } catch {
-    return false;
-  }
-}
-function useDeviceAvailability(requestAudio, requestVideo) {
-  const [state, setState] = react.useState({
-    audio: requestAudio,
-    // Optimistically assume devices exist
-    video: requestVideo
-  });
-  react.useEffect(() => {
-    let cancelled = false;
-    async function checkDevices() {
-      const [hasAudio, hasVideo] = await Promise.all([
-        requestAudio ? hasMediaDevice("audioinput") : Promise.resolve(false),
-        requestVideo ? hasMediaDevice("videoinput") : Promise.resolve(false)
-      ]);
-      if (!cancelled) {
-        setState({
-          audio: requestAudio && hasAudio,
-          video: requestVideo && hasVideo
-        });
-      }
-    }
-    checkDevices();
-    return () => {
-      cancelled = true;
-    };
-  }, [requestAudio, requestVideo]);
-  return state;
-}
-var MEDIA_DEVICE_ERROR_NAMES = /* @__PURE__ */ new Set([
-  "NotAllowedError",
-  "NotFoundError",
-  "NotReadableError",
-  "OverconstrainedError"
-]);
-function isMediaDeviceError(error) {
-  return MEDIA_DEVICE_ERROR_NAMES.has(error.name);
-}
 var DEFAULT_ROOM_OPTIONS = {
   adaptiveStream: false,
   dynacast: false
@@ -238,6 +191,7 @@ function mapConnectionState(connectionState) {
 var AvatarSessionContext = react.createContext(
   null
 );
+var MediaDeviceErrorContext = react.createContext(null);
 function AvatarSession({
   credentials,
   children,
@@ -250,12 +204,9 @@ function AvatarSession({
   __unstable_roomOptions
 }) {
   const errorRef = react.useRef(null);
-  const deviceAvailability = useDeviceAvailability(requestAudio, requestVideo);
   const handleError = (error) => {
     onError?.(error);
-    if (!isMediaDeviceError(error)) {
-      errorRef.current = error;
-    }
+    errorRef.current = error;
   };
   const roomOptions = {
     ...DEFAULT_ROOM_OPTIONS,
@@ -267,8 +218,8 @@ function AvatarSession({
       serverUrl: credentials.serverUrl,
       token: credentials.token,
       connect: true,
-      audio: deviceAvailability.audio,
-      video: deviceAvailability.video,
+      audio: false,
+      video: false,
       onDisconnected: () => onEnd?.(),
       onError: handleError,
       options: roomOptions,
@@ -280,6 +231,8 @@ function AvatarSession({
           AvatarSessionContextInner,
           {
             sessionId: credentials.sessionId,
+            requestAudio,
+            requestVideo,
             onEnd,
             onClientEvent,
             errorRef,
@@ -294,6 +247,8 @@ function AvatarSession({
 }
 function AvatarSessionContextInner({
   sessionId,
+  requestAudio,
+  requestVideo,
   onEnd,
   onClientEvent,
   errorRef,
@@ -329,6 +284,64 @@ function AvatarSessionContextInner({
       });
     };
   }, [connectionState, initialScreenStream, room]);
+  const [micError, setMicError] = react.useState(null);
+  const [cameraError, setCameraError] = react.useState(null);
+  const mediaEnabledRef = react.useRef(false);
+  react.useEffect(() => {
+    if (connectionState !== livekitClient.ConnectionState.Connected) return;
+    if (mediaEnabledRef.current) return;
+    mediaEnabledRef.current = true;
+    async function enableMedia() {
+      if (requestAudio) {
+        try {
+          await room.localParticipant.setMicrophoneEnabled(true);
+        } catch (err) {
+          if (err instanceof Error) setMicError(err);
+        }
+      }
+      if (requestVideo) {
+        try {
+          await room.localParticipant.setCameraEnabled(true);
+        } catch (err) {
+          if (err instanceof Error) setCameraError(err);
+        }
+      }
+    }
+    enableMedia();
+  }, [connectionState, room, requestAudio, requestVideo]);
+  react.useEffect(() => {
+    function handleMediaDevicesError(error, kind) {
+      if (kind === "audioinput") {
+        setMicError(error);
+      } else if (kind === "videoinput") {
+        setCameraError(error);
+      }
+    }
+    room.on(livekitClient.RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    return () => {
+      room.off(livekitClient.RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    };
+  }, [room]);
+  const retryMic = react.useCallback(async () => {
+    try {
+      await room.localParticipant.setMicrophoneEnabled(true);
+      setMicError(null);
+    } catch (err) {
+      if (err instanceof Error) setMicError(err);
+    }
+  }, [room]);
+  const retryCamera = react.useCallback(async () => {
+    try {
+      await room.localParticipant.setCameraEnabled(true);
+      setCameraError(null);
+    } catch (err) {
+      if (err instanceof Error) setCameraError(err);
+    }
+  }, [room]);
+  const mediaDeviceErrors = react.useMemo(
+    () => ({ micError, cameraError, retryMic, retryCamera }),
+    [micError, cameraError, retryMic, retryCamera]
+  );
   react.useEffect(() => {
     function handleDataReceived(payload) {
       const event = parseClientEvent(payload);
@@ -357,7 +370,7 @@ function AvatarSessionContextInner({
     error: errorRef.current,
     end
   };
-  return /* @__PURE__ */ jsxRuntime.jsx(AvatarSessionContext.Provider, { value: contextValue, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(AvatarSessionContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxRuntime.jsx(MediaDeviceErrorContext.Provider, { value: mediaDeviceErrors, children }) });
 }
 function useAvatarSessionContext() {
   const context = react.useContext(AvatarSessionContext);
@@ -368,6 +381,9 @@ function useAvatarSessionContext() {
   }
   return context;
 }
+function useMediaDeviceErrorContext() {
+  return react.useContext(MediaDeviceErrorContext);
+}
 function useAvatar() {
   const remoteParticipants = componentsReact.useRemoteParticipants();
   const avatarParticipant = remoteParticipants[0] ?? null;
@@ -433,8 +449,16 @@ function AvatarVideo({ children, ...props }) {
     }
   );
 }
+var NOOP_ASYNC = async () => {
+};
 function useLocalMedia() {
   const { localParticipant } = componentsReact.useLocalParticipant();
+  const {
+    micError = null,
+    cameraError = null,
+    retryMic = NOOP_ASYNC,
+    retryCamera = NOOP_ASYNC
+  } = useMediaDeviceErrorContext() ?? {};
   const audioDevices = componentsReact.useMediaDevices({ kind: "audioinput" });
   const videoDevices = componentsReact.useMediaDevices({ kind: "videoinput" });
   const hasMic = audioDevices?.length > 0;
@@ -480,7 +504,11 @@ function useLocalMedia() {
     toggleMic,
     toggleCamera,
     toggleScreenShare,
-    localVideoTrackRef
+    localVideoTrackRef,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
 }
 function ControlBar({
@@ -498,7 +526,11 @@ function ControlBar({
     isScreenShareEnabled,
     toggleMic,
     toggleCamera,
-    toggleScreenShare
+    toggleScreenShare,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   } = useLocalMedia();
   const isActive = session.state === "active";
   const state = {
@@ -509,7 +541,11 @@ function ControlBar({
     toggleCamera,
     toggleScreenShare,
     endCall: session.end,
-    isActive
+    isActive,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
   if (children) {
     return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children(state) });