realtime-avatar 0.22.0 → 0.23.0

package/dist/react.d.ts

@@ -1,7 +1,9 @@
 import { RegisteredTool, ToolRegistration } from './tools.js';
-import { ah as SessionLifecycleRoomBridgeProps, h as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-6ndCkiio.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, aM as AvatarVideoSurface, aN as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, aO as LivePlaybackKeeper, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, aP as MIC_LEASE_ENDED_TIMEOUT_MS, aQ as MicLease, aR as NETWORK_QUALITY_POLICY, aS as NetworkQualityStatus, aT as PlayableVideoElement, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, aU as RealtimeAvatarCapacityError, aV as RealtimeAvatarLiveKitRoom, aW as RealtimeAvatarLiveKitRoomProps, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aX as shouldReplayPendingTurn, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarCamera, aD as useAvatarPlayoutDelay, aE as useAvatarQualityGovernor, aF as useCallTranscript, aG as useLiveKitAvatarGrant, aI as useMicLease, aJ as useRealtimeSession, aK as useReleaseMicLeaseOnTrackEnded, aL as useSessionLifecycle } from './proxy-client-6ndCkiio.js';
+import { aj as SessionLifecycleRoomBridgeProps, h as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-DlFXaXtn.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, aQ as AvatarVideoSurface, aR as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, u as DeclaredInputSource, E as EndReason, v as EndedEvent, w as ExtendResult, F as FishTtsModel, x as FreezeReadingFn, G as Governor, y as GovernorAction, z as GovernorConfig, H as GovernorSignal, I as GovernorState, J as GraceWindowClosedEvent, K as GraceWindowOpenEvent, M as GraceWindowState, N as IdleWarningEvent, O as InboundRtpCursor, P as InboundRtpReading, Q as KnownBehaviorState, R as LLMProvider, S as LLMSelection, T as LiveKitAvatarGrantState, U as LiveKitAvatarGrantStatus, V as LiveKitCapacityState, W as LiveKitConnectionStatus, X as LiveKitSessionRequest, Y as LiveKitSessionStartResult, aS as LivePlaybackKeeper, Z as MAX_RECONNECT_ATTEMPTS, _ as MAX_SESSION_INSTRUCTIONS_CHARS, aT as MIC_LEASE_ENDED_TIMEOUT_MS, aU as MicLease, aV as NETWORK_QUALITY_POLICY, aW as NetworkQualityStatus, aX as PlayableVideoElement, $ as ProxyClientOptions, a0 as QualityCap, a1 as RECONNECT_BACKOFF_MS, aY as RealtimeAvatarCapacityError, aZ as RealtimeAvatarLiveKitRoom, a_ as RealtimeAvatarLiveKitRoomProps, a2 as RealtimeAvatarRequestOptions, a3 as RealtimeSessionApi, a4 as RealtimeSessionMedia, a5 as RealtimeSessionRoomSinks, a6 as ReconnectPolicy, a7 as ReconnectingEvent, a8 as RecoveryState, a9 as RetryStep, aa as SendTurnOptions, ab as SessionBehavior, ac as SessionClip, ad as SessionClocks, ae as SessionEndReason, af as SessionLifecycleApi, ag as SessionLifecyclePhase, ah as SessionLifecyclePhaseKind, ai as SessionLifecycleRoomBridge, ak as SurfaceLayers, al as TranscriptSender, am as TranscriptSenderOptions, an as TurnState, ao as TurnTimeoutEvent, ap as UseAvatarQualityGovernorInput, aq as UseLiveKitAvatarGrantInput, ar as UseRealtimeSessionInput, as as UseSessionLifecycleInput, at as VoiceSpec, au as VoiceSpecInput, av as capacityErrorFromBusy, aw as capacityStateFromGrant, ax as createProxyClient, az as knownBehaviorStates, aA as mapTurnState, aB as readInboundRtp, aC as sessionBehaviorSchema, aD as sessionClipSchema, a$ as shouldReplayPendingTurn, aE as splitCallTranscript, aF as useAvatarAdaptivePlayoutDelay, aG as useAvatarCamera, aH as useAvatarPlayoutDelay, aI as useAvatarQualityGovernor, aJ as useCallTranscript, aK as useLiveKitAvatarGrant, aM as useMicLease, aN as useRealtimeSession, aO as useReleaseMicLeaseOnTrackEnded, aP as useSessionLifecycle } from './proxy-client-DlFXaXtn.js';
 import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { R as RecordingArtifact } from './recording-DjswTx5B.js';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';
 import 'zod';
 import 'livekit-client';
@@ -129,4 +131,14 @@ declare function useAvatarCall(props: AvatarCallProps): {
 /** One component: a live character on screen. */
 declare function AvatarCall(props: AvatarCallProps): ReactNode;
 
-export { AvatarCall, type AvatarCallEndReason, type AvatarCallHandle, type AvatarCallProps, type AvatarCallStatus, AvatarSessionClient, AvatarVideoFit, DEFAULT_AVATAR_UNSTABLE_STALL_MS, SessionLifecycleRoomBridgeProps, useAvatarCall, useCharacterTools };
+type RecordingPlaybackAsset = {
+    recording: RecordingArtifact;
+    url: string;
+};
+/** Each participant file carries only its own voice; one clock drives both files. */
+declare function RecordingPlayer({ assets, className }: {
+    assets: readonly RecordingPlaybackAsset[];
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+
+export { AvatarCall, type AvatarCallEndReason, type AvatarCallHandle, type AvatarCallProps, type AvatarCallStatus, AvatarSessionClient, AvatarVideoFit, DEFAULT_AVATAR_UNSTABLE_STALL_MS, type RecordingPlaybackAsset, RecordingPlayer, SessionLifecycleRoomBridgeProps, useAvatarCall, useCharacterTools };

package/dist/react.js

@@ -3,6 +3,7 @@ import { useRef, useState, useEffect, useCallback, useMemo, createElement, Fragm
 import { useRoomContext, useConnectionState, useLocalParticipant, useTranscriptions, RoomAudioRenderer, LiveKitRoom, useMaybeRoomContext, useVoiceAssistant, VideoTrack, useChat } from '@livekit/components-react';
 import { ConnectionState, isRemoteTrack, VideoQuality, ConnectionQuality, RoomEvent, TrackEvent, Track, ConnectionError, ConnectionErrorReason, DisconnectReason, createLocalVideoTrack, Room } from 'livekit-client';
 import { z } from 'zod';
+import { jsxs, jsx } from 'react/jsx-runtime';
 
 // ../client/src/react/use-character-tools.ts
 var invocationSchema = z.object({
@@ -2119,15 +2120,22 @@ var AVATAR_VIDEO_LIVE_WRAP = "absolute inset-0 z-20 size-full transition-opacity
 var AVATAR_VIDEO_BADGE = "absolute top-2 right-2 z-30 inline-flex items-center gap-1.5 rounded-md bg-black/55 px-1.5 py-0.5 font-mono text-[10px] text-white/85 backdrop-blur-sm";
 var AVATAR_VIDEO_BADGE_DOT = "size-1.5 rounded-full bg-emerald-400";
 var RECORDED_MEDIA_MODES = ["audio", "video", "audio_video"];
-var recordingModeSchema = z.enum(["off", ...RECORDED_MEDIA_MODES]).describe("Server-owned recording policy; omitted means off. Audio includes user and avatar audio.");
+var recordingModeSchema = z.enum(["off", ...RECORDED_MEDIA_MODES, "participants"]).describe("Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices.");
 var RECORDING_STATUSES = ["pending", "recording", "processing", "ready", "failed", "expired"];
 z.enum(RECORDING_STATUSES);
+var recordingParticipantSchema = z.object({
+  participantIdentity: z.string().min(1).max(160),
+  role: z.enum(["user", "avatar"])
+}).strict();
 var recordingMetadataSchema = z.object({
   sessionId: z.string().min(1),
   recordingId: z.string().min(1),
-  mode: recordingModeSchema.exclude(["off"]),
+  mode: z.enum(RECORDED_MEDIA_MODES),
   createdAt: z.string().datetime({ offset: true }),
-  retainedUntil: z.string().datetime({ offset: true })
+  retainedUntil: z.string().datetime({ offset: true }),
+  participant: recordingParticipantSchema.optional(),
+  mediaStartedAt: z.string().datetime({ offset: true }).optional(),
+  mediaEndedAt: z.string().datetime({ offset: true }).optional()
 });
 var recordingArtifactSchema = z.discriminatedUnion("status", [
   recordingMetadataSchema.extend({ status: z.enum(["pending", "recording", "processing", "expired"]) }).strict(),
@@ -2434,6 +2442,8 @@ z.object({
 }).strict();
 z.object({
   recording: recordingArtifactSchema.optional(),
+  recording_mode: recordingModeSchema.optional(),
+  recordings: z.array(recordingArtifactSchema).max(2).optional(),
   connection_history: connectionHistoryGrantSchema.optional(),
   status: z.literal("ready").default("ready"),
   session_id: z.string().min(1),
@@ -2454,6 +2464,11 @@ var RTA_LIFECYCLE_TOPIC = "rta.lifecycle";
 var RTA_TURN_INSTRUCTIONS_ATTR = "rta.turn_instructions";
 var RTA_CLOSING_TURN_ATTR = "rta.closing_turn";
 var RTA_TURN_ID_ATTR = "rta.turn_id";
+var RTA_RETRY_OF_TURN_ID_ATTR = "rta.retry_of_turn_id";
+var RTA_INPUT_SOURCE_VERSION_ATTR = "rta.input_source_version";
+var RTA_OBSERVED_INPUT_SOURCE_ATTR = "rta.observed_input_source";
+var RTA_DECLARED_INPUT_SOURCE_ATTR = "rta.declared_input_source";
+var RTA_INPUT_SOURCE_DECLARATION_SCOPE_ATTR = "rta.input_source_declaration_scope";
 var sessionEndReasonSchema = z.enum([
   "user_ended",
   "session_cap",
@@ -3394,6 +3409,11 @@ var DEFAULT_CREDITS_LOW_LEAD_SECONDS = 300;
 function positive(value, fallbackSeconds) {
   return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallbackSeconds;
 }
+function validateInputSource(value) {
+  if (value !== void 0 && value !== "text" && value !== "client_stt") {
+    throw new TypeError('inputSource must be "text" or "client_stt"');
+  }
+}
 function useRealtimeSession(input) {
   const {
     session,
@@ -3451,7 +3471,8 @@ function useRealtimeSession(input) {
   const turnSenderRef = useRef(null);
   const dataPublisherRef = useRef(null);
   const lastTurnRef = useRef(null);
-  const [clockTick, setClockTick] = useState(0);
+  const turnSequenceRef = useRef(0);
+  const [, setClockTick] = useState(0);
   const endsAt = endsAtFrom({
     serverStartedAtUnixMs: serverClock?.startedAtUnixMs ?? null,
     maxSessionSeconds: serverClock?.maxSessionSeconds ?? null
@@ -3473,8 +3494,8 @@ function useRealtimeSession(input) {
       if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
     } catch {
     }
-    return `t-${Date.now()}-${clockTick}`;
-  }, [clockTick]);
+    return `t-${Date.now()}-${++turnSequenceRef.current}`;
+  }, []);
   const onLifecycleData = useCallback((frame) => {
     const parsed = lifecycleServerFrameSchema.safeParse(frame);
     if (!parsed.success) return;
@@ -3574,8 +3595,8 @@ function useRealtimeSession(input) {
         if (gw === "open" || gw === "delivering") stayConnected();
       }
       const turnInfo = lastTurnRef.current;
-      if (turnInfo && now - turnInfo.sentAt >= turnTimeoutMs) {
-        lastTurnRef.current = null;
+      if (turnInfo && turnInfo.sentAt !== null && now - turnInfo.sentAt >= turnTimeoutMs) {
+        turnInfo.sentAt = null;
         cbRef.current.onTurnTimeout?.({ turnId: turnInfo.id });
       }
       setClockTick((value) => value + 1);
@@ -3604,6 +3625,7 @@ function useRealtimeSession(input) {
   }, [phaseKind, lifecycle.phase, lifecycle.attempt]);
   useEffect(() => {
     if (phaseKind === "ended") {
+      lastTurnRef.current = null;
       if (!endedFiredRef.current) {
         endedFiredRef.current = true;
         const inner2 = lifecycle.phase.kind === "ended" ? lifecycle.phase.reason : void 0;
@@ -3640,23 +3662,47 @@ function useRealtimeSession(input) {
     setGraceWindow({ kind: "closed" });
     return { ok: true };
   }, []);
-  const sendTurn = useCallback(async (text, opts) => {
+  const sendResolvedTurn = useCallback(async (text, attributes, retryOfTurnId) => {
     const trimmed = text.trim();
     const sender = turnSenderRef.current;
     if (!sender || !trimmed) return;
     const turnId = newTurnId();
-    lastTurnRef.current = { text: trimmed, opts, id: turnId, sentAt: Date.now() };
+    const outgoing = { ...attributes, [RTA_TURN_ID_ATTR]: turnId };
+    if (retryOfTurnId) outgoing[RTA_RETRY_OF_TURN_ID_ATTR] = retryOfTurnId;
+    lastTurnRef.current = { text: trimmed, attributes: { ...outgoing }, id: turnId, sentAt: Date.now() };
     lifecycle.markActivity();
-    const attributes = opts?.instructions ? { [RTA_TURN_INSTRUCTIONS_ATTR]: opts.instructions } : void 0;
-    await sender(trimmed, attributes ? { attributes } : void 0);
+    await sender(trimmed, { attributes: outgoing });
   }, [lifecycle, newTurnId]);
+  const sendInput = useCallback(async (text, opts, adapterSource) => {
+    const turnSource = opts?.inputSource;
+    validateInputSource(turnSource);
+    const declaredSource = turnSource ?? adapterSource;
+    const attributes = {
+      [RTA_INPUT_SOURCE_VERSION_ATTR]: "1",
+      [RTA_OBSERVED_INPUT_SOURCE_ATTR]: "text"
+    };
+    if (declaredSource !== void 0) {
+      attributes[RTA_DECLARED_INPUT_SOURCE_ATTR] = declaredSource;
+      attributes[RTA_INPUT_SOURCE_DECLARATION_SCOPE_ATTR] = turnSource !== void 0 ? "turn" : "adapter";
+    }
+    if (opts?.instructions) attributes[RTA_TURN_INSTRUCTIONS_ATTR] = opts.instructions;
+    await sendResolvedTurn(text, attributes);
+  }, [sendResolvedTurn]);
+  const sendTurn = useCallback((text, opts) => sendInput(text, opts), [sendInput]);
+  const createTranscriptSender = useCallback((opts) => {
+    const source = opts?.inputSource;
+    validateInputSource(source);
+    const boundSource = source ?? "client_stt";
+    return (text, turnOpts) => sendInput(text, turnOpts, boundSource);
+  }, [sendInput]);
   const retryTurn = useCallback(() => {
     const last = lastTurnRef.current;
     if (!last) return;
-    void sendTurn(last.text, last.opts);
-  }, [sendTurn]);
+    void sendResolvedTurn(last.text, last.attributes, last.id).catch(() => void 0);
+  }, [sendResolvedTurn]);
   const end = useCallback((reason) => {
     if (reason) lastLabeledEndReasonRef.current = reason;
+    lastTurnRef.current = null;
     requestGracefulClose();
     lifecycle.reset();
   }, [lifecycle, requestGracefulClose]);
@@ -3723,6 +3769,7 @@ function useRealtimeSession(input) {
       requestGracefulClose,
       extend,
       sendTurn,
+      createTranscriptSender,
       retryTurn,
       end,
       behavior,
@@ -3745,6 +3792,7 @@ function useRealtimeSession(input) {
       requestGracefulClose,
       extend,
       sendTurn,
+      createTranscriptSender,
       retryTurn,
       end,
       behavior,
@@ -3921,4 +3969,224 @@ function createProxyClient(options) {
   };
 }
 
-export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_AVATAR_UNSTABLE_STALL_MS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, NETWORK_QUALITY_POLICY, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarCamera, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+// ../browser/src/recording-playback.ts
+function recordingTimeline(recordings) {
+  if (new Set(recordings.map((recording) => recording.sessionId)).size > 1) throw new Error("Recordings belong to different sessions");
+  if (new Set(recordings.map((recording) => recording.recordingId)).size !== recordings.length) throw new Error("Duplicate recording assets");
+  const participants = recordings.filter((recording) => recording.participant && recording.status === "ready");
+  if (new Set(participants.map((recording) => recording.participant?.role)).size !== participants.length) throw new Error("Duplicate participant recordings");
+  const entries = participants.map((recording) => {
+    if (recording.status !== "ready" || !recording.mediaStartedAt || !recording.mediaEndedAt || recording.durationMs === null) {
+      throw new Error("Recording media timing is unavailable");
+    }
+    const start = Date.parse(recording.mediaStartedAt);
+    const end = Math.min(Date.parse(recording.mediaEndedAt), start + recording.durationMs);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) throw new Error("Recording media timing is invalid");
+    return { recording, start, end };
+  });
+  if (!entries.length) return null;
+  const originMs = Math.min(...entries.map((entry) => entry.start));
+  return {
+    originMs,
+    durationMs: Math.max(...entries.map((entry) => entry.end)) - originMs,
+    entries: entries.map(({ recording, start, end }) => ({ recording, startMs: start - originMs, endMs: end - originMs }))
+  };
+}
+function recordingPositions(timeline, positionMs) {
+  return timeline.entries.map((entry) => ({
+    recordingId: entry.recording.recordingId,
+    active: positionMs >= entry.startMs && positionMs < entry.endMs,
+    timeSeconds: Math.max(0, Math.min(positionMs, entry.endMs) - entry.startMs) / 1e3
+  }));
+}
+function exhausted(element, seconds) {
+  return Number.isFinite(element.duration) && seconds >= element.duration || element.ended && seconds >= element.currentTime;
+}
+function RecordingPlayer({ assets, className }) {
+  const timeline = useMemo(() => {
+    try {
+      return recordingTimeline(assets.map((asset) => asset.recording));
+    } catch {
+      return null;
+    }
+  }, [assets]);
+  const media = useRef(/* @__PURE__ */ new Map());
+  const position = useRef(0);
+  const anchor = useRef(null);
+  const [displayPosition, setDisplayPosition] = useState(0);
+  const [playing, setPlaying] = useState(false);
+  const [buffering, setBuffering] = useState(false);
+  const [error, setError] = useState("");
+  const sourceKey = assets.map((asset) => `${asset.recording.recordingId}:${asset.url}`).join("|");
+  useEffect(() => {
+    if (!timeline) return;
+    const sessionId = timeline.entries[0].recording.sessionId;
+    if (anchor.current?.sessionId === sessionId) {
+      position.current = Math.min(timeline.durationMs, Math.max(0, position.current + anchor.current.originMs - timeline.originMs));
+    } else if (anchor.current) {
+      position.current = 0;
+      setPlaying(false);
+    }
+    anchor.current = { sessionId, originMs: timeline.originMs };
+    setDisplayPosition(position.current);
+    let cancelled = false;
+    let frame = 0;
+    let last = performance.now();
+    let painted = last;
+    const starting = /* @__PURE__ */ new Set();
+    const stopMedia = () => {
+      for (const element of media.current.values()) element.pause();
+    };
+    const fail = () => {
+      if (cancelled) return;
+      stopMedia();
+      setPlaying(false);
+      setError("Playback is unavailable. Refresh access and try again.");
+    };
+    const update = (now) => {
+      if (cancelled) return;
+      const proposed = Math.min(timeline.durationMs, position.current + (playing ? now - last : 0));
+      last = now;
+      const states = recordingPositions(timeline, proposed);
+      const waiting = playing && states.some((state) => {
+        const element = media.current.get(state.recordingId);
+        return state.active && (!element || !exhausted(element, state.timeSeconds) && (element.readyState < 2 || element.seeking));
+      });
+      setBuffering(waiting);
+      if (!waiting) position.current = proposed;
+      for (const state of recordingPositions(timeline, position.current)) {
+        const element = media.current.get(state.recordingId);
+        if (!element) continue;
+        if (!state.active || exhausted(element, state.timeSeconds)) {
+          element.pause();
+          continue;
+        }
+        if (element.readyState >= 1 && Math.abs(element.currentTime - state.timeSeconds) > 0.08) {
+          element.currentTime = state.timeSeconds;
+        }
+        if (!playing || waiting) {
+          element.pause();
+          continue;
+        }
+        if (element.paused && !starting.has(state.recordingId)) {
+          starting.add(state.recordingId);
+          void element.play().catch((cause) => {
+            if (!(cause instanceof Error && cause.name === "AbortError")) fail();
+          }).finally(() => {
+            starting.delete(state.recordingId);
+          });
+        }
+      }
+      if (now - painted >= 100 || !playing || position.current >= timeline.durationMs) {
+        setDisplayPosition(position.current);
+        painted = now;
+      }
+      if (position.current >= timeline.durationMs) {
+        stopMedia();
+        setPlaying(false);
+      }
+      frame = requestAnimationFrame(update);
+    };
+    if (playing) frame = requestAnimationFrame(update);
+    else {
+      stopMedia();
+      setBuffering(false);
+    }
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+      stopMedia();
+    };
+  }, [timeline, playing, sourceKey]);
+  const activeIds = new Set(timeline ? recordingPositions(timeline, displayPosition).filter((state) => state.active).map((state) => state.recordingId) : []);
+  const seek = (value) => {
+    position.current = value;
+    setDisplayPosition(value);
+    if (timeline) for (const state of recordingPositions(timeline, value)) {
+      const element = media.current.get(state.recordingId);
+      if (!element) continue;
+      if (element.readyState >= 1) element.currentTime = state.timeSeconds;
+      if (!state.active) element.pause();
+    }
+  };
+  const toggle = () => {
+    setError("");
+    if (playing) {
+      setPlaying(false);
+      return;
+    }
+    if (!timeline) return;
+    if (position.current >= timeline.durationMs) seek(0);
+    for (const state of recordingPositions(timeline, position.current)) {
+      const element = media.current.get(state.recordingId);
+      if (state.active && element && !exhausted(element, state.timeSeconds)) {
+        if (element.readyState >= 1) element.currentTime = state.timeSeconds;
+        void element.play().catch((cause) => {
+          if (cause instanceof Error && cause.name === "AbortError") return;
+          for (const current of media.current.values()) current.pause();
+          setPlaying(false);
+          setError("Your browser could not play this recording. Try again or download the original.");
+        });
+      }
+    }
+    setPlaying(true);
+  };
+  return /* @__PURE__ */ jsxs("div", { className, children: [
+    /* @__PURE__ */ jsx("div", { style: { display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 240px), 1fr))", gap: 12 }, children: assets.map(({ recording, url }) => {
+      if (!recording.participant) return null;
+      const label = recording.participant.role === "user" ? "User" : "Character";
+      const ref = (element) => {
+        if (element) media.current.set(recording.recordingId, element);
+        else media.current.delete(recording.recordingId);
+      };
+      const onError = () => {
+        for (const current of media.current.values()) current.pause();
+        setPlaying(false);
+        setError("A recording could not load. Refresh access and try again.");
+      };
+      return recording.mode !== "audio" ? /* @__PURE__ */ jsxs("figure", { hidden: !activeIds.has(recording.recordingId), style: { margin: 0 }, children: [
+        /* @__PURE__ */ jsx("figcaption", { children: label }),
+        /* @__PURE__ */ jsx(
+          "video",
+          {
+            ref,
+            src: url,
+            playsInline: true,
+            preload: "auto",
+            onError,
+            hidden: !activeIds.has(recording.recordingId),
+            style: { width: "100%", maxHeight: 360, objectFit: "contain" }
+          }
+        ),
+        !activeIds.has(recording.recordingId) ? /* @__PURE__ */ jsx("p", { children: "No recording at this time." }) : null
+      ] }, recording.recordingId) : /* @__PURE__ */ jsx("audio", { ref, src: url, preload: "auto", onError, "aria-label": `${label} audio` }, recording.recordingId);
+    }) }),
+    /* @__PURE__ */ jsxs("div", { style: { display: "flex", alignItems: "center", gap: 12 }, children: [
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: toggle, disabled: !timeline, style: { minHeight: 44, minWidth: 44 }, children: playing ? "Pause" : "Play" }),
+      /* @__PURE__ */ jsx(
+        "input",
+        {
+          type: "range",
+          "aria-label": "Call playback position",
+          min: 0,
+          max: timeline?.durationMs ?? 0,
+          step: 100,
+          value: displayPosition,
+          "aria-valuetext": `${Math.floor(displayPosition / 1e3)} seconds`,
+          disabled: !timeline,
+          onChange: (event) => seek(Number(event.currentTarget.value)),
+          style: { minHeight: 44, flex: 1 }
+        }
+      ),
+      /* @__PURE__ */ jsxs("span", { children: [
+        Math.floor(displayPosition / 1e3),
+        " / ",
+        Math.ceil((timeline?.durationMs ?? 0) / 1e3),
+        " s"
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx("p", { role: "status", children: error || (!timeline ? "Media timing is unavailable. Individual recordings can still be downloaded." : buffering ? "Buffering\u2026" : "") })
+  ] });
+}
+
+export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_AVATAR_UNSTABLE_STALL_MS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, NETWORK_QUALITY_POLICY, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, RecordingPlayer, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarCamera, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/recording-DjswTx5B.d.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+
+declare const recordingModeSchema: z.ZodEnum<{
+    audio: "audio";
+    video: "video";
+    audio_video: "audio_video";
+    off: "off";
+    participants: "participants";
+}>;
+type RecordingMode = z.infer<typeof recordingModeSchema>;
+declare const recordingArtifactStatusSchema: z.ZodEnum<{
+    ready: "ready";
+    pending: "pending";
+    recording: "recording";
+    processing: "processing";
+    failed: "failed";
+    expired: "expired";
+}>;
+type RecordingArtifactStatus = z.infer<typeof recordingArtifactStatusSchema>;
+declare const recordingParticipantSchema: z.ZodObject<{
+    participantIdentity: z.ZodString;
+    role: z.ZodEnum<{
+        user: "user";
+        avatar: "avatar";
+    }>;
+}, z.core.$strict>;
+type RecordingParticipant = z.infer<typeof recordingParticipantSchema>;
+declare const recordingArtifactSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    sessionId: z.ZodString;
+    recordingId: z.ZodString;
+    mode: z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+        audio_video: "audio_video";
+    }>;
+    createdAt: z.ZodString;
+    retainedUntil: z.ZodString;
+    participant: z.ZodOptional<z.ZodObject<{
+        participantIdentity: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            avatar: "avatar";
+        }>;
+    }, z.core.$strict>>;
+    mediaStartedAt: z.ZodOptional<z.ZodString>;
+    mediaEndedAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        recording: "recording";
+        processing: "processing";
+        expired: "expired";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    sessionId: z.ZodString;
+    recordingId: z.ZodString;
+    mode: z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+        audio_video: "audio_video";
+    }>;
+    createdAt: z.ZodString;
+    retainedUntil: z.ZodString;
+    participant: z.ZodOptional<z.ZodObject<{
+        participantIdentity: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            avatar: "avatar";
+        }>;
+    }, z.core.$strict>>;
+    mediaStartedAt: z.ZodOptional<z.ZodString>;
+    mediaEndedAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodLiteral<"ready">;
+    mediaType: z.ZodEnum<{
+        "audio/mp4": "audio/mp4";
+        "video/mp4": "video/mp4";
+    }>;
+    sizeBytes: z.ZodNumber;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    sessionId: z.ZodString;
+    recordingId: z.ZodString;
+    mode: z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+        audio_video: "audio_video";
+    }>;
+    createdAt: z.ZodString;
+    retainedUntil: z.ZodString;
+    participant: z.ZodOptional<z.ZodObject<{
+        participantIdentity: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            avatar: "avatar";
+        }>;
+    }, z.core.$strict>>;
+    mediaStartedAt: z.ZodOptional<z.ZodString>;
+    mediaEndedAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodLiteral<"failed">;
+    errorCode: z.ZodEnum<{
+        recording_failed: "recording_failed";
+        recording_unavailable: "recording_unavailable";
+    }>;
+}, z.core.$strict>], "status">;
+type RecordingArtifact = z.infer<typeof recordingArtifactSchema>;
+declare const listRecordingsQuerySchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ListRecordingsQuery = Partial<z.infer<typeof listRecordingsQuerySchema>>;
+declare const listRecordingsResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        sessionId: z.ZodString;
+        recordingId: z.ZodString;
+        mode: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+            audio_video: "audio_video";
+        }>;
+        createdAt: z.ZodString;
+        retainedUntil: z.ZodString;
+        participant: z.ZodOptional<z.ZodObject<{
+            participantIdentity: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                avatar: "avatar";
+            }>;
+        }, z.core.$strict>>;
+        mediaStartedAt: z.ZodOptional<z.ZodString>;
+        mediaEndedAt: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            pending: "pending";
+            recording: "recording";
+            processing: "processing";
+            expired: "expired";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        sessionId: z.ZodString;
+        recordingId: z.ZodString;
+        mode: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+            audio_video: "audio_video";
+        }>;
+        createdAt: z.ZodString;
+        retainedUntil: z.ZodString;
+        participant: z.ZodOptional<z.ZodObject<{
+            participantIdentity: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                avatar: "avatar";
+            }>;
+        }, z.core.$strict>>;
+        mediaStartedAt: z.ZodOptional<z.ZodString>;
+        mediaEndedAt: z.ZodOptional<z.ZodString>;
+        status: z.ZodLiteral<"ready">;
+        mediaType: z.ZodEnum<{
+            "audio/mp4": "audio/mp4";
+            "video/mp4": "video/mp4";
+        }>;
+        sizeBytes: z.ZodNumber;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        sessionId: z.ZodString;
+        recordingId: z.ZodString;
+        mode: z.ZodEnum<{
+            audio: "audio";
+            video: "video";
+            audio_video: "audio_video";
+        }>;
+        createdAt: z.ZodString;
+        retainedUntil: z.ZodString;
+        participant: z.ZodOptional<z.ZodObject<{
+            participantIdentity: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                avatar: "avatar";
+            }>;
+        }, z.core.$strict>>;
+        mediaStartedAt: z.ZodOptional<z.ZodString>;
+        mediaEndedAt: z.ZodOptional<z.ZodString>;
+        status: z.ZodLiteral<"failed">;
+        errorCode: z.ZodEnum<{
+            recording_failed: "recording_failed";
+            recording_unavailable: "recording_unavailable";
+        }>;
+    }, z.core.$strict>], "status">>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+type ListRecordingsResponse = z.infer<typeof listRecordingsResponseSchema>;
+declare const recordingAccessResponseSchema: z.ZodObject<{
+    recordingId: z.ZodString;
+    url: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strict>;
+type RecordingAccessResponse = z.infer<typeof recordingAccessResponseSchema>;
+
+export { type ListRecordingsQuery as L, type RecordingArtifact as R, type ListRecordingsResponse as a, type RecordingAccessResponse as b, type RecordingArtifactStatus as c, type RecordingMode as d, type RecordingParticipant as e, listRecordingsResponseSchema as f, recordingArtifactSchema as g, recordingArtifactStatusSchema as h, recordingModeSchema as i, recordingParticipantSchema as j, listRecordingsQuerySchema as l, recordingAccessResponseSchema as r };