realtime-avatar 0.5.0 → 0.5.2

package/dist/react-native.js

@@ -448,6 +448,124 @@ function stableStringify(value) {
   return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
 }
 
+// ../client/src/react/adaptive-playout.ts
+var DEFAULTS = {
+  floorSeconds: 0.15,
+  ceilingSeconds: 0.5,
+  jitterGain: 4,
+  lossGain: 5,
+  growAlpha: 0.6,
+  shrinkAlpha: 0.08,
+  hysteresisSeconds: 0.05
+};
+var AdaptivePlayoutController = class {
+  opts;
+  smoothed;
+  applied;
+  constructor(options = {}) {
+    this.opts = { ...DEFAULTS, ...options };
+    this.smoothed = this.opts.ceilingSeconds;
+    this.applied = this.opts.ceilingSeconds;
+  }
+  /** The currently applied depth (what the receivers were last hinted to). */
+  get appliedSeconds() {
+    return this.applied;
+  }
+  update(sample) {
+    const { floorSeconds, ceilingSeconds, jitterGain, lossGain } = this.opts;
+    const jitter = Number.isFinite(sample.jitterSeconds) ? Math.max(0, sample.jitterSeconds) : 0;
+    const loss = Number.isFinite(sample.lossFraction) ? Math.min(1, Math.max(0, sample.lossFraction)) : 0;
+    const demand = Math.min(
+      ceilingSeconds,
+      Math.max(floorSeconds, floorSeconds + jitterGain * jitter + lossGain * loss)
+    );
+    const alpha = demand > this.smoothed ? this.opts.growAlpha : this.opts.shrinkAlpha;
+    this.smoothed += alpha * (demand - this.smoothed);
+    const hysteresis = this.opts.hysteresisSeconds;
+    const clamped = Math.min(ceilingSeconds, Math.max(floorSeconds, this.smoothed));
+    const target = clamped - floorSeconds <= hysteresis ? floorSeconds : ceilingSeconds - clamped <= hysteresis ? ceilingSeconds : clamped;
+    if (target === this.applied) return { targetSeconds: this.applied, changed: false };
+    const atBound = target === floorSeconds || target === ceilingSeconds;
+    if (!atBound && Math.abs(target - this.applied) <= hysteresis) {
+      return { targetSeconds: this.applied, changed: false };
+    }
+    this.applied = target;
+    return { targetSeconds: this.applied, changed: true };
+  }
+};
+function readInboundRtp(reports, previous) {
+  for (const report of reports) {
+    if (report["type"] !== "inbound-rtp") continue;
+    const jitterSeconds = typeof report["jitter"] === "number" ? report["jitter"] : 0;
+    const packetsLost = typeof report["packetsLost"] === "number" ? report["packetsLost"] : 0;
+    const packetsReceived = typeof report["packetsReceived"] === "number" ? report["packetsReceived"] : 0;
+    const dLost = Math.max(0, packetsLost - (previous?.packetsLost ?? packetsLost));
+    const dReceived = Math.max(0, packetsReceived - (previous?.packetsReceived ?? packetsReceived));
+    const denominator = dLost + dReceived;
+    return {
+      sample: {
+        jitterSeconds,
+        lossFraction: denominator > 0 ? dLost / denominator : 0
+      },
+      cursor: { packetsLost, packetsReceived }
+    };
+  }
+  return void 0;
+}
+
+// ../client/src/react/use-adaptive-playout.ts
+function useAvatarAdaptivePlayoutDelay(videoTrack, audioTrack, enabled = false, options) {
+  const ceiling = options?.ceilingSeconds ?? DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS;
+  const [appliedSeconds, setAppliedSeconds] = useState(ceiling);
+  const videoMediaTrack = videoTrack?.publication?.track;
+  const audioMediaTrack = audioTrack?.publication?.track;
+  useEffect(() => {
+    if (!enabled || !videoMediaTrack && !audioMediaTrack) return;
+    const receivers = [videoMediaTrack, audioMediaTrack].map((t) => t?.receiver).filter(
+      (r) => typeof r?.getStats === "function"
+    );
+    if (receivers.length === 0) return;
+    const controller = new AdaptivePlayoutController(options);
+    const cursors = /* @__PURE__ */ new Map();
+    let closed = false;
+    let inFlight = false;
+    const tick = async () => {
+      if (closed || inFlight) return;
+      inFlight = true;
+      try {
+        let worst;
+        for (let i = 0; i < receivers.length; i++) {
+          const stats = await receivers[i].getStats();
+          if (closed || typeof stats?.values !== "function") continue;
+          const reading = readInboundRtp(stats.values(), cursors.get(i));
+          if (!reading) continue;
+          cursors.set(i, reading.cursor);
+          worst = {
+            jitterSeconds: Math.max(worst?.jitterSeconds ?? 0, reading.sample.jitterSeconds),
+            lossFraction: Math.max(worst?.lossFraction ?? 0, reading.sample.lossFraction)
+          };
+        }
+        if (closed || !worst) return;
+        const decision = controller.update(worst);
+        if (decision.changed) {
+          applyAvatarPlayoutDelay(videoMediaTrack, audioMediaTrack, decision.targetSeconds);
+          setAppliedSeconds(decision.targetSeconds);
+        }
+      } catch {
+      } finally {
+        inFlight = false;
+      }
+    };
+    const interval = setInterval(() => void tick(), 1e3);
+    return () => {
+      closed = true;
+      clearInterval(interval);
+      setAppliedSeconds(ceiling);
+    };
+  }, [enabled, videoMediaTrack, audioMediaTrack, options, ceiling]);
+  return appliedSeconds;
+}
+
 // ../client/src/react/quality-governor.ts
 var DEFAULT_GOVERNOR_CONFIG = {
   openingCap: "low",
@@ -778,10 +896,12 @@ function AvatarVideoSurface(props) {
     style,
     children,
     showLiveBadge = true,
+    adaptivePlayout = false,
     testID
   } = props;
   const { videoTrack, audioTrack } = useVoiceAssistant();
   useAvatarPlayoutDelay(videoTrack, audioTrack);
+  useAvatarAdaptivePlayoutDelay(videoTrack, audioTrack, adaptivePlayout);
   const connectionState = useConnectionState();
   const connected = connectionState === ConnectionState.Connected;
   const trackProducing = useLiveTrackProducing(
@@ -2273,4 +2393,4 @@ function createProxyClient(options) {
   };
 }
 
-export { AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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, RECONNECT_BACKOFF_MS, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, isNativeLiveTrackSubscribed, knownBehaviorStates, mapTurnState, sessionBehaviorSchema, sessionClipSchema, splitCallTranscript, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useLiveTrackProducing, useMicLease, useRealtimeAvatarAudioSession, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+export { AdaptivePlayoutController, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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, RECONNECT_BACKOFF_MS, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, isNativeLiveTrackSubscribed, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useLiveTrackProducing, useMicLease, useRealtimeAvatarAudioSession, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { A as AvatarSessionClient, a as AvatarVideoFit } from './proxy-client-Dm-O0jNn.js';
-export { b as ApproachingEndEvent, c as ApproachingEndReason, d as AvatarVideoSurface, e as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, f as CallTranscriptSegment, g as CartesiaTtsModel, h as ClipResult, i as ClosingTurnResult, j as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, k as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, l as DEFAULT_CREDITS_LOW_LEAD_SECONDS, m as DEFAULT_GOVERNOR_CONFIG, n as DEFAULT_GRACE_CEILING_SECONDS, o as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, p as DEFAULT_IDLE_SECONDS, q as DEFAULT_IDLE_WARN_LEAD_SECONDS, r as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, s as EndedEvent, t as ExtendResult, F as FishTtsModel, u as FreezeReadingFn, G as Governor, v as GovernorAction, w as GovernorConfig, x as GovernorSignal, y as GovernorState, z as GraceWindowClosedEvent, H as GraceWindowOpenEvent, I as GraceWindowState, J as IdleWarningEvent, K as KnownBehaviorState, L as LLMProvider, M as LLMSelection, N as LiveKitAvatarGrantState, O as LiveKitAvatarGrantStatus, P as LiveKitCapacityState, Q as LiveKitConnectionStatus, R as LiveKitSessionRequest, S as LiveKitSessionStartResult, T as LivePlaybackKeeper, U as MAX_RECONNECT_ATTEMPTS, V as MAX_SESSION_INSTRUCTIONS_CHARS, W as MIC_LEASE_ENDED_TIMEOUT_MS, X as MicLease, Y as PlayableVideoElement, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, a0 as RealtimeAvatarCapacityError, a1 as RealtimeAvatarLiveKitRoom, a2 as RealtimeAvatarLiveKitRoomProps, a3 as RealtimeAvatarRequestOptions, a4 as RealtimeSessionApi, a5 as RealtimeSessionMedia, a6 as RealtimeSessionRoomSinks, a7 as ReconnectPolicy, a8 as ReconnectingEvent, a9 as RecoveryState, aa as RetryStep, ab as SessionBehavior, ac as SessionClip, ad as SessionClocks, ae as SessionEndReason, af as SessionLifecycleApi, ag as SessionLifecyclePhase, ah as SessionLifecyclePhaseKind, ai as SessionLifecycleRoomBridge, aj as SessionLifecycleRoomBridgeProps, ak as SurfaceLayers, al as TurnState, am as TurnTimeoutEvent, an as UseAvatarQualityGovernorInput, ao as UseLiveKitAvatarGrantInput, ap as UseRealtimeSessionInput, aq as UseSessionLifecycleInput, ar as VoiceSpec, as as VoiceSpecInput, at as capacityErrorFromBusy, au as capacityStateFromGrant, av as createProxyClient, aw as knownBehaviorStates, ax as mapTurnState, ay as sessionBehaviorSchema, az as sessionClipSchema, aA as shouldReplayPendingTurn, aB as splitCallTranscript, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-Dm-O0jNn.js';
+import { A as AvatarSessionClient, a as AvatarVideoFit } from './proxy-client-BIaUo0az.js';
+export { b as AdaptivePlayoutController, c as AdaptivePlayoutDecision, d as AdaptivePlayoutOptions, e as AdaptivePlayoutSample, f as ApproachingEndEvent, g as ApproachingEndReason, h as AvatarVideoSurface, i as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, j as CallTranscriptSegment, k as CartesiaTtsModel, l as ClipResult, m as ClosingTurnResult, n as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, o as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, p as DEFAULT_CREDITS_LOW_LEAD_SECONDS, q as DEFAULT_GOVERNOR_CONFIG, r as DEFAULT_GRACE_CEILING_SECONDS, s as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, t as DEFAULT_IDLE_SECONDS, u as DEFAULT_IDLE_WARN_LEAD_SECONDS, v as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, w as EndedEvent, x as ExtendResult, F as FishTtsModel, y as FreezeReadingFn, G as Governor, z as GovernorAction, H as GovernorConfig, I as GovernorSignal, J as GovernorState, K as GraceWindowClosedEvent, L 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, Z as LivePlaybackKeeper, _ as MAX_RECONNECT_ATTEMPTS, $ as MAX_SESSION_INSTRUCTIONS_CHARS, a0 as MIC_LEASE_ENDED_TIMEOUT_MS, a1 as MicLease, a2 as PlayableVideoElement, a3 as ProxyClientOptions, a4 as QualityCap, a5 as RECONNECT_BACKOFF_MS, a6 as RealtimeAvatarCapacityError, a7 as RealtimeAvatarLiveKitRoom, a8 as RealtimeAvatarLiveKitRoomProps, a9 as RealtimeAvatarRequestOptions, aa as RealtimeSessionApi, ab as RealtimeSessionMedia, ac as RealtimeSessionRoomSinks, ad as ReconnectPolicy, ae as ReconnectingEvent, af as RecoveryState, ag as RetryStep, ah as SessionBehavior, ai as SessionClip, aj as SessionClocks, ak as SessionEndReason, al as SessionLifecycleApi, am as SessionLifecyclePhase, an as SessionLifecyclePhaseKind, ao as SessionLifecycleRoomBridge, ap as SessionLifecycleRoomBridgeProps, aq as SurfaceLayers, ar as TurnState, as as TurnTimeoutEvent, at as UseAvatarQualityGovernorInput, au as UseLiveKitAvatarGrantInput, av as UseRealtimeSessionInput, aw as UseSessionLifecycleInput, ax as VoiceSpec, ay as VoiceSpecInput, az as capacityErrorFromBusy, aA as capacityStateFromGrant, aB as createProxyClient, aC as knownBehaviorStates, aD as mapTurnState, aE as readInboundRtp, aF as sessionBehaviorSchema, aG as sessionClipSchema, aH as shouldReplayPendingTurn, aI as splitCallTranscript, aJ as useAvatarAdaptivePlayoutDelay, aK as useAvatarPlayoutDelay, aL as useAvatarQualityGovernor, aM as useCallTranscript, aN as useLiveKitAvatarGrant, aO as useMicLease, aP as useRealtimeSession, aQ as useReleaseMicLeaseOnTrackEnded, aR as useSessionLifecycle } from './proxy-client-BIaUo0az.js';
 import '@livekit/components-react';
 import 'livekit-client';
 import 'zod';

package/dist/react.js

@@ -435,6 +435,124 @@ function stableStringify(value) {
   return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
 }
 
+// ../client/src/react/adaptive-playout.ts
+var DEFAULTS = {
+  floorSeconds: 0.15,
+  ceilingSeconds: 0.5,
+  jitterGain: 4,
+  lossGain: 5,
+  growAlpha: 0.6,
+  shrinkAlpha: 0.08,
+  hysteresisSeconds: 0.05
+};
+var AdaptivePlayoutController = class {
+  opts;
+  smoothed;
+  applied;
+  constructor(options = {}) {
+    this.opts = { ...DEFAULTS, ...options };
+    this.smoothed = this.opts.ceilingSeconds;
+    this.applied = this.opts.ceilingSeconds;
+  }
+  /** The currently applied depth (what the receivers were last hinted to). */
+  get appliedSeconds() {
+    return this.applied;
+  }
+  update(sample) {
+    const { floorSeconds, ceilingSeconds, jitterGain, lossGain } = this.opts;
+    const jitter = Number.isFinite(sample.jitterSeconds) ? Math.max(0, sample.jitterSeconds) : 0;
+    const loss = Number.isFinite(sample.lossFraction) ? Math.min(1, Math.max(0, sample.lossFraction)) : 0;
+    const demand = Math.min(
+      ceilingSeconds,
+      Math.max(floorSeconds, floorSeconds + jitterGain * jitter + lossGain * loss)
+    );
+    const alpha = demand > this.smoothed ? this.opts.growAlpha : this.opts.shrinkAlpha;
+    this.smoothed += alpha * (demand - this.smoothed);
+    const hysteresis = this.opts.hysteresisSeconds;
+    const clamped = Math.min(ceilingSeconds, Math.max(floorSeconds, this.smoothed));
+    const target = clamped - floorSeconds <= hysteresis ? floorSeconds : ceilingSeconds - clamped <= hysteresis ? ceilingSeconds : clamped;
+    if (target === this.applied) return { targetSeconds: this.applied, changed: false };
+    const atBound = target === floorSeconds || target === ceilingSeconds;
+    if (!atBound && Math.abs(target - this.applied) <= hysteresis) {
+      return { targetSeconds: this.applied, changed: false };
+    }
+    this.applied = target;
+    return { targetSeconds: this.applied, changed: true };
+  }
+};
+function readInboundRtp(reports, previous) {
+  for (const report of reports) {
+    if (report["type"] !== "inbound-rtp") continue;
+    const jitterSeconds = typeof report["jitter"] === "number" ? report["jitter"] : 0;
+    const packetsLost = typeof report["packetsLost"] === "number" ? report["packetsLost"] : 0;
+    const packetsReceived = typeof report["packetsReceived"] === "number" ? report["packetsReceived"] : 0;
+    const dLost = Math.max(0, packetsLost - (previous?.packetsLost ?? packetsLost));
+    const dReceived = Math.max(0, packetsReceived - (previous?.packetsReceived ?? packetsReceived));
+    const denominator = dLost + dReceived;
+    return {
+      sample: {
+        jitterSeconds,
+        lossFraction: denominator > 0 ? dLost / denominator : 0
+      },
+      cursor: { packetsLost, packetsReceived }
+    };
+  }
+  return void 0;
+}
+
+// ../client/src/react/use-adaptive-playout.ts
+function useAvatarAdaptivePlayoutDelay(videoTrack, audioTrack, enabled = false, options) {
+  const ceiling = options?.ceilingSeconds ?? DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS;
+  const [appliedSeconds, setAppliedSeconds] = useState(ceiling);
+  const videoMediaTrack = videoTrack?.publication?.track;
+  const audioMediaTrack = audioTrack?.publication?.track;
+  useEffect(() => {
+    if (!enabled || !videoMediaTrack && !audioMediaTrack) return;
+    const receivers = [videoMediaTrack, audioMediaTrack].map((t) => t?.receiver).filter(
+      (r) => typeof r?.getStats === "function"
+    );
+    if (receivers.length === 0) return;
+    const controller = new AdaptivePlayoutController(options);
+    const cursors = /* @__PURE__ */ new Map();
+    let closed = false;
+    let inFlight = false;
+    const tick = async () => {
+      if (closed || inFlight) return;
+      inFlight = true;
+      try {
+        let worst;
+        for (let i = 0; i < receivers.length; i++) {
+          const stats = await receivers[i].getStats();
+          if (closed || typeof stats?.values !== "function") continue;
+          const reading = readInboundRtp(stats.values(), cursors.get(i));
+          if (!reading) continue;
+          cursors.set(i, reading.cursor);
+          worst = {
+            jitterSeconds: Math.max(worst?.jitterSeconds ?? 0, reading.sample.jitterSeconds),
+            lossFraction: Math.max(worst?.lossFraction ?? 0, reading.sample.lossFraction)
+          };
+        }
+        if (closed || !worst) return;
+        const decision = controller.update(worst);
+        if (decision.changed) {
+          applyAvatarPlayoutDelay(videoMediaTrack, audioMediaTrack, decision.targetSeconds);
+          setAppliedSeconds(decision.targetSeconds);
+        }
+      } catch {
+      } finally {
+        inFlight = false;
+      }
+    };
+    const interval = setInterval(() => void tick(), 1e3);
+    return () => {
+      closed = true;
+      clearInterval(interval);
+      setAppliedSeconds(ceiling);
+    };
+  }, [enabled, videoMediaTrack, audioMediaTrack, options, ceiling]);
+  return appliedSeconds;
+}
+
 // ../client/src/react/quality-governor.ts
 var DEFAULT_GOVERNOR_CONFIG = {
   openingCap: "low",
@@ -706,11 +824,23 @@ function AvatarVideoSurface(props) {
     className,
     style,
     children,
-    showLiveBadge = true
+    showLiveBadge = true,
+    adaptivePlayout = false,
+    onPlayoutDelayChange
   } = props;
   const testId = props["data-testid"];
   const { videoTrack, audioTrack } = useVoiceAssistant();
   useAvatarPlayoutDelay(videoTrack, audioTrack);
+  const playoutDelaySeconds = useAvatarAdaptivePlayoutDelay(
+    videoTrack,
+    audioTrack,
+    adaptivePlayout
+  );
+  const onPlayoutDelayChangeRef = useRef(onPlayoutDelayChange);
+  onPlayoutDelayChangeRef.current = onPlayoutDelayChange;
+  useEffect(() => {
+    onPlayoutDelayChangeRef.current?.(playoutDelaySeconds);
+  }, [playoutDelaySeconds]);
   const connectionState = useConnectionState();
   const connected = connectionState === ConnectionState.Connected;
   const trackProducing = useLiveTrackProducing(videoTrack);
@@ -2578,4 +2708,4 @@ function createProxyClient(options) {
   };
 }
 
-export { AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, 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, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/server.d.ts

@@ -1,2 +1,2 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, verifyTranscript } from './index.js';
-export { i as Asset, h as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, d as ClipDeclaration, f as ClipLibrary, o as ClipLibraryPlan, e as ClipLibraryUpdate, p as ClipSource, g as ClipSyncResult, q as ContextMessage, k as CreditBalance, E as EndCallOptions, r as EndCallReason, L as ListSessionsOptions, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, s as VideoState, t as isQueued } from './types-DLxz6uFE.js';
+export { i as Asset, h as AssetKind, A as Avatar, m as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, n as CallConnection, C as CallMode, a as CallPolicy, o as CallQueued, d as ClipDeclaration, f as ClipLibrary, p as ClipLibraryPlan, e as ClipLibraryUpdate, q as ClipSource, g as ClipSyncResult, r as ContextMessage, l as CreditBalance, E as EndCallOptions, s as EndCallReason, j as ListSessionsOptions, L as LoopRedirect, S as StartCallResult, T as TranscriptPayload, k as UsageSession, U as UsageSessionPage, V as VideoPolicy, t as VideoState, u as isQueued } from './types-BeGuvyra.js';

package/dist/server.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * Register a character from a looping clip you host.
    *
-   * Use a VIDEO source for anything that will be called live. An avatar built from a still
-   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
-   * track dimensions both look fine, only the pixels are wrong. Image sources are for
-   * offline lipsync renders.
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
    */
   async createAvatarFromVideo(input) {
     const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       metadata: input.metadata
     });
   }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
   async createAvatar(input) {
     const body = {
       displayName: input.displayName,
       sourceKind: input.sourceKind,
       sourceAssetId: input.sourceAssetId
     };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
     if (input.voice !== void 0) body.voice = input.voice;
     if (input.settings !== void 0) body.settings = input.settings;
     if (input.metadata !== void 0) body.metadata = input.metadata;
@@ -191,7 +225,14 @@ var RealtimeAvatar = class {
   async getAvatar(avatarId) {
     return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
   }
-  /** Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice. */
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
   async updateAvatar(avatarId, patch) {
     return toAvatar(
       await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
@@ -274,6 +315,94 @@ var RealtimeAvatar = class {
       )
     );
   }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
   /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
   async listClips(avatarId) {
     return this.#clipEnvelope(
@@ -475,7 +604,13 @@ function toAvatar(raw) {
     sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
     // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
     // and serving, and this says why the re-shoot did not take.
-    error: a.error ? String(a.error) : null
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
   };
 }
 function toAsset(raw) {

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-B45GgjrV.js';
-import './types-DLxz6uFE.js';
+import { P as ProxyConfig } from './types-CHrhuhYb.js';
+import './types-BeGuvyra.js';
 
 /**
  * TanStack Start. Mount at `routes/api/realtime-avatar/$.ts` — the trailing `$` is Start's