realtime-avatar 0.5.0 → 0.5.2

package/dist/index.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/nextjs.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';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.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/{proxy-client-Dm-O0jNn.d.ts → proxy-client-BIaUo0az.d.ts}

@@ -487,6 +487,28 @@ type AvatarVideoSurfaceProps = {
     children?: ReactNode;
     /** Surface a small "live · WxH" badge when the live layer is shown. Default true. */
     showLiveBadge?: boolean;
+    /**
+     * Reclaim the flat 0.5s de-jitter cushion on clean networks: a 1Hz closed loop
+     * over `getStats()` that descends toward a 150ms floor while jitter and loss stay
+     * low, and snaps back to 0.5s within a couple of ticks when either appears.
+     * Default **false** — the flat
+     * cushion is the shipped behavior and this is the opt-in that trades loss margin
+     * for up to ~350ms of felt reply latency. The loop always OPENS at the ceiling, so
+     * enabling it can never make the first frame later than it is today.
+     */
+    adaptivePlayout?: boolean;
+    /**
+     * Called with the receiver playout depth (SECONDS) whenever it changes — the flat
+     * {@link DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS} while `adaptivePlayout` is off, the live
+     * value while it is on.
+     *
+     * Read this if anything you render is timed against the avatar's VOICE: the media rides
+     * the receiver buffer and a side channel (captions, a transcript reveal, a lip-synced
+     * overlay) does not, so it has to be held by the same amount or it arrives early. While
+     * the cushion was a constant, consumers hard-coded it; once it moves, a hard-coded copy
+     * desyncs by up to the whole adaptive range. Fires on change only, not per frame.
+     */
+    onPlayoutDelayChange?: (seconds: number) => void;
     /** Test id for the box. */
     "data-testid"?: string;
 };
@@ -845,6 +867,130 @@ type RealtimeAvatarLiveKitRoomProps = Omit<LiveKitRoomProps, "serverUrl" | "toke
 declare function RealtimeAvatarLiveKitRoom(props: RealtimeAvatarLiveKitRoomProps): ReactElement;
 declare const capacityErrorFromBusy: (busy: CapacityBusyResponse) => RealtimeAvatarCapacityError;
 
+/**
+ * The adaptive playout-delay controller — the closed loop behind
+ * `useAvatarAdaptivePlayoutDelay`.
+ *
+ * The flat {@link DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS} cushion exists for loss
+ * robustness (measured at ~5% loss it takes the stream from ~11fps with
+ * multi-second freezes to a steady 25fps) — but it bills every viewer 0.5s of
+ * felt reply latency on every turn, clean network or not. This controller keeps
+ * the cushion where the network needs it and reclaims it where it doesn't:
+ *
+ *   target = clamp(floor + jitterGain·EWMA(jitter) + lossGain·EWMA(loss),
+ *                  floor, ceiling)
+ *
+ * with three deliberate asymmetries, each a lesson already paid for:
+ *
+ * 1. **It OPENS at the ceiling** (the incumbent 0.5s) and only ever descends in
+ *    steady state. The open-small-then-ramp variant shipped, failed twice (the
+ *    rVFC ramp trigger is throttled on an opacity:0-mounted element, stranding
+ *    the shallow buffer), and was removed in 2262e4c7b. This loop never opens
+ *    shallow and never depends on rVFC — its clock is a plain interval over
+ *    `RTCRtpReceiver.getStats()`.
+ * 2. **Grow fast, shrink slow.** A loss burst must deepen the buffer within a
+ *    couple of ticks (freezes are the cardinal sin); a clean stretch earns
+ *    latency back over tens of seconds. In the continuous-render model the
+ *    session is long, so there is plenty of steady state to reclaim in.
+ * 3. **Hysteresis.** The hint is only re-applied when the smoothed target moved
+ *    by more than `hysteresisSeconds` — a receiver being re-hinted every second
+ *    with ±5ms wiggle re-anchors its buffer for nothing.
+ *
+ * Pure by construction: no react, no livekit, no DOM — a plain state machine
+ * over numbers, imported directly by the node test runner. The hook that feeds
+ * it stats lives in `use-adaptive-playout.ts`.
+ */
+/** One tick's network observation, already reduced to the two axes that matter. */
+interface AdaptivePlayoutSample {
+    /** RTP jitter in SECONDS (`inbound-rtp.jitter`), worst of the avatar's receivers. */
+    jitterSeconds: number;
+    /** Fraction of packets lost over the tick (0..1), worst of the avatar's receivers. */
+    lossFraction: number;
+}
+interface AdaptivePlayoutOptions {
+    /** The clean-network resting depth. Default 0.15s — the design's floor. */
+    floorSeconds?: number;
+    /** The lossy-network depth AND the opening value. Default 0.5s (the incumbent flat cushion). */
+    ceilingSeconds?: number;
+    /** Seconds of buffer per second of RTP jitter. Default 4 (25ms jitter ⇒ +100ms). */
+    jitterGain?: number;
+    /** Seconds of buffer per unit loss fraction. Default 5 (5% loss ⇒ +250ms ⇒ near ceiling). */
+    lossGain?: number;
+    /** EWMA blend when the demand RISES. Default 0.6 — most of a burst lands in 2 ticks. */
+    growAlpha?: number;
+    /** EWMA blend when the demand FALLS. Default 0.08 — ~9-tick half-life, latency earned back slowly. */
+    shrinkAlpha?: number;
+    /** Minimum movement before the hint is re-applied. Default 0.05s (the design's 50ms). */
+    hysteresisSeconds?: number;
+}
+interface AdaptivePlayoutDecision {
+    /** The depth the receivers should sit at, seconds. Always within [floor, ceiling]. */
+    targetSeconds: number;
+    /** True when the caller should re-apply the hint (movement cleared the hysteresis). */
+    changed: boolean;
+}
+declare class AdaptivePlayoutController {
+    private readonly opts;
+    private smoothed;
+    private applied;
+    constructor(options?: AdaptivePlayoutOptions);
+    /** The currently applied depth (what the receivers were last hinted to). */
+    get appliedSeconds(): number;
+    update(sample: AdaptivePlayoutSample): AdaptivePlayoutDecision;
+}
+/**
+ * Cumulative counters from one receiver's previous `inbound-rtp` report, kept by
+ * the caller so loss can be computed as a PER-TICK delta (the stats counters are
+ * cumulative for the whole session — a session-long ratio would never recover
+ * from one bad patch).
+ */
+interface InboundRtpCursor {
+    packetsLost: number;
+    packetsReceived: number;
+}
+interface InboundRtpReading {
+    sample: AdaptivePlayoutSample;
+    cursor: InboundRtpCursor;
+}
+/**
+ * Reduce one receiver's `getStats()` report to this tick's {@link AdaptivePlayoutSample}.
+ * Takes the report as a plain iterable of stat dicts so tests need no RTCStatsReport.
+ * Returns undefined when the report carries no `inbound-rtp` entry (nothing decodable
+ * yet) — the caller should skip the tick rather than feed a fabricated zero.
+ *
+ * Counter resets (a receiver restart makes cumulative counters go BACKWARD) read as
+ * a zero-loss tick, never a negative one.
+ */
+declare function readInboundRtp(reports: Iterable<Record<string, unknown>>, previous?: InboundRtpCursor): InboundRtpReading | undefined;
+
+/**
+ * The adaptive counterpart to `useAvatarPlayoutDelay` — OPT-IN via `enabled`
+ * (default false ⇒ a complete no-op, the incumbent flat cushion untouched).
+ *
+ * When enabled it runs the {@link AdaptivePlayoutController} closed loop: a 1Hz
+ * `RTCRtpReceiver.getStats()` poll over BOTH avatar receivers, the worst
+ * jitter/loss of the pair feeding one shared target so audio and video stay on
+ * the SAME depth (lip-sync law — WebRTC pairs the streams to the larger of the
+ * two hints). The loop opens at the ceiling (the flat cushion already applied by
+ * `useAvatarPlayoutDelay`), descends toward the 150ms floor on clean paths, and
+ * snaps back up within a couple of ticks when jitter or loss appears.
+ *
+ * Degrades to the incumbent behavior wherever the substrate is missing: a track
+ * without `getStats` on its receiver, a stats report with no `inbound-rtp` yet,
+ * or a browser without the playout-delay hint all leave the flat cushion exactly
+ * as `useAvatarPlayoutDelay` set it.
+ *
+ * RETURNS THE APPLIED DEPTH IN SECONDS, and that return value is load-bearing rather
+ * than a convenience. Anything a consumer times against the avatar's voice — a caption
+ * reveal being the real case — has to be held by the SAME cushion, because the media is
+ * buffered and a side channel is not. While the cushion was a flat constant a consumer
+ * could hard-code it; the moment it moves, a hard-coded copy desyncs by up to the whole
+ * adaptive range. So the value comes back out of the hook, and stays equal to
+ * {@link DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS} whenever the loop is disabled or inert —
+ * a consumer can read it unconditionally.
+ */
+declare function useAvatarAdaptivePlayoutDelay(videoTrack: TrackReferenceOrPlaceholder | undefined, audioTrack: TrackReferenceOrPlaceholder | undefined, enabled?: boolean, options?: AdaptivePlayoutOptions): number;
+
 /**
  * Avatar nonverbal-behavior snapshot + its SSOT derivation.
  *
@@ -1473,4 +1619,4 @@ interface ProxyClientOptions {
 }
 declare function createProxyClient(options: ProxyClientOptions): AvatarSessionClient;
 
-export { RECONNECT_BACKOFF_MS as $, type AvatarSessionClient as A, type BehaviorSnapshot as B, type CallTranscript as C, DEFAULT_APPROACHING_END_LEAD_SECONDS as D, type EndReason as E, type FishTtsModel as F, type Governor as G, type GraceWindowOpenEvent as H, type GraceWindowState as I, type IdleWarningEvent as J, type KnownBehaviorState as K, type LLMProvider as L, type LLMSelection as M, type LiveKitAvatarGrantState as N, type LiveKitAvatarGrantStatus as O, type LiveKitCapacityState as P, type LiveKitConnectionStatus as Q, type LiveKitSessionRequest as R, type LiveKitSessionStartResult as S, type LivePlaybackKeeper as T, MAX_RECONNECT_ATTEMPTS as U, MAX_SESSION_INSTRUCTIONS_CHARS as V, MIC_LEASE_ENDED_TIMEOUT_MS as W, type MicLease as X, type PlayableVideoElement as Y, type ProxyClientOptions as Z, type QualityCap as _, type AvatarVideoFit as a, RealtimeAvatarCapacityError as a0, RealtimeAvatarLiveKitRoom as a1, type RealtimeAvatarLiveKitRoomProps as a2, type RealtimeAvatarRequestOptions as a3, type RealtimeSessionApi as a4, type RealtimeSessionMedia as a5, type RealtimeSessionRoomSinks as a6, type ReconnectPolicy as a7, type ReconnectingEvent as a8, type RecoveryState as a9, shouldReplayPendingTurn as aA, splitCallTranscript as aB, useAvatarPlayoutDelay as aC, useAvatarQualityGovernor as aD, useCallTranscript as aE, useLiveKitAvatarGrant as aF, useMicLease as aG, useRealtimeSession as aH, useReleaseMicLeaseOnTrackEnded as aI, useSessionLifecycle as aJ, type LiveKitSessionGrant as aK, isNativeLiveTrackSubscribed as aL, useLiveTrackProducing as aM, type RetryStep as aa, type SessionBehavior as ab, type SessionClip as ac, type SessionClocks as ad, type SessionEndReason as ae, type SessionLifecycleApi as af, type SessionLifecyclePhase as ag, type SessionLifecyclePhaseKind as ah, SessionLifecycleRoomBridge as ai, type SessionLifecycleRoomBridgeProps as aj, type SurfaceLayers as ak, type TurnState as al, type TurnTimeoutEvent as am, type UseAvatarQualityGovernorInput as an, type UseLiveKitAvatarGrantInput as ao, type UseRealtimeSessionInput as ap, type UseSessionLifecycleInput as aq, type VoiceSpec as ar, type VoiceSpecInput as as, capacityErrorFromBusy as at, capacityStateFromGrant as au, createProxyClient as av, knownBehaviorStates as aw, mapTurnState as ax, sessionBehaviorSchema as ay, sessionClipSchema as az, type ApproachingEndEvent as b, type ApproachingEndReason as c, AvatarVideoSurface as d, type AvatarVideoSurfaceProps as e, type CallTranscriptSegment as f, type CartesiaTtsModel as g, type ClipResult as h, type ClosingTurnResult as i, type CreditsLowEvent as j, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as k, DEFAULT_CREDITS_LOW_LEAD_SECONDS as l, DEFAULT_GOVERNOR_CONFIG as m, DEFAULT_GRACE_CEILING_SECONDS as n, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as o, DEFAULT_IDLE_SECONDS as p, DEFAULT_IDLE_WARN_LEAD_SECONDS as q, DEFAULT_TURN_TIMEOUT_SECONDS as r, type EndedEvent as s, type ExtendResult as t, type FreezeReadingFn as u, type GovernorAction as v, type GovernorConfig as w, type GovernorSignal as x, type GovernorState as y, type GraceWindowClosedEvent as z };
+export { MAX_SESSION_INSTRUCTIONS_CHARS as $, type AvatarSessionClient as A, type BehaviorSnapshot as B, type CallTranscript as C, DEFAULT_APPROACHING_END_LEAD_SECONDS as D, type EndReason as E, type FishTtsModel as F, type Governor as G, type GovernorConfig as H, type GovernorSignal as I, type GovernorState as J, type GraceWindowClosedEvent as K, type GraceWindowOpenEvent as L, type GraceWindowState as M, type IdleWarningEvent as N, type InboundRtpCursor as O, type InboundRtpReading as P, type KnownBehaviorState as Q, type LLMProvider as R, type LLMSelection as S, type LiveKitAvatarGrantState as T, type LiveKitAvatarGrantStatus as U, type LiveKitCapacityState as V, type LiveKitConnectionStatus as W, type LiveKitSessionRequest as X, type LiveKitSessionStartResult as Y, type LivePlaybackKeeper as Z, MAX_RECONNECT_ATTEMPTS as _, type AvatarVideoFit as a, MIC_LEASE_ENDED_TIMEOUT_MS as a0, type MicLease as a1, type PlayableVideoElement as a2, type ProxyClientOptions as a3, type QualityCap as a4, RECONNECT_BACKOFF_MS as a5, RealtimeAvatarCapacityError as a6, RealtimeAvatarLiveKitRoom as a7, type RealtimeAvatarLiveKitRoomProps as a8, type RealtimeAvatarRequestOptions as a9, capacityStateFromGrant as aA, createProxyClient as aB, knownBehaviorStates as aC, mapTurnState as aD, readInboundRtp as aE, sessionBehaviorSchema as aF, sessionClipSchema as aG, shouldReplayPendingTurn as aH, splitCallTranscript as aI, useAvatarAdaptivePlayoutDelay as aJ, useAvatarPlayoutDelay as aK, useAvatarQualityGovernor as aL, useCallTranscript as aM, useLiveKitAvatarGrant as aN, useMicLease as aO, useRealtimeSession as aP, useReleaseMicLeaseOnTrackEnded as aQ, useSessionLifecycle as aR, type LiveKitSessionGrant as aS, isNativeLiveTrackSubscribed as aT, useLiveTrackProducing as aU, type RealtimeSessionApi as aa, type RealtimeSessionMedia as ab, type RealtimeSessionRoomSinks as ac, type ReconnectPolicy as ad, type ReconnectingEvent as ae, type RecoveryState as af, type RetryStep as ag, type SessionBehavior as ah, type SessionClip as ai, type SessionClocks as aj, type SessionEndReason as ak, type SessionLifecycleApi as al, type SessionLifecyclePhase as am, type SessionLifecyclePhaseKind as an, SessionLifecycleRoomBridge as ao, type SessionLifecycleRoomBridgeProps as ap, type SurfaceLayers as aq, type TurnState as ar, type TurnTimeoutEvent as as, type UseAvatarQualityGovernorInput as at, type UseLiveKitAvatarGrantInput as au, type UseRealtimeSessionInput as av, type UseSessionLifecycleInput as aw, type VoiceSpec as ax, type VoiceSpecInput as ay, capacityErrorFromBusy as az, AdaptivePlayoutController as b, type AdaptivePlayoutDecision as c, type AdaptivePlayoutOptions as d, type AdaptivePlayoutSample as e, type ApproachingEndEvent as f, type ApproachingEndReason as g, AvatarVideoSurface as h, type AvatarVideoSurfaceProps as i, type CallTranscriptSegment as j, type CartesiaTtsModel as k, type ClipResult as l, type ClosingTurnResult as m, type CreditsLowEvent as n, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as o, DEFAULT_CREDITS_LOW_LEAD_SECONDS as p, DEFAULT_GOVERNOR_CONFIG as q, DEFAULT_GRACE_CEILING_SECONDS as r, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as s, DEFAULT_IDLE_SECONDS as t, DEFAULT_IDLE_WARN_LEAD_SECONDS as u, DEFAULT_TURN_TIMEOUT_SECONDS as v, type EndedEvent as w, type ExtendResult as x, type FreezeReadingFn as y, type GovernorAction as z };

package/dist/react-native.d.ts

@@ -1,8 +1,8 @@
 import { LiveKitRoomProps } from '@livekit/react-native';
 export { AudioSession, VideoTrack, VideoTrackProps, registerGlobals } from '@livekit/react-native';
 import { ReactNode, ReactElement } from 'react';
-import { aK as LiveKitSessionGrant, a as AvatarVideoFit } from './proxy-client-Dm-O0jNn.js';
-export { b as ApproachingEndEvent, c as ApproachingEndReason, A as AvatarSessionClient, 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, U as MAX_RECONNECT_ATTEMPTS, V as MAX_SESSION_INSTRUCTIONS_CHARS, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, 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, aL as isNativeLiveTrackSubscribed, aw as knownBehaviorStates, ax as mapTurnState, ay as sessionBehaviorSchema, az as sessionClipSchema, aB as splitCallTranscript, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aM as useLiveTrackProducing, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-Dm-O0jNn.js';
+import { aS as LiveKitSessionGrant, 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, A as AvatarSessionClient, 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, _ as MAX_RECONNECT_ATTEMPTS, $ as MAX_SESSION_INSTRUCTIONS_CHARS, a3 as ProxyClientOptions, a4 as QualityCap, a5 as RECONNECT_BACKOFF_MS, 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, aT as isNativeLiveTrackSubscribed, aC as knownBehaviorStates, aD as mapTurnState, aE as readInboundRtp, aF as sessionBehaviorSchema, aG as sessionClipSchema, aI as splitCallTranscript, aJ as useAvatarAdaptivePlayoutDelay, aK as useAvatarPlayoutDelay, aL as useAvatarQualityGovernor, aM as useCallTranscript, aN as useLiveKitAvatarGrant, aU as useLiveTrackProducing, aO as useMicLease, aP as useRealtimeSession, aQ as useReleaseMicLeaseOnTrackEnded, aR as useSessionLifecycle } from './proxy-client-BIaUo0az.js';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
 export { DisconnectReason, RemoteAudioTrack, RemoteTrack, RemoteVideoTrack, Room, RoomEvent, SendTextOptions, Track } from 'livekit-client';
@@ -88,6 +88,14 @@ type AvatarVideoSurfaceProps = {
     children?: ReactNode;
     /** Surface a small "live · WxH" badge when the live layer is shown. Default true. */
     showLiveBadge?: boolean;
+    /**
+     * Reclaim the flat 0.5s de-jitter cushion on clean networks — the same opt-in
+     * closed loop the web surface takes, sharing the same implementation. Default
+     * **false**. The loop is stats-driven (no rVFC), so it behaves identically on
+     * iOS and Android; a receiver whose WebRTC shim exposes no `getStats` simply
+     * keeps the flat cushion.
+     */
+    adaptivePlayout?: boolean;
     /** Test id for the box. */
     testID?: string;
 };