realtime-avatar 0.1.0

package/dist/platform.d.ts

@@ -0,0 +1,163 @@
+import type { SourceVideoCacheSettings, VideoCachePlan } from "./types";
+export declare const REALTIME_AVATAR_MODEL_IDS: {
+    readonly live: "realtime-avatar-live-v1";
+    readonly video: "realtime-avatar-video-v1";
+};
+export type RealtimeAvatarPlatformEnvironment = "live" | "test";
+export type PlatformAssetKind = "image" | "video" | "audio";
+export type PlatformAvatarSourceKind = "image" | "video";
+export type PlatformAvatarModelId = (typeof REALTIME_AVATAR_MODEL_IDS)[keyof typeof REALTIME_AVATAR_MODEL_IDS];
+export type PlatformAvatarStatus = "draft" | "preprocessing" | "ready" | "failed" | "disabled" | "deleted";
+export type PlatformAvatarCacheStatus = "queued" | "registering" | "ready" | "stale" | "failed" | "deleted";
+export type PlatformApiKeyScope = "*" | "api_keys:write" | "credits:read" | "avatars:read" | "avatars:write" | "realtime:write" | "usage:read" | "usage:write";
+export type PlatformCreditBalance = {
+    tenantId: string;
+    balanceCreditMicros: number;
+    reservedCreditMicros: number;
+    availableCreditMicros: number;
+    lifetimeGrantedCreditMicros: number;
+    lifetimeUsedCreditMicros: number;
+    updatedAt: string;
+};
+export type PlatformAsset = {
+    id: string;
+    tenantId: string;
+    kind: PlatformAssetKind;
+    status: "pending_upload" | "uploaded" | "processing" | "ready" | "failed" | "deleted";
+    contentType: string;
+    sizeBytes: number;
+    sha256: string | null;
+    publicUrl: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type PlatformAvatar = {
+    id: string;
+    tenantId: string;
+    displayName: string;
+    sourceKind: PlatformAvatarSourceKind;
+    modelId: PlatformAvatarModelId;
+    sourceAssetId: string | null;
+    status: PlatformAvatarStatus;
+    defaultVoiceId: string | null;
+    cacheManifestId: string | null;
+    cacheVersion: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type UpdatePlatformAvatarRequest = {
+    displayName?: string;
+    defaultVoiceId?: string | null;
+    /** Free-form; `settings.persona` / `metadata.persona` drive the avatar's spoken context. */
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type CreatePlatformAvatarRequest = {
+    displayName: string;
+    sourceKind: PlatformAvatarSourceKind;
+    modelId?: PlatformAvatarModelId;
+    sourceAssetId?: string;
+    defaultVoiceId?: string;
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type UploadPlatformAssetOptions = {
+    kind?: PlatformAssetKind;
+    filename?: string;
+    contentType?: string;
+};
+export type CreateRemotePlatformAssetRequest = {
+    kind: PlatformAssetKind;
+    remoteUrl: string;
+    originalFilename?: string;
+    metadata?: Record<string, unknown>;
+};
+export type PlatformAvatarCacheManifest = {
+    id: string;
+    tenantId: string;
+    avatarId: string;
+    cacheKey: string;
+    sourceKind: PlatformAvatarSourceKind;
+    sourceAssetId: string | null;
+    status: PlatformAvatarCacheStatus;
+    modelId: PlatformAvatar["modelId"];
+    backendId: string;
+    modalVolumeName: string;
+    modalVolumePath: string;
+    readyMarkerPath: string | null;
+    artifactR2Key: string | null;
+    previewR2Key: string | null;
+    sourceFingerprint: string | null;
+    settingsFingerprint: string | null;
+    durationSeconds: number | null;
+    frameCount: number | null;
+    byteSize: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type PlanPlatformAvatarVideoCacheRequest = {
+    avatar_id: string;
+    video_cache?: Partial<SourceVideoCacheSettings>;
+};
+export type PlanPlatformAvatarVideoCacheResponse = {
+    status: "queued" | "ready";
+    plan: VideoCachePlan;
+    manifest: PlatformAvatarCacheManifest;
+};
+export type CreateImageAvatarOptions = {
+    displayName: string;
+    image: Blob;
+    filename?: string;
+    defaultVoiceId?: string;
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+export type CreateVideoAvatarOptions = {
+    displayName: string;
+    video: Blob;
+    filename?: string;
+    defaultVoiceId?: string;
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    videoCache?: Partial<SourceVideoCacheSettings>;
+    planCache?: boolean;
+};
+export type CreateVideoAvatarFromUrlOptions = {
+    displayName: string;
+    videoUrl: string;
+    filename?: string;
+    defaultVoiceId?: string;
+    settings?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    assetMetadata?: Record<string, unknown>;
+    videoCache?: Partial<SourceVideoCacheSettings>;
+    planCache?: boolean;
+};
+export type CreateImageAvatarResult = {
+    asset: PlatformAsset;
+    avatar: PlatformAvatar;
+};
+export type CreateVideoAvatarResult = {
+    asset: PlatformAsset;
+    avatar: PlatformAvatar;
+    videoCache: PlanPlatformAvatarVideoCacheResponse | null;
+};
+/**
+ * Non-streaming lipsync: render an audio URL to a talking-head MP4 and get back
+ * its public URL. Provide an existing `avatarId` or a `portraitUrl` to register
+ * on the fly.
+ */
+export type LipsyncOptions = {
+    audioUrl: string;
+    avatarId?: string;
+    portraitUrl?: string;
+    backgroundId?: string;
+};
+export type LipsyncResult = {
+    url: string;
+    avatarId: string;
+    frames: number;
+    fps: number;
+    durationSeconds: number;
+};
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/platform.js

@@ -0,0 +1,5 @@
+export const REALTIME_AVATAR_MODEL_IDS = {
+    live: "realtime-avatar-live-v1",
+    video: "realtime-avatar-video-v1",
+};
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,0BAA0B;CACzB,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./provider";
+export * from "./session";
+export * from "./stage";
+export * from "./realtime";
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,5 @@
+export * from "./provider";
+export * from "./session";
+export * from "./stage";
+export * from "./realtime";
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC"}

package/dist/react/provider.d.ts

@@ -0,0 +1,37 @@
+import type { ReactElement, ReactNode } from "react";
+import { RealtimeAvatarClient } from "../client";
+import type { RealtimeTurnRequest } from "../types";
+import type { CloudflareWhepPlaybackOptions } from "../browser/webrtc";
+export type RealtimeAvatarProviderMediaOptions = {
+    sfu?: "auto" | "off";
+    waitForViewer?: boolean;
+    waitForViewerMs?: number;
+    whep?: CloudflareWhepPlaybackOptions;
+};
+export type RealtimeAvatarProviderDefaults = {
+    mode?: "interactive" | "livestream" | "compat";
+    media?: "auto" | "off" | RealtimeAvatarProviderMediaOptions;
+    transport?: "auto" | "http";
+    connectTimeoutMs?: number;
+    playoutDelayMs?: number | "adaptive";
+    turnDefaults?: Partial<RealtimeTurnRequest>;
+};
+export type RealtimeAvatarProviderProps = {
+    /** Shared SDK client. Browser apps usually pass `RealtimeAvatarClient.webProxy(...)`. */
+    client?: RealtimeAvatarClient;
+    /** Defaults merged into every `useRealtimeAvatar()` call below this provider. */
+    defaults?: RealtimeAvatarProviderDefaults;
+    children?: ReactNode;
+};
+export type RealtimeAvatarContextValue = {
+    client: RealtimeAvatarClient;
+    defaults: RealtimeAvatarProviderDefaults;
+};
+/**
+ * Optional app-level SDK configuration. Most apps can skip this; use it when
+ * self-hosting routes, testing with a mock client, or setting global defaults.
+ */
+export declare function RealtimeAvatarProvider(props: RealtimeAvatarProviderProps): ReactElement;
+export declare function useRealtimeAvatarClient(): RealtimeAvatarClient;
+export declare function useRealtimeAvatarContext(): RealtimeAvatarContextValue;
+//# sourceMappingURL=provider.d.ts.map

package/dist/react/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/react/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,MAAM,MAAM,kCAAkC,GAAG;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,6BAA6B,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,kCAAkC,CAAC;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,yFAAyF;IACzF,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,8BAA8B,CAAC;IAC1C,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,8BAA8B,CAAC;CAC1C,CAAC;AAKF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,YAAY,CASvF;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED,wBAAgB,wBAAwB,IAAI,0BAA0B,CAKrE"}

package/dist/react/provider.js

@@ -0,0 +1,33 @@
+import { createContext, createElement, useContext, useMemo } from "react";
+import { RealtimeAvatarClient } from "../client";
+const RealtimeAvatarContext = createContext(null);
+let defaultBrowserClient = null;
+/**
+ * Optional app-level SDK configuration. Most apps can skip this; use it when
+ * self-hosting routes, testing with a mock client, or setting global defaults.
+ */
+export function RealtimeAvatarProvider(props) {
+    const { client, defaults, children } = props;
+    const fallbackClient = useMemo(() => client ?? RealtimeAvatarClient.webProxy(), [client]);
+    const defaultsKey = stableJson(defaults ?? {});
+    const value = useMemo(() => ({ client: fallbackClient, defaults: defaults ?? {} }), [fallbackClient, defaultsKey]);
+    return createElement(RealtimeAvatarContext.Provider, { value }, children);
+}
+export function useRealtimeAvatarClient() {
+    return useRealtimeAvatarContext().client;
+}
+export function useRealtimeAvatarContext() {
+    const context = useContext(RealtimeAvatarContext);
+    if (context)
+        return context;
+    defaultBrowserClient ??= RealtimeAvatarClient.webProxy();
+    return { client: defaultBrowserClient, defaults: {} };
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return item;
+        return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)));
+    });
+}
+//# sourceMappingURL=provider.js.map

package/dist/react/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/react/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAiCjD,MAAM,qBAAqB,GAAG,aAAa,CAAoC,IAAI,CAAC,CAAC;AACrF,IAAI,oBAAoB,GAAgC,IAAI,CAAC;AAE7D;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC7C,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,IAAI,oBAAoB,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1F,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,OAAO,CACnB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC,EAC5D,CAAC,cAAc,EAAE,WAAW,CAAC,CAC9B,CAAC;IACF,OAAO,aAAa,CAAC,qBAAqB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,OAAO,wBAAwB,EAAE,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,MAAM,OAAO,GAAG,UAAU,CAAC,qBAAqB,CAAC,CAAC;IAClD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,oBAAoB,KAAK,oBAAoB,CAAC,QAAQ,EAAE,CAAC;IACzD,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1E,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/react/realtime.d.ts

@@ -0,0 +1,74 @@
+import type { ReactElement } from "react";
+import { RealtimeAvatarClient } from "../client";
+import type { RealtimeTurnRequest } from "../types";
+import type { CloudflareWhepPlaybackOptions } from "../browser/webrtc";
+import { type UseAvatarSessionResult } from "./session";
+import { type AvatarStageProps } from "./stage";
+export type RealtimeAvatarMode = "interactive" | "livestream" | "compat";
+export type RealtimeAvatarSource = {
+    kind: "portrait";
+    url?: string | null;
+} | {
+    kind: "video";
+    url?: string | null;
+    cacheId?: string | null;
+};
+export type RealtimeAvatarMediaOptions = {
+    /**
+     * "auto" attaches the granted SFU/WHEP playback when available. Defaults to
+     * "off" in interactive/compat and "auto" in livestream.
+     */
+    sfu?: "auto" | "off";
+    /** If true, prepare does not resolve until WHEP is ready or waitForViewerMs expires. */
+    waitForViewer?: boolean;
+    waitForViewerMs?: number;
+    /** Advanced Cloudflare WHEP tuning. Most apps should omit this. */
+    whep?: CloudflareWhepPlaybackOptions;
+};
+export type UseRealtimeAvatarOptions = {
+    /**
+     * Browser apps usually omit this and let the SDK call `RealtimeAvatarClient.webProxy()`
+     * or read the shared client from `RealtimeAvatarProvider`.
+     */
+    client?: RealtimeAvatarClient;
+    avatarId: string;
+    source?: RealtimeAvatarSource;
+    mode?: RealtimeAvatarMode;
+    voiceId?: string;
+    backgroundId?: string;
+    turnDefaults?: Partial<RealtimeTurnRequest>;
+    autoPrepare?: boolean;
+    /**
+     * Simple form: "auto" | "off". Object form exposes SFU preconnect policy.
+     * By default, interactive avoids SFU overhead; livestream preconnects it.
+     */
+    media?: "auto" | "off" | RealtimeAvatarMediaOptions;
+    /** Rare override. Defaults: "auto" except compat => "http". */
+    transport?: "auto" | "http";
+    connectTimeoutMs?: number;
+    playoutDelayMs?: number | "adaptive";
+};
+export type UseRealtimeAvatarResult = UseAvatarSessionResult & {
+    mode: RealtimeAvatarMode;
+    source: RealtimeAvatarSource | null;
+    /** Product-facing alias for `send()`. */
+    chat: UseAvatarSessionResult["send"];
+};
+/**
+ * Product-facing React hook for app developers. It chooses the right transport
+ * policy for the use case:
+ * - interactive: lowest-latency WS/canvas, no SFU overhead by default.
+ * - livestream: WS/canvas immediately, Cloudflare WHEP/SFU preconnected for viewers.
+ * - compat: HTTP streaming only.
+ */
+export declare function useRealtimeAvatar(options: UseRealtimeAvatarOptions): UseRealtimeAvatarResult;
+export type RealtimeAvatarViewProps = Omit<AvatarStageProps, "session" | "idleVideoUrl" | "portraitUrl"> & {
+    avatar: UseRealtimeAvatarResult;
+    /** Override the idle loop inferred from `source.kind === "video"`. */
+    idleVideoUrl?: string | null;
+    /** Override the portrait/poster inferred from `source.kind === "portrait"`. */
+    poster?: string | null;
+};
+/** Product-facing stage for `useRealtimeAvatar()`. */
+export declare function RealtimeAvatarView(props: RealtimeAvatarViewProps): ReactElement;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/react/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/react/realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC;AAEvE,OAAO,EAAoB,KAAK,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAe,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,wFAAwF;IACxF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,IAAI,CAAC,EAAE,6BAA6B,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,0BAA0B,CAAC;IACpD,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,GAAG;IAC7D,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpC,yCAAyC;IACzC,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAqE5F;AAED,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,cAAc,GAAG,aAAa,CAAC,GAAG;IACzG,MAAM,EAAE,uBAAuB,CAAC;IAChC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,YAAY,CAQ/E"}

package/dist/react/realtime.js

@@ -0,0 +1,105 @@
+import { createElement, useMemo } from "react";
+import { useRealtimeAvatarContext } from "./provider";
+import { useAvatarSession } from "./session";
+import { AvatarStage } from "./stage";
+/**
+ * Product-facing React hook for app developers. It chooses the right transport
+ * policy for the use case:
+ * - interactive: lowest-latency WS/canvas, no SFU overhead by default.
+ * - livestream: WS/canvas immediately, Cloudflare WHEP/SFU preconnected for viewers.
+ * - compat: HTTP streaming only.
+ */
+export function useRealtimeAvatar(options) {
+    const context = useRealtimeAvatarContext();
+    const { client, avatarId, source, mode: modeOption, voiceId, backgroundId, turnDefaults, autoPrepare, media: mediaOption, transport: transportOption, connectTimeoutMs: connectTimeoutMsOption, playoutDelayMs: playoutDelayMsOption, } = options;
+    const defaultClient = client ?? context.client;
+    const mode = modeOption ?? context.defaults.mode ?? "interactive";
+    const media = mediaOption ?? context.defaults.media;
+    const transport = transportOption ?? context.defaults.transport;
+    const connectTimeoutMs = connectTimeoutMsOption ?? context.defaults.connectTimeoutMs;
+    const playoutDelayMs = playoutDelayMsOption ?? context.defaults.playoutDelayMs;
+    const mediaKey = stableJson({ mode, media });
+    const mediaPolicy = useMemo(() => normalizeRealtimeAvatarMedia(mode, media), [mediaKey]);
+    const sourceKind = source?.kind;
+    const sourceUrl = source?.url ?? null;
+    const sourceCacheId = source?.kind === "video" ? source.cacheId ?? null : null;
+    const sessionSource = useMemo(() => sessionSourceFromRealtimeSource(source), [sourceKind, sourceUrl, sourceCacheId]);
+    const normalizedSource = useMemo(() => {
+        if (!sourceKind)
+            return null;
+        return sourceKind === "video"
+            ? { kind: "video", url: sourceUrl, cacheId: sourceCacheId }
+            : { kind: "portrait", url: sourceUrl };
+    }, [sourceKind, sourceUrl, sourceCacheId]);
+    const turnDefaultsKey = stableJson({ provider: context.defaults.turnDefaults ?? {}, local: turnDefaults ?? {} });
+    const resolvedTurnDefaults = useMemo(() => ({
+        max_buffer_delay_ms: 90,
+        low_latency_first_chunk: true,
+        ...(context.defaults.turnDefaults ?? {}),
+        ...turnDefaults,
+    }), [turnDefaultsKey]);
+    const session = useAvatarSession({
+        client: defaultClient,
+        avatarId,
+        ...sessionSource,
+        voiceId,
+        backgroundId,
+        turnDefaults: resolvedTurnDefaults,
+        autoPrepare,
+        transport: transport ?? (mode === "compat" ? "http" : "auto"),
+        media: mediaPolicy.media,
+        whep: mediaPolicy.whep,
+        waitForMedia: mediaPolicy.waitForMedia,
+        waitForMediaMs: mediaPolicy.waitForMediaMs,
+        connectTimeoutMs,
+        playoutDelayMs,
+    });
+    return {
+        ...session,
+        mode,
+        source: normalizedSource,
+        chat: session.send,
+    };
+}
+/** Product-facing stage for `useRealtimeAvatar()`. */
+export function RealtimeAvatarView(props) {
+    const { avatar, idleVideoUrl, poster, ...stageProps } = props;
+    return createElement(AvatarStage, {
+        ...stageProps,
+        session: avatar,
+        idleVideoUrl: idleVideoUrl ?? (avatar.source?.kind === "video" ? avatar.source.url : null),
+        portraitUrl: poster ?? (avatar.source?.kind === "portrait" ? avatar.source.url : null),
+    });
+}
+function sessionSourceFromRealtimeSource(source) {
+    if (!source)
+        return {};
+    if (source.kind === "portrait") {
+        return { sourceKind: "portrait", portraitUrl: source.url ?? null };
+    }
+    return {
+        sourceKind: "source_video",
+        sourceVideoUrl: source.url ?? null,
+        videoCacheId: source.cacheId ?? null,
+    };
+}
+function normalizeRealtimeAvatarMedia(mode, media) {
+    const modeDefault = mode === "livestream" ? "auto" : "off";
+    if (!media || typeof media === "string") {
+        return { media: media ?? modeDefault };
+    }
+    return {
+        media: media.sfu ?? modeDefault,
+        whep: media.whep,
+        waitForMedia: media.waitForViewer,
+        waitForMediaMs: media.waitForViewerMs,
+    };
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return item;
+        return Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)));
+    });
+}
+//# sourceMappingURL=realtime.js.map

package/dist/react/realtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.js","sourceRoot":"","sources":["../../src/react/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAM/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAA+B,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAyB,MAAM,SAAS,CAAC;AAoD7D;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,OAAO,GAAG,wBAAwB,EAAE,CAAC;IAC3C,MAAM,EACJ,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EAAE,UAAU,EAChB,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,eAAe,EAC1B,gBAAgB,EAAE,sBAAsB,EACxC,cAAc,EAAE,oBAAoB,GACrC,GAAG,OAAO,CAAC;IACZ,MAAM,aAAa,GAAG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC/C,MAAM,IAAI,GAAG,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,aAAa,CAAC;IAClE,MAAM,KAAK,GAAG,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACpD,MAAM,SAAS,GAAG,eAAe,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAChE,MAAM,gBAAgB,GAAG,sBAAsB,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IACrF,MAAM,cAAc,GAAG,oBAAoB,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC/E,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,4BAA4B,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzF,MAAM,UAAU,GAAG,MAAM,EAAE,IAAI,CAAC;IAChC,MAAM,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC;IACtC,MAAM,aAAa,GAAG,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,MAAM,aAAa,GAAG,OAAO,CAC3B,GAAG,EAAE,CAAC,+BAA+B,CAAC,MAAM,CAAC,EAC7C,CAAC,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,CACvC,CAAC;IACF,MAAM,gBAAgB,GAAG,OAAO,CAA8B,GAAG,EAAE;QACjE,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAC7B,OAAO,UAAU,KAAK,OAAO;YAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE;YAC3D,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IAC3C,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC;IAC3C,MAAM,eAAe,GAAG,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,YAAY,IAAI,EAAE,EAAE,KAAK,EAAE,YAAY,IAAI,EAAE,EAAE,CAAC,CAAC;IACjH,MAAM,oBAAoB,GAAG,OAAO,CAClC,GAAG,EAAE,CAAC,CAAC;QACL,mBAAmB,EAAE,EAAE;QACvB,uBAAuB,EAAE,IAAI;QAC7B,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,IAAI,EAAE,CAAC;QACxC,GAAG,YAAY;KAChB,CAAC,EACF,CAAC,eAAe,CAAC,CAClB,CAAC;IACF,MAAM,OAAO,GAAG,gBAAgB,CAAC;QAC/B,MAAM,EAAE,aAAa;QACrB,QAAQ;QACR,GAAG,aAAa;QAChB,OAAO;QACP,YAAY;QACZ,YAAY,EAAE,oBAAoB;QAClC,WAAW;QACX,SAAS,EAAE,SAAS,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAC7D,KAAK,EAAE,WAAW,CAAC,KAAK;QACxB,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,YAAY,EAAE,WAAW,CAAC,YAAY;QACtC,cAAc,EAAE,WAAW,CAAC,cAAc;QAC1C,gBAAgB;QAChB,cAAc;KACf,CAAC,CAAC;IACH,OAAO;QACL,GAAG,OAAO;QACV,IAAI;QACJ,MAAM,EAAE,gBAAgB;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC;AACJ,CAAC;AAUD,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC;IAC9D,OAAO,aAAa,CAAC,WAAW,EAAE;QAChC,GAAG,UAAU;QACb,OAAO,EAAE,MAAM;QACf,YAAY,EAAE,YAAY,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1F,WAAW,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;KACvF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,+BAA+B,CAAC,MAAwC;IAI/E,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,OAAO;QACL,UAAU,EAAE,cAAc;QAC1B,cAAc,EAAE,MAAM,CAAC,GAAG,IAAI,IAAI;QAClC,YAAY,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CACnC,IAAwB,EACxB,KAAwC;IAOxC,MAAM,WAAW,GAAG,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3D,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,WAAW,EAAE,CAAC;IACzC,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI,WAAW;QAC/B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,YAAY,EAAE,KAAK,CAAC,aAAa;QACjC,cAAc,EAAE,KAAK,CAAC,eAAe;KACtC,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QAC1C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1E,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/react/session.d.ts

@@ -0,0 +1,91 @@
+import type { RefObject } from "react";
+import type { RealtimeAvatarClient } from "../client";
+import type { AvatarSessionConfig, AvatarSessionTransport } from "../session";
+import type { RealtimePrepareResponse, RealtimeTurnRequest } from "../types";
+import { type AvatarPlayerMetrics, type AvatarPlaySummary } from "../browser/player";
+import { type AvatarSessionMediaState } from "../browser/media-session";
+import type { CloudflareWhepPlaybackOptions } from "../browser/webrtc";
+import type { RealtimeMediaPlan } from "../media";
+export type UseAvatarSessionStatus = "idle" | "preparing" | "ready" | "thinking" | "speaking" | "error";
+export type UseAvatarSessionOptions = AvatarSessionConfig & {
+    client: RealtimeAvatarClient;
+    /** Prepare automatically whenever the avatar/source changes. Default true. */
+    autoPrepare?: boolean;
+    /**
+     * "auto" (default): pin prepare + turns to one GPU container over a single
+     * WebSocket when the client supports it, falling back to HTTP transparently.
+     * "http": skip the socket entirely.
+     */
+    transport?: "auto" | "http";
+    /** Enables SDK-managed Cloudflare WHEP when the platform grants a media plan. Default "auto". */
+    media?: "auto" | "off";
+    /** Optional WHEP tuning. The socket/canvas mux remains fallback unless WHEP reaches "playing". */
+    whep?: CloudflareWhepPlaybackOptions;
+    /** Strict mode only: wait for WHEP before reporting ready. Default false. */
+    waitForMedia?: boolean;
+    waitForMediaMs?: number;
+    /** Cap socket prepare before falling back to HTTP. Defaults to 5s; pass 0 to disable. */
+    connectTimeoutMs?: number;
+    /** "adaptive" (default) starts playout on the first decodable video frame; a number fixes the legacy delay in ms. */
+    playoutDelayMs?: number | "adaptive";
+};
+export type AvatarTurnOptions = {
+    /** Prior chat context to send before the user's new message. */
+    history?: RealtimeTurnRequest["messages"];
+    /** Per-turn request overrides, e.g. source_start_frame or voice settings. */
+    turn?: Partial<RealtimeTurnRequest>;
+};
+export type UseAvatarSessionResult = {
+    canvasRef: RefObject<HTMLCanvasElement | null>;
+    /** Bind to a muted <video> when using SDK-managed WebRTC media. Safe across remounts. */
+    videoRef: (node: HTMLVideoElement | null) => void;
+    /** Current video element, for apps that need imperative inspection. Prefer `videoRef` for binding. */
+    videoElementRef: RefObject<HTMLVideoElement | null>;
+    status: UseAvatarSessionStatus;
+    ready: boolean;
+    busy: boolean;
+    error: string | null;
+    /** Original error object for callers that need structured details (for example billing/paywall codes). */
+    lastError: unknown;
+    /** Streaming assistant reply for the current/last turn. */
+    text: string;
+    /** Last successful prepare response, including runtime timings and source-video cache metadata. */
+    prepared: RealtimePrepareResponse | null;
+    metrics: AvatarPlayerMetrics;
+    /** How turns are running right now ("socket" = single-container low-latency path). */
+    transport: AvatarSessionTransport;
+    /** Optional media-plane plan returned by the session grant. */
+    mediaPlan: RealtimeMediaPlan | null;
+    /** WebRTC media state; WS mux/canvas remains the fallback unless this is "playing". */
+    mediaState: AvatarSessionMediaState;
+    mediaError: string | null;
+    /** True once the fallback canvas has drawn a frame for the current turn. */
+    canvasLive: boolean;
+    /** True once the WHEP video has decoded enough to show. */
+    webrtcLive: boolean;
+    /** Last play summary, useful for source-video handoff or analytics. */
+    lastSummary: AvatarPlaySummary | null;
+    /** Unlock browser audio from a user gesture before autoplaying later turns. */
+    unlockAudio: () => Promise<void>;
+    /** Audio stream tap for recording the exact player output; call `unlockAudio()` first. */
+    captureAudioStream: () => MediaStream | null;
+    send: (text: string, options?: AvatarTurnOptions) => Promise<AvatarPlaySummary | null>;
+    speak: (text: string, options?: Omit<AvatarTurnOptions, "history">) => Promise<AvatarPlaySummary | null>;
+    prepare: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    stop: () => void;
+    disconnect: () => void;
+};
+/**
+ * Drop-in realtime avatar session for React. Owns prepare lifecycle + audio-
+ * clocked playback; bind `canvasRef` to a `<canvas>` and call `send`.
+ *
+ *     const avatar = useAvatarSession({ client, avatarId });
+ *     return <>
+ *       <canvas ref={avatar.canvasRef} />
+ *       <button onClick={() => avatar.send("hi")} disabled={!avatar.ready}>Send</button>
+ *     </>;
+ */
+export declare function useAvatarSession(options: UseAvatarSessionOptions): UseAvatarSessionResult;
+//# sourceMappingURL=session.d.ts.map

package/dist/react/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/react/session.ts"],"names":[],"mappings":"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"}