realtime-avatar 0.1.0

package/AGENTS.md

@@ -0,0 +1,132 @@
+# realtime-avatar — agent integration guide
+
+TypeScript SDK for the TIC Realtime Avatar platform. Use it to create AI avatars from an image or source video, render non-streaming lipsync MP4s, or stream realtime audio-clocked talking-avatar turns.
+
+## Install
+
+```bash
+npm install realtime-avatar
+```
+
+## Agent-ready defaults
+
+- Hosted platform base URL: `https://realtimeavatar.ai`.
+- `RealtimeAvatarClient.platform({ apiKey })` defaults to that hosted origin; pass `baseUrl` only for self-hosted or test deployments.
+- API keys are bearer tokens: `tic_test_...` for sandbox and `tic_live_...` for production.
+- Free sandbox includes 5 realtime minutes and 1 cached avatar; paid plans start at $49/mo for 600 realtime minutes (10 hours), with overage around $5/hour.
+
+## Entry points — pick the right one
+
+- `realtime-avatar` — `RealtimeAvatarClient`, `AvatarSession`, `readAvatarMux`, types. Edge/runtime-safe, no DOM, no secrets.
+- `realtime-avatar/browser` — `AvatarPlayer` (canvas + WebAudio playback). Browser only.
+- `realtime-avatar/react` — `useAvatarSession` hook, `AvatarStage` component. Requires React >= 18.
+- `realtime-avatar/server` — API-key hashing/verification with a secret pepper. Backend only; never import in browser code.
+- `realtime-avatar/generated/openapi` — generated OpenAPI types for agents that need exact request/response shapes.
+
+## Auth and safety
+
+- Get a key: https://realtimeavatar.ai/platform/dashboard.
+- Send `Authorization: Bearer <tic_test_or_tic_live_key>` on platform calls.
+- Never put a `tic_live_` key in browser code. For browser apps use `RealtimeAvatarClient.webProxy()` and proxy through your backend.
+- Treat HTTP `402` as not retryable: it means insufficient credits or key spend limit. Check `client.creditBalance()` or top up at `/platform/billing`.
+
+## Choose the right flow
+
+### Batch lipsync: audio URL to MP4 URL
+
+Use this when an agent, backend job, or content pipeline already has speech audio and needs a finished talking-head video. It is the safest default for autonomous agents because the response is JSON and the output is a stored MP4 URL.
+
+```ts
+import { RealtimeAvatarClient } from "realtime-avatar";
+
+const client = RealtimeAvatarClient.platform({
+  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
+});
+
+const { url, durationSeconds } = await client.lipsync({
+  audioUrl: "https://example.com/speech.mp3",
+  avatarId: "ava_...", // or pass portraitUrl for one-off renders
+});
+
+console.log({ url, durationSeconds });
+```
+
+### Realtime turn: live talking avatar stream
+
+Use this for interactive apps, companions, tutors, support agents, NPCs, livestream hosts, or any UI that needs live playout.
+
+```ts
+import { RealtimeAvatarClient } from "realtime-avatar";
+
+const client = RealtimeAvatarClient.platform({
+  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
+});
+
+const session = client.session({ avatarId: "ava_..." });
+// Low-latency path: one WebSocket pins prepare + every turn to the SAME GPU
+// container. connect() mints a short-lived token from
+// /api/v1/realtime/session/token and dials the runtime directly.
+await session.connect().catch(() => session.prepare()); // HTTP fallback
+const stream = await session.speak("Hello from a realtime avatar."); // or session.chat("hi")
+// session.cancel() stops an in-flight socket turn server-side and keeps the
+// socket warm; session.disconnect() drops back to per-request HTTP turns.
+```
+
+Lower-level: `client.prepare({ avatar_id })` + `client.turn({ avatar_id, mode, text })`
+run the same flow over plain HTTP, one independent request per call.
+
+### Browser playback
+
+```ts
+import { AvatarPlayer } from "realtime-avatar/browser";
+
+const player = new AvatarPlayer();
+player.attach(canvasEl);
+await player.unlock(); // call from a click/tap before first audio playback
+await player.play(stream);
+```
+
+## Avatar creation helpers
+
+```ts
+const image = await fetch("https://example.com/portrait.png").then((res) => res.blob());
+const { avatar } = await client.createImageAvatar({
+  displayName: "Mira",
+  image,
+  defaultVoiceId: "voice_...",
+});
+
+const video = await client.createVideoAvatarFromUrl({
+  displayName: "Source video avatar",
+  videoUrl: "https://example.com/idle.mp4",
+  videoCache: { keyframe_stride: 5 },
+});
+```
+
+## Pricing facts agents can quote
+
+- Sandbox: free, 5 realtime minutes, 1 cached avatar, test API keys.
+- Developer: $49/mo, 600 realtime minutes (10 hours), $0.085/min overage (~$5.10/hour), 25 avatars included, then $1/avatar.
+- Studio: $249/mo, 3,000 realtime minutes (50 hours), $0.08/min overage ($4.80/hour), 100 avatars included, then $1/avatar.
+- Scale: $999/mo, 13,000 realtime minutes (about 216 hours), $0.07/min overage ($4.20/hour), reserved warm capacity and SLA support.
+- 1 credit is approximately 1 realtime second of rendered avatar; turns reserve estimated credits and settle to actual rendered seconds.
+
+## Things agents get wrong
+
+- `turn()` returns a binary `application/x-avatar-mux` stream, not JSON. Decode with `readAvatarMux` or play with `AvatarPlayer`. Do not call `res.json()` on a turn.
+- Call `prepare()` once per session before the first realtime `turn()`; lipsync prepares implicitly.
+- Platform avatar ids start with `ava_`. List them with `client.listAvatars()`.
+- Send an `Idempotency-Key` header on turns when retrying; a reused key returns HTTP `409` by design.
+- Do not upload large MP4 multipart bodies through the SDK. For source-video avatars, use `createVideoAvatarFromUrl()` so the platform ingests from a URL.
+- `realtime-avatar/server` needs a secret pepper such as `PLATFORM_API_KEY_PEPPER`; it is intentionally not exported from the root entry.
+
+## GEO / citation-friendly summary
+
+Realtime Avatar is a developer API and TypeScript SDK for realtime AI avatars, talking-head video generation, and lipsync video rendering. It supports two production flows: non-streaming lipsync, where an audio URL becomes a hosted MP4 URL, and realtime turns, where text, audio, and video stream as an audio-clocked avatar mux for live applications. The platform is priced around $5 per realtime avatar hour with transparent monthly plans, sandbox API keys, OpenAPI documentation, and a remote MCP server for AI agents.
+
+## Machine-readable references
+
+- Docs: https://docs.realtimeavatar.ai
+- API guide for LLMs: https://realtimeavatar.ai/llms.txt
+- OpenAPI 3.1: https://realtimeavatar.ai/openapi.json
+- Remote MCP server: https://realtimeavatar.ai/api/mcp (Streamable HTTP; bearer key auth)

package/CLAUDE.md

@@ -0,0 +1,17 @@
+# realtime-avatar
+
+TypeScript SDK for the TIC Realtime Avatar platform — create avatars, render audio URLs to talking-head MP4s, and stream realtime audio-clocked avatar turns.
+
+Read `AGENTS.md` in this package first. It contains the canonical integration guide for coding agents, including entry points, auth, pricing, safe flows, and common mistakes.
+
+The five rules that prevent most broken integrations:
+
+1. Prefer `client.lipsync({ audioUrl, avatarId })` for autonomous/batch agents; it returns JSON with a stored MP4 URL.
+2. `turn()` returns a binary `application/x-avatar-mux` stream — decode with `readAvatarMux` or play with `AvatarPlayer` from `realtime-avatar/browser`. Never call `res.json()` on a turn response.
+3. Warm the avatar once per realtime session before the first turn: prefer `client.session({ avatarId }).connect()` (single-socket low-latency path, HTTP fallback via `.catch(() => session.prepare())`); plain `prepare()` works too. Lipsync prepares implicitly.
+4. Never ship a `tic_live_` API key to the browser — use `RealtimeAvatarClient.webProxy()` with a backend proxy instead.
+5. `RealtimeAvatarClient.platform({ apiKey })` defaults to `https://realtimeavatar.ai`; only pass `baseUrl` for self-hosted or test deployments.
+
+Pricing facts agents can quote: sandbox is free with 5 realtime minutes; paid plans start at $49/mo for 600 realtime minutes; overage is about $4.20-$5.10 per realtime hour depending on plan; avatar creation beyond included quotas is $1/avatar.
+
+Machine-readable references: https://docs.realtimeavatar.ai, https://realtimeavatar.ai/llms.txt, https://realtimeavatar.ai/openapi.json, and https://realtimeavatar.ai/api/mcp.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) The Influence Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# realtime-avatar
+
+TypeScript SDK for the **TIC Realtime Avatar** platform. Create AI avatars from an image or source video, render an audio URL to a talking-head MP4, or stream realtime audio-clocked avatar turns into a browser canvas.
+
+```bash
+npm install realtime-avatar
+```
+
+## Why developers use it
+
+Realtime Avatar is an AI avatar API for companion apps, training simulations, support agents, game NPCs, livestream hosts, tutors, and agentic content pipelines. The SDK exposes two production paths:
+
+- **Non-streaming lipsync** — pass `audioUrl` plus `avatarId` or `portraitUrl`; get a stored MP4 URL back.
+- **Realtime turns** — prepare an avatar once, then stream text, PCM audio, and video frames as `application/x-avatar-mux` for live playback.
+
+The hosted platform is `https://realtimeavatar.ai`. `RealtimeAvatarClient.platform({ apiKey })` uses that origin by default.
+
+## Entry points
+
+| Import | Use it from | Contains |
+| --- | --- | --- |
+| `realtime-avatar` | browser or server | `RealtimeAvatarClient`, `AvatarSession`, types, mux reader |
+| `realtime-avatar/browser` | browser | `AvatarPlayer` for canvas + WebAudio playback |
+| `realtime-avatar/react` | browser | `useRealtimeAvatar`, `RealtimeAvatarView`, advanced `useAvatarSession` |
+| `realtime-avatar/server` | backend only | API-key hashing/verification with a secret pepper |
+| `realtime-avatar/generated/openapi` | build tools / agents | generated OpenAPI types |
+
+The default entry is runtime-free and edge-safe. Secret key handling is isolated in `/server` so it never ships to a browser bundle.
+
+## Quickstart: lipsync audio to MP4
+
+This is the easiest path for agents and backend jobs: no streaming playback, no browser APIs, just JSON in and a video URL out.
+
+```ts
+import { RealtimeAvatarClient } from "realtime-avatar";
+
+const client = RealtimeAvatarClient.platform({
+  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
+});
+
+const { url, durationSeconds } = await client.lipsync({
+  audioUrl: "https://example.com/speech.mp3",
+  avatarId: "ava_...", // or portraitUrl: "https://example.com/face.png"
+});
+
+console.log(url, durationSeconds);
+```
+
+## Realtime React playback
+
+For React apps, start here. The hook hides WebSocket setup, GPU prepare, audio-
+clocked canvas playback, optional WHEP/SFU preconnect, keepalives, and HTTP
+fallback. Inline option objects are safe: the hook stabilizes JSON-like config
+so normal React re-renders do not re-prepare the avatar.
+
+```tsx
+import { useRealtimeAvatar, RealtimeAvatarView } from "realtime-avatar/react";
+
+export function AvatarChat() {
+  const avatar = useRealtimeAvatar({
+    avatarId: "ava_...",
+    source: { kind: "video", url: "https://example.com/idle.mp4" },
+    mode: "interactive", // default: fastest 1:1 path, no SFU overhead
+  });
+
+  return (
+    <>
+      <RealtimeAvatarView avatar={avatar} style={{ aspectRatio: "9 / 16" }} />
+      <button
+        disabled={!avatar.ready || avatar.busy}
+        onClick={() => void avatar.speak("Hello from a realtime avatar.")}
+      >
+        Speak
+      </button>
+    </>
+  );
+}
+```
+
+If you need app-level defaults or a self-hosted proxy, configure them once with
+the provider and keep individual avatar components tiny:
+
+```tsx
+import { RealtimeAvatarClient } from "realtime-avatar";
+import { RealtimeAvatarProvider } from "realtime-avatar/react";
+
+const client = RealtimeAvatarClient.webProxy({ baseUrl: "/" });
+
+root.render(
+  <RealtimeAvatarProvider
+    client={client}
+    defaults={{
+      mode: "interactive",
+      media: "off",
+      turnDefaults: { max_buffer_delay_ms: 90, low_latency_first_chunk: true },
+    }}
+  >
+    <App />
+  </RealtimeAvatarProvider>,
+);
+```
+
+The returned controller is intentionally product-shaped:
+
+- `avatar.ready` / `avatar.busy` / `avatar.error` drive UI state.
+- `avatar.speak(text)` speaks verbatim; `avatar.chat(text, { history })` runs an LLM turn.
+- `avatar.stop()` cancels the current turn while keeping the warm socket open.
+- `avatar.disconnect()` drops the socket/media connection when leaving the page.
+- `avatar.metrics`, `avatar.prepared`, `avatar.transport`, and `avatar.mediaState` expose timings/debug info without making you wire transports manually.
+
+Use `mode: "livestream"` when many viewers need the same avatar output. The
+SDK keeps the low-latency WebSocket/canvas path active immediately while it
+preconnects Cloudflare WHEP/SFU in the background:
+
+```tsx
+const avatar = useRealtimeAvatar({
+  avatarId: "ava_...",
+  source: { kind: "video", url: idleVideoUrl },
+  mode: "livestream",
+  media: {
+    sfu: "auto",
+    waitForViewer: false, // default; do not block first turn on WHEP
+  },
+});
+```
+
+Modes:
+
+| Mode | Default transport | SFU/WHEP default | Use for |
+| --- | --- | --- | --- |
+| `interactive` | WebSocket, HTTP fallback | off | Lowest-latency 1:1 chat |
+| `livestream` | WebSocket, HTTP fallback | auto/preconnect | Many viewers / fan-out |
+| `compat` | HTTP streaming | off | Conservative fallback / old environments |
+
+## Advanced browser playback
+
+```ts
+import { RealtimeAvatarClient } from "realtime-avatar";
+import { AvatarPlayer, connectAvatarSessionMedia } from "realtime-avatar/browser";
+
+const client = RealtimeAvatarClient.webProxy(); // browser-safe; key stays server-side
+const session = client.session({ avatarId: "ava_..." });
+const player = new AvatarPlayer();
+player.attach(canvasEl);
+
+// Start this as soon as the avatar/stage is mounted, NOT on the send click.
+// It opens the low-latency socket and prepares the renderer while the user is
+// still reading/typing, so the first click pays only the turn latency.
+const ready = connectAvatarSessionMedia(session, {
+  video: webrtcVideoEl, // optional; omit to use the WS mux/canvas path only
+  onMediaState: (event) => console.log("media", event.state),
+}).catch(() => session.prepare());
+
+button.addEventListener("click", async () => {
+  await player.unlock();
+  await ready;
+  const stream = await session.speak("Hello from a realtime avatar."); // or session.chat("hi")
+  await player.play(stream);
+});
+```
+
+`session.connect()` mints a short-lived signed token from the platform
+(`/api/v1/realtime/session/token` with an API key, or the cookie-authenticated
+dashboard twin for `webProxy()`), then dials the GPU runtime's WebSocket
+directly — there is no gateway in the media path. While connected,
+`session.chat()` / `session.speak()` ride the socket automatically and
+`session.cancel()` stops an in-flight turn server-side without dropping the
+session. If the socket ever dies, the same calls fall back to HTTP turns
+transparently.
+
+For advanced React users, `useAvatarSession()` and `AvatarStage` expose the same
+lower-level pieces. Most apps should prefer `useRealtimeAvatar()` and
+`RealtimeAvatarView`.
+
+Two latency behaviors are on by default and need no configuration: playout is
+**adaptive** — audio starts the instant the first video frame is decodable
+instead of after a fixed buffer delay (pass `new AvatarPlayer({ playoutDelayMs:
+360 })` to pin the legacy fixed delay) — and the session socket sends idle
+keepalive pings every 25 s so the warm GPU session can't be silently dropped
+by proxies between turns (`keepAliveIntervalMs: 0` disables).
+
+### Idle clips: boomerang playback
+
+Idle/ambient clips are plain image-to-video generations whose first and last
+frames differ, so a hard `<video loop>` jumps at the wrap. Drive them with the
+SDK's ping-pong helper instead — forward, then smoothly reversed — and any clip
+loops seamlessly:
+
+```ts
+import { attachBoomerangPlayback } from "realtime-avatar/browser";
+
+const playback = attachBoomerangPlayback(idleVideoEl); // muted + playsInline
+// later: playback.stop();
+```
+
+### Vocal delivery: emotion, speed, volume
+
+Turns accept `emotion`, `speed` (0.6–1.5), and `volume` (0.5–2.0) as rough
+delivery multipliers. `speak_text` transcripts may also embed Cartesia inline
+tags — `<emotion value="excited"/>`, `<speed ratio="1.2"/>`,
+`<volume ratio="0.8"/>`, `[laughter]` — which are honored by TTS but stripped
+from the `text_delta`/`text_done` events your UI renders. In `chat` mode the
+LLM is already prompted to use these tags sparingly on its own.
+
+## Server-side with a trusted key
+
+```ts
+import { RealtimeAvatarClient } from "realtime-avatar";
+
+const client = RealtimeAvatarClient.platform({
+  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
+});
+
+await client.prepare({ avatar_id: "ava_..." });
+const stream = await client.turn({ avatar_id: "ava_...", mode: "speak_text", text: "Hi!" });
+```
+
+## Create avatars
+
+```ts
+const image = await fetch("https://example.com/face.png").then((res) => res.blob());
+const { avatar } = await client.createImageAvatar({ displayName: "Mira", image });
+
+const videoAvatar = await client.createVideoAvatarFromUrl({
+  displayName: "Source video Mira",
+  videoUrl: "https://example.com/idle.mp4",
+  videoCache: { keyframe_stride: 5 },
+});
+```
+
+## Pricing summary
+
+- Sandbox: free, 5 realtime minutes, 1 cached avatar.
+- Developer: $49/mo, 600 realtime minutes (10 hours), $0.085/min overage (~$5.10/hour).
+- Studio: $249/mo, 3,000 realtime minutes (50 hours), $0.08/min overage ($4.80/hour).
+- Scale: $999/mo, 13,000 realtime minutes (~216 hours), $0.07/min overage ($4.20/hour).
+- Avatar creation beyond included quotas is $1/avatar on paid plans.
+
+## Streaming protocol
+
+`turn()` streams a compact `application/x-avatar-mux` body with interleaved text, PCM audio, and JPEG/I420 video frames. `AvatarPlayer` decodes and plays it with an audio-clocked render loop. `readAvatarMux` exposes the raw event iterator if you want to handle frames yourself.
+
+## Agent resources
+
+This package ships `AGENTS.md` and `CLAUDE.md` for coding agents. Machine-readable platform references are available at:
+
+- Docs: https://realtimeavatar.ai/docs
+- API guide: https://realtimeavatar.ai/llms.txt
+- OpenAPI 3.1: https://realtimeavatar.ai/openapi.json
+- Remote MCP server: https://realtimeavatar.ai/api/mcp
+
+## License
+
+MIT

package/dist/api-keys.d.ts

@@ -0,0 +1,26 @@
+export type RealtimeAvatarApiKeyEnvironment = "live" | "test";
+export type ParsedRealtimeAvatarApiKey = {
+    readonly raw: string;
+    readonly prefix: "tic_live" | "tic_test";
+    readonly environment: RealtimeAvatarApiKeyEnvironment;
+    readonly keyId: string;
+    readonly secret: string;
+    readonly redacted: string;
+};
+export type RealtimeAvatarApiKeyErrorCode = "empty_key" | "invalid_prefix" | "missing_key_id" | "missing_secret" | "invalid_format" | "revoked_key";
+export declare class RealtimeAvatarApiKeyError extends Error {
+    readonly code: RealtimeAvatarApiKeyErrorCode;
+    constructor(code: RealtimeAvatarApiKeyErrorCode, message: string);
+}
+export declare function parseRealtimeAvatarApiKey(apiKey: string): ParsedRealtimeAvatarApiKey;
+export declare function redactRealtimeAvatarApiKey(apiKey: string | ParsedRealtimeAvatarApiKey): string;
+export declare function assertRealtimeAvatarApiKeyActive(apiKey: string | ParsedRealtimeAvatarApiKey, options?: {
+    revokedKeyIds?: ReadonlySet<string> | readonly string[];
+}): ParsedRealtimeAvatarApiKey;
+export declare function hashRealtimeAvatarApiKey(apiKey: string, options?: {
+    pepper?: string | Uint8Array;
+}): Promise<string>;
+export declare function verifyRealtimeAvatarApiKeyHash(apiKey: string, expectedHash: string, options?: {
+    pepper?: string | Uint8Array;
+}): Promise<boolean>;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../src/api-keys.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,+BAA+B,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,+BAA+B,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,CAAC;AAElB,qBAAa,yBAA0B,SAAQ,KAAK;IAEhD,QAAQ,CAAC,IAAI,EAAE,6BAA6B;gBAAnC,IAAI,EAAE,6BAA6B,EAC5C,OAAO,EAAE,MAAM;CAKlB;AAKD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,0BAA0B,CA8BpF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,0BAA0B,GAAG,MAAM,CAG9F;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,GAAG,0BAA0B,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAA;CAAO,GACxE,0BAA0B,CAO5B;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAAO,GAC7C,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAAO,GAC7C,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/api-keys.js

@@ -0,0 +1,88 @@
+export class RealtimeAvatarApiKeyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RealtimeAvatarApiKeyError";
+    }
+}
+const API_KEY_PATTERN = /^(tic_(live|test))_([A-Za-z0-9]{8,64})_([A-Za-z0-9_-]{24,256})$/;
+const TEXT_ENCODER = new TextEncoder();
+export function parseRealtimeAvatarApiKey(apiKey) {
+    const raw = apiKey.trim();
+    if (!raw)
+        throw new RealtimeAvatarApiKeyError("empty_key", "Realtime Avatar API key is required");
+    const match = API_KEY_PATTERN.exec(raw);
+    if (match) {
+        const prefix = match[1];
+        const environment = match[2];
+        const keyId = match[3];
+        const secret = match[4];
+        return {
+            raw,
+            prefix,
+            environment,
+            keyId,
+            secret,
+            redacted: redactParts(prefix, keyId, secret),
+        };
+    }
+    if (!raw.startsWith("tic_live_") && !raw.startsWith("tic_test_")) {
+        throw new RealtimeAvatarApiKeyError("invalid_prefix", "Realtime Avatar API keys must start with tic_live_ or tic_test_");
+    }
+    if (/^tic_(?:live|test)__/.test(raw)) {
+        throw new RealtimeAvatarApiKeyError("missing_key_id", "Realtime Avatar API key is missing its key id");
+    }
+    if (/^tic_(?:live|test)_[A-Za-z0-9]{8,64}_?$/.test(raw)) {
+        throw new RealtimeAvatarApiKeyError("missing_secret", "Realtime Avatar API key is missing its secret");
+    }
+    throw new RealtimeAvatarApiKeyError("invalid_format", "Realtime Avatar API key format is invalid");
+}
+export function redactRealtimeAvatarApiKey(apiKey) {
+    const parsed = typeof apiKey === "string" ? parseRealtimeAvatarApiKey(apiKey) : apiKey;
+    return parsed.redacted;
+}
+export function assertRealtimeAvatarApiKeyActive(apiKey, options = {}) {
+    const parsed = typeof apiKey === "string" ? parseRealtimeAvatarApiKey(apiKey) : apiKey;
+    const revoked = options.revokedKeyIds instanceof Set ? options.revokedKeyIds : new Set(options.revokedKeyIds ?? []);
+    if (revoked.has(parsed.keyId)) {
+        throw new RealtimeAvatarApiKeyError("revoked_key", "Realtime Avatar API key has been revoked");
+    }
+    return parsed;
+}
+export async function hashRealtimeAvatarApiKey(apiKey, options = {}) {
+    parseRealtimeAvatarApiKey(apiKey);
+    const bytes = TEXT_ENCODER.encode(apiKey.trim());
+    if (options.pepper) {
+        const key = await crypto.subtle.importKey("raw", copyBytes(pepperBytes(options.pepper)), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const digest = new Uint8Array(await crypto.subtle.sign("HMAC", key, copyBytes(bytes)));
+        return `hmac-sha256:${toHex(digest)}`;
+    }
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", copyBytes(bytes)));
+    return `sha256:${toHex(digest)}`;
+}
+export async function verifyRealtimeAvatarApiKeyHash(apiKey, expectedHash, options = {}) {
+    const actualHash = await hashRealtimeAvatarApiKey(apiKey, options);
+    return timingSafeEqual(actualHash, expectedHash);
+}
+function redactParts(prefix, keyId, secret) {
+    return `${prefix}_${keyId}...${secret.slice(-4)}`;
+}
+function pepperBytes(pepper) {
+    return typeof pepper === "string" ? TEXT_ENCODER.encode(pepper) : pepper;
+}
+function copyBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+function toHex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqual(left, right) {
+    let diff = left.length ^ right.length;
+    const maxLength = Math.max(left.length, right.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        diff |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+    }
+    return diff === 0;
+}
+//# sourceMappingURL=api-keys.js.map

package/dist/api-keys.js.map

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

package/dist/browser/audio.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Playout policy for the audio clock that everything else syncs to.
+ *
+ * - `number`: legacy fixed delay — playout starts `n` ms after the first audio
+ *   chunk arrives, regardless of whether video is ready.
+ * - `"adaptive"`: audio is HELD (buffered, not started) until the player
+ *   releases it — in practice the moment the first video frame is decodable —
+ *   then starts with a small jitter lead. Perceived first-frame latency drops
+ *   by whatever slack the fixed delay was padding (typically 250-400 ms),
+ *   and audio can never start before there is a frame to lip-sync against.
+ */
+export type PlayoutDelay = number | "adaptive";
+export type AdaptivePlayoutOptions = {
+    /** Scheduling lead once released, in ms. Absorbs event-loop/decode jitter. */
+    leadMs?: number;
+    /** Start anyway this long after the first audio chunk (audio-only turns, video stalls). */
+    maxHoldMs?: number;
+};
+export declare class Pcm16AudioScheduler {
+    private readonly sourceSampleRate;
+    /** Optional extra sink (e.g. a MediaStreamAudioDestinationNode recording
+     *  tap) that every scheduled buffer also connects to. Additive — speaker
+     *  output through `context.destination` is unchanged. */
+    private readonly extraDestination;
+    private context;
+    private nextStartTime;
+    private mediaStartTime;
+    private readonly minLeadSeconds;
+    /** When the context is owned externally (shared/unlocked on a gesture), we
+     *  must not close it on per-turn cleanup. */
+    private readonly ownsContext;
+    private readonly adaptive;
+    private readonly fixedDelayMs;
+    private readonly leadMs;
+    private readonly maxHoldMs;
+    /** False only while adaptive playout is holding buffered audio. */
+    private released;
+    private pending;
+    private pendingMs;
+    private holdTimer;
+    constructor(sourceSampleRate?: number, playoutDelay?: PlayoutDelay, sharedContext?: AudioContext | null, adaptiveOptions?: AdaptivePlayoutOptions, 
+    /** Optional extra sink (e.g. a MediaStreamAudioDestinationNode recording
+     *  tap) that every scheduled buffer also connects to. Additive — speaker
+     *  output through `context.destination` is unchanged. */
+    extraDestination?: AudioNode | null);
+    prepare(): Promise<void>;
+    get mediaTimeSeconds(): number | null;
+    get queuedMs(): number;
+    /**
+     * Release held audio (adaptive mode): anchor the media clock a small lead
+     * from now and start every buffered chunk back-to-back. The player calls
+     * this when the first video frame is decodable, so audio and video begin
+     * together at the earliest moment both exist. Idempotent; no-op in fixed
+     * mode (fixed playout self-starts on the first scheduled chunk).
+     */
+    startPlayout(): void;
+    schedule(pcm: Uint8Array<ArrayBufferLike>): Promise<{
+        durationMs: number;
+        queuedMs: number;
+        underrunMs: number;
+    }>;
+    private startBuffer;
+    close(): void;
+}
+//# sourceMappingURL=audio.d.ts.map

package/dist/browser/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../../src/browser/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/C,MAAM,MAAM,sBAAsB,GAAG;IACnC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAKF,qBAAa,mBAAmB;IAmB5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAIjC;;6DAEyD;IACzD,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAzBnC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC;iDAC6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAA8C;gBAG5C,gBAAgB,SAAS,EAC1C,YAAY,GAAE,YAAyB,EACvC,aAAa,CAAC,EAAE,YAAY,GAAG,IAAI,EACnC,eAAe,GAAE,sBAA2B;IAC5C;;6DAEyD;IACxC,gBAAgB,GAAE,SAAS,GAAG,IAAW;IAWtD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,IAAI,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAGpC;IAED,IAAI,QAAQ,IAAI,MAAM,CAIrB;IAED;;;;;;OAMG;IACH,YAAY,IAAI,IAAI;IAoBd,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC;QACxD,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IAyCF,OAAO,CAAC,WAAW;IAenB,KAAK,IAAI,IAAI;CAed"}