@spatialwalk/avatarkit-rtc 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -1,416 +1,8 @@
 # @spatialwalk/avatarkit-rtc
 
-Unified RTC adapter for avatarkit - supports LiveKit, Agora and other RTC providers.
+RTC adapter for [avatarkit](https://www.npmjs.com/package/@spatialwalk/avatarkit) - currently supports LiveKit and Agora.
 
-## Installation
-
-```bash
-pnpm add @spatialwalk/avatarkit-rtc
-```
-
-### Peer Dependencies
-
-根据使用的 RTC 提供商安装对应的 SDK：
-
-```bash
-# LiveKit
-pnpm add livekit-client
-
-# Agora
-pnpm add agora-rtc-sdk-ng
-```
-
-## Quick Start
-
-```typescript
-import { AvatarPlayer, LiveKitProvider, AgoraProvider } from '@spatialwalk/avatarkit-rtc';
-import { AvatarView, Avatar } from '@spatialwalk/avatarkit';
-
-// 1. 创建 Avatar 和 AvatarView（来自 avatarkit）
-const avatar = await Avatar.create(characterId);
-const avatarView = new AvatarView(avatar, container);
-
-// 2. 创建 Provider（选择 LiveKit 或 Agora）
-const provider = new LiveKitProvider();  // 或 new AgoraProvider()
-
-// 3. 创建 Player
-const player = new AvatarPlayer(provider, avatarView, {
-  logLevel: 'warning',  // 可选：设置日志级别
-});
-
-// 4. 连接到 RTC 服务器
-await player.connect({
-  url: 'wss://your-livekit-server.com',
-  token: 'your-token',
-  roomName: 'room-name',
-});
-
-// 5. 开始发布麦克风音频（用户说话）
-await player.startPublishing();
-
-// 6. 停止发布
-await player.stopPublishing();
-
-// 7. 断开连接
-await player.disconnect();
-```
-
-## API Reference
-
-### AvatarPlayer
-
-主入口类，统一管理 RTC 连接和 Avatar 渲染。
-
-#### Constructor
-
-```typescript
-new AvatarPlayer(provider: RTCProvider, avatarView: AvatarView, options?: AvatarPlayerOptions)
-```
-
-**参数：**
-
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| `provider` | `LiveKitProvider \| AgoraProvider` | RTC 提供商实例 |
-| `avatarView` | `AvatarView` | avatarkit 的 AvatarView 实例 |
-| `options` | `AvatarPlayerOptions` | 可选配置 |
-
-#### AvatarPlayerOptions
-
-```typescript
-interface AvatarPlayerOptions {
-  /** 开始说话过渡帧数，默认 5 (~200ms at 25fps) */
-  transitionStartFrameCount?: number;
-  
-  /** 结束说话过渡帧数，默认 40 (~1600ms at 25fps) */
-  transitionEndFrameCount?: number;
-  
-  /** 日志级别：'info' | 'warning' | 'error' | 'none'，默认 'warning' */
-  logLevel?: LogLevel;
-}
-```
-
-#### Properties
-
-| 属性 | 类型 | 描述 |
-|------|------|------|
-| `isConnected` | `boolean` | 是否已连接到 RTC 服务器 |
-
-#### Methods
-
-##### connect(config)
-
-连接到 RTC 服务器。
-
-```typescript
-await player.connect(config: RTCConnectionConfig): Promise<void>
-```
-
-**LiveKit 配置：**
-
-```typescript
-interface LiveKitConnectionConfig {
-  url: string;      // LiveKit 服务器 URL (wss://...)
-  token: string;    // 认证 Token
-  roomName: string; // 房间名称
-}
-```
-
-**Agora 配置：**
-
-```typescript
-interface AgoraConnectionConfig {
-  appId: string;    // Agora App ID
-  channel: string;  // 频道名称
-  token?: string;   // 认证 Token（生产环境必需）
-  uid?: number;     // 用户 ID（可选，0 = 自动分配）
-}
-```
-
-##### disconnect()
-
-断开 RTC 连接，清理所有资源。
-
-```typescript
-await player.disconnect(): Promise<void>
-```
-
-##### startPublishing()
-
-开始发布麦克风音频。会请求麦克风权限。
-
-```typescript
-await player.startPublishing(): Promise<void>
-```
-
-##### stopPublishing()
-
-停止发布麦克风音频。
-
-```typescript
-await player.stopPublishing(): Promise<void>
-```
-
-##### getConnectionState()
-
-获取当前连接状态。
-
-```typescript
-player.getConnectionState(): ConnectionState
-```
-
-**ConnectionState 枚举：**
-
-| 值 | 描述 |
-|----|------|
-| `'disconnected'` | 未连接 |
-| `'connecting'` | 正在连接 |
-| `'connected'` | 已连接 |
-| `'reconnecting'` | 正在重连 |
-| `'failed'` | 连接失败 |
-
-##### getNativeClient()
-
-获取底层 RTC 客户端对象，用于访问平台特定功能。
-
-```typescript
-player.getNativeClient(): unknown
-```
-
-**返回值：**
-
-| Provider | 返回类型 |
-|----------|---------|
-| LiveKit | `Room` 实例（SDK 导出为 `LiveKitRoom`） |
-| Agora | `IAgoraRTCClient` 实例（SDK 导出为 `AgoraClient`） |
-
-**类型安全说明：**
-
-- **直接使用 Provider**：返回具体类型，无需断言
-- **通过 AvatarPlayer 使用**：返回 `unknown`，需要手动类型断言
-
-**示例：**
-
-```typescript
-// 方式 1：直接使用 Provider（推荐，有完整类型提示）
-import { LiveKitProvider, LiveKitRoom } from '@spatialwalk/avatarkit-rtc';
-
-const provider = new LiveKitProvider();
-const room = provider.getNativeClient();  // 类型: LiveKitRoom | null
-console.log('远程参与者数量:', room?.remoteParticipants.size);
-
-// 方式 2：通过 AvatarPlayer 使用（需手动断言）
-import { AvatarPlayer, LiveKitRoom } from '@spatialwalk/avatarkit-rtc';
-
-const room = player.getNativeClient() as LiveKitRoom | null;
-console.log('远程参与者数量:', room?.remoteParticipants.size);
-
-// Agora 示例
-import { AgoraProvider, AgoraClient } from '@spatialwalk/avatarkit-rtc';
-
-const provider = new AgoraProvider();
-const client = provider.getNativeClient();  // 类型: AgoraClient | null
-console.log('连接状态:', client?.connectionState);
-```
-
-##### on(event, handler)
-
-监听事件。
-
-```typescript
-player.on(event: string, handler: Function): void
-```
-
-**支持的事件：**
-
-| 事件名 | 回调参数 | 描述 |
-|--------|----------|------|
-| `'connected'` | `()` | 连接成功 |
-| `'disconnected'` | `()` | 连接断开 |
-| `'error'` | `(error: Error)` | 发生错误 |
-| `'connection-state-changed'` | `(state: ConnectionState)` | 连接状态变化 |
-
-##### off(event, handler)
-
-移除事件监听。
-
-```typescript
-player.off(event: string, handler: Function): void
-```
-
----
-
-### LiveKitProvider
-
-LiveKit RTC 提供商实现。
-
-```typescript
-import { LiveKitProvider } from '@spatialwalk/avatarkit-rtc';
-
-const provider = new LiveKitProvider();
-```
-
----
-
-### AgoraProvider
-
-Agora RTC 提供商实现。
-
-```typescript
-import { AgoraProvider } from '@spatialwalk/avatarkit-rtc';
-
-const provider = new AgoraProvider({
-  debugLogging: true,  // 可选：启用调试日志
-});
-```
-
-**AgoraProviderOptions：**
-
-```typescript
-interface AgoraProviderOptions {
-  /** 启用详细调试日志，默认 false */
-  debugLogging?: boolean;
-}
-```
-
----
-
-### Type Guards
-
-类型守卫函数，用于判断配置类型。
-
-```typescript
-import { isLiveKitConfig, isAgoraConfig } from '@spatialwalk/avatarkit-rtc';
-
-if (isLiveKitConfig(config)) {
-  // config 是 LiveKitConnectionConfig
-}
-
-if (isAgoraConfig(config)) {
-  // config 是 AgoraConnectionConfig
-}
-```
-
----
-
-### Native Client Types
-
-SDK 导出了底层 RTC 客户端的类型别名，方便在使用 `getNativeClient()` 时获得类型支持：
-
-```typescript
-import type { LiveKitRoom, AgoraClient } from '@spatialwalk/avatarkit-rtc';
-
-// LiveKitRoom = livekit-client 的 Room 类型
-// AgoraClient = agora-rtc-sdk-ng 的 IAgoraRTCClient 类型
-```
-
----
-
-## Log Levels
-
-SDK 日志级别通过 `AvatarPlayerOptions.logLevel` 配置：
-
-| Level | 输出内容 |
-|-------|---------|
-| `'info'` | 所有日志（连接状态、帧处理、调试信息） |
-| `'warning'` | 警告 + 错误（**默认**） |
-| `'error'` | 只有错误 |
-| `'none'` | 禁用所有日志 |
-
-```typescript
-const player = new AvatarPlayer(provider, avatarView, {
-  logLevel: 'info',  // 调试时启用
-});
-```
-
----
-
-## Complete Example
-
-### LiveKit 接入
-
-```typescript
-import { AvatarPlayer, LiveKitProvider } from '@spatialwalk/avatarkit-rtc';
-import { AvatarView, Avatar } from '@spatialwalk/avatarkit';
-
-async function initLiveKit() {
-  // 初始化 Avatar
-  const avatar = await Avatar.create('character-id');
-  const container = document.getElementById('avatar-container')!;
-  const avatarView = new AvatarView(avatar, container);
-
-  // 创建 Player
-  const provider = new LiveKitProvider();
-  const player = new AvatarPlayer(provider, avatarView, {
-    logLevel: 'info',
-    transitionStartFrameCount: 5,
-    transitionEndFrameCount: 40,
-  });
-
-  // 监听事件
-  player.on('connected', () => console.log('Connected!'));
-  player.on('disconnected', () => console.log('Disconnected!'));
-  player.on('error', (err) => console.error('Error:', err));
-
-  // 连接
-  await player.connect({
-    url: 'wss://your-livekit-server.com',
-    token: 'your-token',
-    roomName: 'my-room',
-  });
-
-  // 开始说话
-  await player.startPublishing();
-
-  // 停止说话
-  // await player.stopPublishing();
-
-  // 断开
-  // await player.disconnect();
-}
-```
-
-### Agora 接入
-
-```typescript
-import { AvatarPlayer, AgoraProvider } from '@spatialwalk/avatarkit-rtc';
-import { AvatarView, Avatar } from '@spatialwalk/avatarkit';
-
-async function initAgora() {
-  // 初始化 Avatar
-  const avatar = await Avatar.create('character-id');
-  const container = document.getElementById('avatar-container')!;
-  const avatarView = new AvatarView(avatar, container);
-
-  // 创建 Player
-  const provider = new AgoraProvider({ debugLogging: true });
-  const player = new AvatarPlayer(provider, avatarView);
-
-  // 连接
-  await player.connect({
-    appId: 'your-agora-app-id',
-    channel: 'my-channel',
-    token: 'your-token',  // 生产环境必需
-    uid: 0,  // 0 = 自动分配
-  });
-
-  // 开始说话
-  await player.startPublishing();
-}
-```
-
----
-
-## Browser Compatibility
-
-| Feature | Chrome | Firefox | Safari | Edge |
-|---------|--------|---------|--------|------|
-| LiveKit (VP8 + RTCRtpScriptTransform) | ✅ 94+ | ✅ 117+ | ❌ | ✅ 94+ |
-| Agora (H.264 + SEI) | ✅ 74+ | ✅ 78+ | ✅ 14.1+ | ✅ 79+ |
-
-**注意：** LiveKit 需要浏览器支持 `RTCRtpScriptTransform` API。
-
----
+📚 **Documentation**: [https://docs.spatialreal.ai/guide/rtc-mode](https://docs.spatialreal.ai/guide/rtc-mode)
 
 ## License
 

package/dist/assets/animation-worker-DOGeTjF0.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-worker-DOGeTjF0.js","sources":["../src/providers/livekit/animation-worker.ts"],"sourcesContent":["/**\n * RTCRtpScriptTransform Worker for Animation Track (VP8 Video)\n *\n * This worker handles extracting animation data from VP8 video frames.\n * The server prepends a minimal VP8 header to trick the browser's depacketizer.\n *\n * Frame format after depacketization (VP8 descriptor is stripped by depacketizer):\n * [0-9]     VP8 frame header (10 bytes) - minimal keyframe structure, skipped\n * [10]      flags (uint8) - packet flags\n * [11-14]   msgLen (little-endian u32) - length of protobuf message\n * [15..15+msgLen)  protobuf Message binary\n */\n\n// Type declarations for RTCRtpScriptTransform API (experimental)\ndeclare interface RTCTransformEvent extends Event {\n  transformer: {\n    readable: ReadableStream;\n    writable: WritableStream;\n    options?: unknown;\n  };\n}\n\n// Worker global scope with RTCRtpScriptTransform support\ndeclare const self: DedicatedWorkerGlobalScope & {\n  onrtctransform?: ((event: RTCTransformEvent) => void) | null;\n};\n\n// VP8 header size (frame tag + sync code + dimensions, descriptor already stripped)\nconst VP8_FRAME_HEADER_SIZE = 10;\n\n// Protocol constants (must match egress-server/metadata_track.go)\nconst METADATA_FIXED_HEADER_SIZE = 5; // 1B flags + 4B length\n\n// Packet flags\nconst PACKET_FLAG_IDLE = 0x01;\nconst PACKET_FLAG_START = 0x02;\nconst PACKET_FLAG_END = 0x04;\nconst PACKET_FLAG_GZIPPED = 0x08;\nconst PACKET_FLAG_TRANSITION = 0x10; // Transition packet - contains target frame for generating transition from idle\nconst PACKET_FLAG_TRANSITION_END = 0x20; // Transition end packet - contains last frame for generating transition back to idle\nconst PACKET_FLAG_REDUNDANT = 0x40; // Packet contains redundant previous frame for ALR loss recovery\n\ninterface FrameMetadata {\n  flags: number;\n  protobufLength: number;\n  protobufData: Uint8Array;\n  // ALR (Application-Level Redundancy) data\n  hasRedundant: boolean;\n  redundantLength: number;\n  redundantData: Uint8Array | null;\n}\n\ninterface TransformOptions {\n  operation: 'receiver';\n}\n\n// State for receiver\nlet receiverMetaCount = 0;\nlet lastLogTime = 0;\nlet totalFrames = 0;\nlet framesWithMeta = 0;\nlet wasIdle = false; // Track idle state for transition detection\nlet isInStartTransition = false; // Dedup consecutive transition-start packets\nlet isInEndTransition = false; // Dedup consecutive transition-end packets\n\n// ALR (Application-Level Redundancy) state for loss detection\nlet lastReceivedTimestamp: number | null = null;\nlet framesRecovered = 0;\nlet framesLost = 0;\n// Expected timestamp increment per animation frame (90000 Hz * 40ms = 3600)\n// Animation is sent every 2nd audio frame (40ms intervals)\nconst EXPECTED_TIMESTAMP_INCREMENT = 3600;\n\n// Sequence tracking for out-of-order detection\nlet lastRenderedSeq: number = -1; // Last sequence number sent to main thread\nlet framesOutOfOrder = 0; // Count of out-of-order frames detected\nlet framesDuplicate = 0; // Count of duplicate frames skipped\nlet framesDropped = 0; // Count of frames that were permanently lost (gaps in sequence)\nlet framesSent = 0; // Total frames successfully sent to main thread\n\nfunction parseMetadataHeader(\n  data: Uint8Array,\n): { meta: FrameMetadata; headerSize: number } | null {\n  if (data.byteLength < METADATA_FIXED_HEADER_SIZE) return null;\n  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);\n  const flags = data[0];\n  const msgLen = view.getUint32(1, true); // little-endian\n\n  // Calculate minimum size needed\n  const headerSize = METADATA_FIXED_HEADER_SIZE + msgLen;\n  if (data.byteLength < headerSize) return null;\n\n  // The compressed payload (will be decompressed later)\n  const compressedData = data.slice(\n    METADATA_FIXED_HEADER_SIZE,\n    METADATA_FIXED_HEADER_SIZE + msgLen,\n  );\n\n  // Note: With the new ALR optimization, both frames are gzipped together\n  // The format INSIDE the gzip (after decompression) is:\n  // - ALR: [currentLen (4B)][currentData][prevLen (4B)][prevData]\n  // - Non-ALR: just the raw protobuf data\n  // We return the compressed data here; decompression and ALR parsing happens in receiverTransform\n\n  const hasRedundant = (flags & PACKET_FLAG_REDUNDANT) !== 0;\n\n  return {\n    meta: {\n      flags,\n      protobufLength: msgLen,\n      protobufData: compressedData, // This is still compressed at this point\n      hasRedundant,\n      redundantLength: 0, // Will be determined after decompression\n      redundantData: null, // Will be extracted after decompression\n    },\n    headerSize,\n  };\n}\n\nfunction isIdlePacket(flags: number): boolean {\n  return (flags & PACKET_FLAG_IDLE) !== 0;\n}\n\nfunction isStartPacket(flags: number): boolean {\n  return (flags & PACKET_FLAG_START) !== 0;\n}\n\nfunction isEndPacket(flags: number): boolean {\n  return (flags & PACKET_FLAG_END) !== 0;\n}\n\nfunction isGzipped(flags: number): boolean {\n  return (flags & PACKET_FLAG_GZIPPED) !== 0;\n}\n\nfunction isTransitionPacket(flags: number): boolean {\n  return (flags & PACKET_FLAG_TRANSITION) !== 0;\n}\n\nfunction isTransitionEndPacket(flags: number): boolean {\n  return (flags & PACKET_FLAG_TRANSITION_END) !== 0;\n}\n\n// Decompress gzipped data using DecompressionStream API\nasync function decompressGzip(data: Uint8Array): Promise<Uint8Array> {\n  const ds = new DecompressionStream('gzip');\n  const writer = ds.writable.getWriter();\n  // Create a copy to ensure we have a plain ArrayBuffer, not SharedArrayBuffer\n  const copy = new Uint8Array(data);\n  writer.write(copy);\n  writer.close();\n\n  const reader = ds.readable.getReader();\n  const chunks: Uint8Array[] = [];\n  let totalLength = 0;\n\n  while (true) {\n    const { done, value } = await reader.read();\n    if (done) break;\n    chunks.push(value);\n    totalLength += value.length;\n  }\n\n  const result = new Uint8Array(totalLength);\n  let offset = 0;\n  for (const chunk of chunks) {\n    result.set(chunk, offset);\n    offset += chunk.length;\n  }\n\n  return result;\n}\n\n// Compression stats for logging\nlet totalCompressedBytes = 0;\nlet totalUncompressedBytes = 0;\n\n// ALR payload structure after decompression\ninterface ALRPayload {\n  frameSeq: number; // Sequence number of current frame\n  currentData: Uint8Array; // Current frame (N)\n  prev1Data: Uint8Array | null; // Previous frame (N-1)\n  prev2Data: Uint8Array | null; // Frame before previous (N-2)\n}\n\n// Parse ALR payload after decompression\n// ALR format: [frameSeq (4B)][currentLen (4B)][currentData][prev1Len (4B)][prev1Data][prev2Len (4B)][prev2Data]\n// Non-ALR format: [frameSeq (4B)][raw protobuf data]\n// Returns { frameSeq, currentData, prev1Data, prev2Data } or null if parsing fails\nfunction parseALRPayload(\n  decompressed: Uint8Array,\n  hasRedundant: boolean,\n): ALRPayload | null {\n  if (decompressed.byteLength < 4) return null;\n\n  const view = new DataView(\n    decompressed.buffer,\n    decompressed.byteOffset,\n    decompressed.byteLength,\n  );\n  let offset = 0;\n\n  // Parse frame sequence number\n  const frameSeq = view.getUint32(offset, true);\n  offset += 4;\n\n  if (!hasRedundant) {\n    // Non-ALR: rest is raw protobuf\n    const currentData = decompressed.slice(offset);\n    return { frameSeq, currentData, prev1Data: null, prev2Data: null };\n  }\n\n  // ALR format: parse current frame\n  if (decompressed.byteLength < offset + 4) return null;\n  const currentLen = view.getUint32(offset, true);\n  offset += 4;\n  if (decompressed.byteLength < offset + currentLen) return null;\n  const currentData = decompressed.slice(offset, offset + currentLen);\n  offset += currentLen;\n\n  // Parse prev1 (N-1) if available\n  let prev1Data: Uint8Array | null = null;\n  if (decompressed.byteLength >= offset + 4) {\n    const prev1Len = view.getUint32(offset, true);\n    offset += 4;\n    if (prev1Len > 0 && decompressed.byteLength >= offset + prev1Len) {\n      prev1Data = decompressed.slice(offset, offset + prev1Len);\n      offset += prev1Len;\n    }\n  }\n\n  // Parse prev2 (N-2) if available\n  let prev2Data: Uint8Array | null = null;\n  if (decompressed.byteLength >= offset + 4) {\n    const prev2Len = view.getUint32(offset, true);\n    offset += 4;\n    if (prev2Len > 0 && decompressed.byteLength >= offset + prev2Len) {\n      prev2Data = decompressed.slice(offset, offset + prev2Len);\n    }\n  }\n\n  return { frameSeq, currentData, prev1Data, prev2Data };\n}\n\n// Helper to send animation data to main thread with sequence tracking\n// Returns true if frame was sent, false if skipped (duplicate/out-of-order)\nfunction sendAnimationToMainThread(\n  protobufData: Uint8Array,\n  flags: number,\n  frameSeq: number,\n  isRecovered: boolean = false,\n): boolean {\n  const isIdle = isIdlePacket(flags);\n  const isStart = isStartPacket(flags);\n  const isEnd = isEndPacket(flags);\n\n  // Check for out-of-order or duplicate frames\n  if (frameSeq <= lastRenderedSeq && lastRenderedSeq !== -1 && !isStart) {\n    if (frameSeq === lastRenderedSeq) {\n      framesDuplicate++;\n    } else {\n      framesOutOfOrder++;\n    }\n    return false;\n  }\n\n  // Check for gap (frames we never received and couldn't recover) - these are DROPPED\n  if (lastRenderedSeq !== -1 && frameSeq > lastRenderedSeq + 1 && !isStart) {\n    const gap = frameSeq - lastRenderedSeq - 1;\n    framesDropped += gap;\n  }\n\n  framesSent++;\n\n  lastRenderedSeq = frameSeq;\n\n  const protobufBuffer = new ArrayBuffer(protobufData.byteLength);\n  new Uint8Array(protobufBuffer).set(protobufData);\n\n  self.postMessage(\n    {\n      type: 'animation',\n      flags,\n      isIdle,\n      isStart,\n      isEnd,\n      isRecovered,\n      frameSeq,\n      protobufData: protobufBuffer,\n    },\n    { transfer: [protobufBuffer] },\n  );\n\n  return true;\n}\n\n// Receiver transform: extract animation data from video frames\n// Uses ALR (Application-Level Redundancy) to recover lost frames\nfunction receiverTransform(\n  frame: RTCEncodedVideoFrame,\n  _controller: TransformStreamDefaultController<RTCEncodedVideoFrame>,\n) {\n  totalFrames++;\n  const data = new Uint8Array(frame.data);\n  const currentTimestamp = frame.timestamp;\n\n  // Skip the VP8 frame header (10 bytes) - the VP8 descriptor is already stripped by depacketizer\n  // Check if we have enough data for VP8 header + at least 1 byte of animation data\n  if (data.length <= VP8_FRAME_HEADER_SIZE) {\n    return; // Frame too small, skip\n  }\n\n  // Extract animation data after VP8 header\n  const animData = data.subarray(VP8_FRAME_HEADER_SIZE);\n\n  const parsed = parseMetadataHeader(animData);\n\n  if (parsed) {\n    const { meta } = parsed;\n    framesWithMeta++;\n    receiverMetaCount++;\n\n    const isIdle = isIdlePacket(meta.flags);\n    const isStart = isStartPacket(meta.flags);\n    const isEnd = isEndPacket(meta.flags);\n\n    // ALR: Detect frame loss and recover using redundant data\n    // Check if we missed frames by looking at timestamp gap\n    if (lastReceivedTimestamp !== null && !isIdle && !isStart) {\n      const timestampDelta = currentTimestamp - lastReceivedTimestamp;\n      // Allow some tolerance (1.5x expected increment) for timing variations\n      if (timestampDelta > EXPECTED_TIMESTAMP_INCREMENT * 1.5) {\n        const missedFrames =\n          Math.round(timestampDelta / EXPECTED_TIMESTAMP_INCREMENT) - 1;\n        framesLost += missedFrames;\n\n        // Try to recover using redundant data from current packet\n        // With ALR optimization, up to 3 frames are gzipped together\n        if (meta.hasRedundant && isGzipped(meta.flags)) {\n          // Decompress to get all frames, then recover\n          totalCompressedBytes += meta.protobufData.byteLength;\n\n          decompressGzip(meta.protobufData)\n            .then((decompressed) => {\n              totalUncompressedBytes += decompressed.byteLength;\n\n              const parsed = parseALRPayload(decompressed, true);\n              if (parsed) {\n                const currentSeq = parsed.frameSeq;\n\n                // Determine how many frames we can recover based on how many were lost\n                // and how many redundant frames we have\n                const framesToRecover: Array<{\n                  data: Uint8Array;\n                  seq: number;\n                }> = [];\n\n                if (missedFrames >= 2 && parsed.prev2Data) {\n                  framesToRecover.push({\n                    data: parsed.prev2Data,\n                    seq: currentSeq - 2,\n                  });\n                }\n                if (missedFrames >= 1 && parsed.prev1Data) {\n                  framesToRecover.push({\n                    data: parsed.prev1Data,\n                    seq: currentSeq - 1,\n                  });\n                }\n\n                const recovered = framesToRecover.length;\n                if (recovered > 0) {\n                  framesRecovered += recovered;\n\n                  // Send recovered frames in chronological order (oldest first)\n                  for (const frame of framesToRecover) {\n                    sendAnimationToMainThread(\n                      frame.data,\n                      meta.flags & ~PACKET_FLAG_REDUNDANT,\n                      frame.seq,\n                      true,\n                    );\n                  }\n                }\n\n                // Then send current frame\n                sendAnimationToMainThread(\n                  parsed.currentData,\n                  meta.flags & ~PACKET_FLAG_REDUNDANT,\n                  currentSeq,\n                  false,\n                );\n              }\n            })\n            .catch((err) => {\n              console.error(`[Animation Worker] ALR decompression error:`, err);\n            });\n\n          // Update timestamp and return early (we've handled this frame)\n          lastReceivedTimestamp = currentTimestamp;\n          return;\n        }\n      }\n    }\n\n    // Update last received timestamp (skip for idle packets to avoid false loss detection)\n    if (!isIdle) {\n      lastReceivedTimestamp = currentTimestamp;\n    }\n\n    // Reset state on session start\n    if (isStart) {\n      lastReceivedTimestamp = currentTimestamp;\n      framesRecovered = 0;\n      framesLost = 0;\n      lastRenderedSeq = -1;\n      framesOutOfOrder = 0;\n      framesDuplicate = 0;\n      framesDropped = 0;\n      framesSent = 0;\n    }\n\n    const isTransition = isTransitionPacket(meta.flags);\n    const isTransitionEnd = isTransitionEndPacket(meta.flags);\n\n    if (isIdle) {\n      // First idle packet - post idleStart event\n      if (!wasIdle) {\n        self.postMessage({ type: 'idleStart' });\n        wasIdle = true;\n      }\n      isInStartTransition = false;\n      isInEndTransition = false;\n    } else if (isTransition && meta.protobufLength > 0) {\n      // Transition packet - contains target frame for smooth transition from idle\n      wasIdle = false;\n\n      // Dedup: only emit first packet in a consecutive transition-start run.\n      if (!isInStartTransition) {\n        isInStartTransition = true;\n        isInEndTransition = false;\n\n        // Decompress if gzipped (transition packets are always gzipped)\n        const gzipped = isGzipped(meta.flags);\n        if (gzipped) {\n          totalCompressedBytes += meta.protobufData.byteLength;\n\n          decompressGzip(meta.protobufData)\n            .then((decompressed) => {\n              totalUncompressedBytes += decompressed.byteLength;\n\n              const protobufBuffer = new ArrayBuffer(decompressed.byteLength);\n              new Uint8Array(protobufBuffer).set(decompressed);\n\n              // Post transition event - main thread will generate transition frames\n              self.postMessage(\n                {\n                  type: 'transition',\n                  flags: meta.flags,\n                  protobufData: protobufBuffer,\n                },\n                { transfer: [protobufBuffer] },\n              );\n            })\n            .catch((err) => {\n              console.error(\n                `[Animation Worker] Gzip decompress error (transition):`,\n                err,\n              );\n            });\n        } else {\n          const protobufBuffer = new ArrayBuffer(meta.protobufData.byteLength);\n          new Uint8Array(protobufBuffer).set(meta.protobufData);\n\n          self.postMessage(\n            {\n              type: 'transition',\n              flags: meta.flags,\n              protobufData: protobufBuffer,\n            },\n            { transfer: [protobufBuffer] },\n          );\n        }\n      }\n    } else if (isTransitionEnd && meta.protobufLength > 0) {\n      // Transition end packet - contains last frame for smooth transition back to idle\n\n      // Dedup: only emit first packet in a consecutive transition-end run.\n      if (!isInEndTransition) {\n        isInEndTransition = true;\n        isInStartTransition = false;\n\n        // Decompress if gzipped (transition end packets are always gzipped)\n        const gzipped = isGzipped(meta.flags);\n        if (gzipped) {\n          totalCompressedBytes += meta.protobufData.byteLength;\n\n          decompressGzip(meta.protobufData)\n            .then((decompressed) => {\n              totalUncompressedBytes += decompressed.byteLength;\n\n              const protobufBuffer = new ArrayBuffer(decompressed.byteLength);\n              new Uint8Array(protobufBuffer).set(decompressed);\n\n              // Post transition end event - main thread will generate reverse transition frames\n              self.postMessage(\n                {\n                  type: 'transitionEnd',\n                  flags: meta.flags,\n                  protobufData: protobufBuffer,\n                },\n                { transfer: [protobufBuffer] },\n              );\n            })\n            .catch((err) => {\n              console.error(\n                `[Animation Worker] Gzip decompress error (transitionEnd):`,\n                err,\n              );\n            });\n        } else {\n          const protobufBuffer = new ArrayBuffer(meta.protobufData.byteLength);\n          new Uint8Array(protobufBuffer).set(meta.protobufData);\n\n          self.postMessage(\n            {\n              type: 'transitionEnd',\n              flags: meta.flags,\n              protobufData: protobufBuffer,\n            },\n            { transfer: [protobufBuffer] },\n          );\n        }\n      }\n    } else if (meta.protobufLength > 0) {\n      // Normal animation packet\n      // Transition from idle to streaming (if not already transitioned via transition packet)\n      if (wasIdle) {\n        wasIdle = false;\n      }\n      isInStartTransition = false;\n      isInEndTransition = false;\n\n      // Decompress if gzipped\n      const gzipped = isGzipped(meta.flags);\n      if (gzipped) {\n        // Track compression stats\n        totalCompressedBytes += meta.protobufData.byteLength;\n\n        // Async decompression\n        decompressGzip(meta.protobufData)\n          .then((decompressed) => {\n            totalUncompressedBytes += decompressed.byteLength;\n\n            // Parse ALR format to get frame sequence and data\n            // Format: [frameSeq (4B)][currentLen (4B)][currentData]... or [frameSeq (4B)][raw protobuf]\n            const parsed = parseALRPayload(decompressed, meta.hasRedundant);\n            if (parsed) {\n              sendAnimationToMainThread(\n                parsed.currentData,\n                meta.flags & ~PACKET_FLAG_REDUNDANT,\n                parsed.frameSeq,\n                false,\n              );\n            }\n          })\n          .catch(() => {});\n      } else {\n        // Uncompressed - this shouldn't happen in normal operation but handle it\n        const protobufBuffer = new ArrayBuffer(meta.protobufData.byteLength);\n        new Uint8Array(protobufBuffer).set(meta.protobufData);\n\n        self.postMessage(\n          {\n            type: 'animation',\n            flags: meta.flags,\n            isIdle: false,\n            isStart,\n            isEnd,\n            frameSeq: -1, // Unknown sequence\n            protobufData: protobufBuffer,\n          },\n          { transfer: [protobufBuffer] },\n        );\n      }\n    }\n\n    // Report stats every second\n    const now = performance.now();\n    if (now - lastLogTime > 1000) {\n      lastLogTime = now;\n      self.postMessage({\n        type: 'metadata',\n        protobufLength: meta.protobufLength,\n        framesPerSec: receiverMetaCount,\n        totalFrames,\n        framesWithMeta,\n        framesLost,\n        framesRecovered,\n        totalCompressedBytes,\n        totalUncompressedBytes,\n        framesOutOfOrder,\n        framesDuplicate,\n        framesDropped,\n        framesSent,\n        lastRenderedSeq,\n      });\n      receiverMetaCount = 0;\n    }\n  }\n\n  // For video, we don't enqueue the frame since it's not real video\n  // The browser's VP8 decoder would fail on our custom data anyway\n  // controller.enqueue(frame);\n}\n\n// Handle rtctransform event (RTCRtpScriptTransform)\nself.onrtctransform = (event: RTCTransformEvent) => {\n  const transformer = event.transformer;\n  const options = transformer.options as TransformOptions;\n\n  try {\n    if (options.operation === 'receiver') {\n      // Reset state\n      receiverMetaCount = 0;\n      lastLogTime = 0;\n      totalFrames = 0;\n      framesWithMeta = 0;\n      wasIdle = false;\n      isInStartTransition = false;\n      isInEndTransition = false;\n      lastReceivedTimestamp = null;\n      framesRecovered = 0;\n      framesLost = 0;\n      lastRenderedSeq = -1;\n      framesOutOfOrder = 0;\n      framesDuplicate = 0;\n      framesDropped = 0;\n      framesSent = 0;\n\n      transformer.readable\n        .pipeThrough(new TransformStream({ transform: receiverTransform }))\n        .pipeTo(transformer.writable)\n        .catch((err: unknown) => {\n          console.error('[Animation Worker] Pipeline error:', err);\n          self.postMessage({\n            type: 'error',\n            error: `Animation receiver pipe error: ${err}`,\n          });\n        });\n\n      self.postMessage({ type: 'ready', operation: 'receiver' });\n    }\n  } catch (err) {\n    console.error('[Animation Worker] Setup error:', err);\n    self.postMessage({\n      type: 'error',\n      error: `Animation transform setup error: ${err}`,\n    });\n  }\n};\n\n// Handle message-based initialization for fallback\nself.onmessage = (event: MessageEvent) => {\n  const { type } = event.data;\n  if (type === 'init') {\n    self.postMessage({ type: 'initialized' });\n  }\n};\n\nexport {};\n"],"names":["currentData","parsed","frame"],"mappings":"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"}

package/dist/core/AvatarPlayer.d.ts

@@ -1,6 +1,5 @@
 import { RTCProvider } from './RTCProvider';
-import { RTCConnectionConfig } from '../types';
-import { RTCProviderEvents } from './types';
+import { RTCConnectionConfig, RTCPrepareConnectionConfig } from '../types';
 import { LogLevel } from '../utils';
 import { AvatarView } from '@spatialwalk/avatarkit';
 /**
@@ -15,6 +14,19 @@ export interface AvatarPlayerOptions {
      * - 'none': Disable all logs
      */
     logLevel?: LogLevel;
+    /**
+     * Enable jitter buffer for smoother animation playback.
+     * When enabled, frames are buffered and rendered in sequence order at a steady 25fps,
+     * absorbing network jitter and out-of-order delivery.
+     * Default: true
+     */
+    enableJitterBuffer?: boolean;
+    /**
+     * Maximum delay (in ms) a frame can sit in the jitter buffer before being rendered.
+     * Only used when enableJitterBuffer is true.
+     * Default: 80 (2 frames at 25fps)
+     */
+    maxBufferDelayMs?: number;
 }
 /**
  * Unified Avatar Player.
@@ -36,11 +48,20 @@ export interface AvatarPlayerOptions {
  * const provider = new LiveKitProvider();
  * const player = new AvatarPlayer(provider, avatarView);
  *
- * // Connect and start
+ * // Connect
  * await player.connect({ url: 'wss://...', token: '...' });
- * await player.startPublishing(); // Start microphone
  *
- * // Disconnect when done
+ * // Option 1: Use microphone (most common)
+ * await player.startPublishing();
+ * await player.stopPublishing();
+ *
+ * // Option 2: Use custom audio source
+ * const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+ * await player.publishAudio(stream.getAudioTracks()[0]);
+ * await player.unpublishAudio();
+ * stream.getTracks().forEach(t => t.stop());
+ *
+ * // Disconnect
  * await player.disconnect();
  * ```
  */
@@ -62,19 +83,67 @@ export declare class AvatarPlayer {
      * @throws Error if already connected or connection fails
      */
     connect(config: RTCConnectionConfig): Promise<void>;
+    /**
+     * Pre-warm a future RTC connection when the provider supports it.
+     * This is best-effort and does not change the connected state.
+     */
+    prepareConnection(config: RTCPrepareConnectionConfig): Promise<void>;
     /**
      * Disconnect from RTC server.
      * Stops all tracks and cleans up resources.
      */
     disconnect(): Promise<void>;
     /**
-     * Start publishing microphone audio to the RTC server.
-     * Requests microphone permission and starts publishing.
-     * @throws Error if permission denied or no microphone found
+     * Publish an audio track to the RTC server.
+     *
+     * The audio source is controlled externally - you can pass any audio track:
+     * - Microphone: `getUserMedia({ audio: true })`
+     * - Browser audio: `audioElement.captureStream()`
+     * - Web Audio API: `audioContext.createMediaStreamDestination().stream`
+     * - Screen share audio: `getDisplayMedia({ audio: true })`
+     *
+     * @param track - MediaStreamTrack to publish (must be an audio track)
+     * @throws Error if not connected or track is invalid
+     *
+     * @example
+     * ```typescript
+     * // Microphone
+     * const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+     * await player.publishAudio(stream.getAudioTracks()[0]);
+     *
+     * // Browser audio element
+     * const audioEl = document.querySelector('audio');
+     * const stream = audioEl.captureStream();
+     * await player.publishAudio(stream.getAudioTracks()[0]);
+     * ```
+     */
+    publishAudio(track: MediaStreamTrack): Promise<void>;
+    /**
+     * Stop publishing audio.
+     * Note: This does NOT stop the track - the caller is responsible for managing the track lifecycle.
+     */
+    unpublishAudio(): Promise<void>;
+    /**
+     * Start publishing microphone audio.
+     *
+     * This requests microphone permission and publishes it to the RTC session.
+     * For custom audio sources (e.g., audio files), use `publishAudio(track)` instead.
+     *
+     * @throws Error if not connected, permission denied, or no microphone found
+     *
+     * @example
+     * ```typescript
+     * await player.startPublishing();
+     * // ... later
+     * await player.stopPublishing();
+     * ```
      */
     startPublishing(): Promise<void>;
     /**
-     * Stop publishing microphone audio.
+     * Stop publishing microphone audio and release the microphone.
+     *
+     * This stops the microphone track and releases the device.
+     * If you used `publishAudio()` with a custom track, use `unpublishAudio()` instead.
      */
     stopPublishing(): Promise<void>;
     /**
@@ -105,15 +174,30 @@ export declare class AvatarPlayer {
     getNativeClient(): unknown;
     /**
      * Add event listener.
-     * @param event - Event name ('connected', 'disconnected', 'error', etc.)
+     * @param event - Event name ('connected', 'disconnected', 'error', 'stalled', etc.)
      * @param handler - Event handler function
      */
-    on<K extends keyof RTCProviderEvents>(event: K, handler: RTCProviderEvents[K]): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
     /**
      * Remove event listener.
      * @param event - Event name
      * @param handler - Event handler function (must be same reference as added)
      */
-    off<K extends keyof RTCProviderEvents>(event: K, handler: RTCProviderEvents[K]): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Reconnect to RTC server using the last connection configuration.
+     * Useful for recovering from connection issues or stream stalls.
+     *
+     * @example
+     * ```typescript
+     * player.on('stalled', async () => {
+     *   console.log('Stream stalled, attempting reconnection...');
+     *   await player.reconnect();
+     * });
+     * ```
+     *
+     * @throws Error if no previous connection config exists or reconnection fails
+     */
+    reconnect(): Promise<void>;
 }
 //# sourceMappingURL=AvatarPlayer.d.ts.map

package/dist/core/AvatarPlayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarPlayer.d.ts","sourceRoot":"","sources":["../../src/core/AvatarPlayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,OAAO,KAAK,EAA2B,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAG1D,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,wBAAwB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAY;IAmBvB;;;;;OAKG;gBAED,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,mBAAmB;IAmB/B;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzD;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAYtC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBrC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAClC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI;IAIP;;;;OAIG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,iBAAiB,EACnC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI;CA+FR"}
+{"version":3,"file":"AvatarPlayer.d.ts","sourceRoot":"","sources":["../../src/core/AvatarPlayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAGhF,OAAO,EAA2B,KAAK,QAAQ,EAAmD,MAAM,UAAU,CAAC;AAGnH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,YAAY;IAqDvB;;;;;OAKG;gBAED,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,mBAAmB;IAwC/B;;OAEG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCzD;;;OAGG;IACG,iBAAiB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1E;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2CjC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B1D;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IASrC;;;;;;;;;;;;;;OAcG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtC;;;;;OAKG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAYrC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAa9D;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAyB/D;;;;;;;;;;;;;OAaG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAoMjC"}