@spatialwalk/avatarkit-rtc 1.0.0-beta.1

package/dist/index2.js

@@ -0,0 +1,220 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { AnimationHandler } from "./index6.js";
+import { configureLogger } from "./index7.js";
+class AvatarPlayer {
+  /**
+   * Create a new AvatarPlayer instance.
+   * @param provider - RTC provider implementation (e.g., LiveKitProvider)
+   * @param avatarView - AvatarView instance from @spatialwalk/avatarkit
+   * @param options - Optional configuration for transitions
+   */
+  constructor(provider, avatarView, options) {
+    /** @internal */
+    __publicField(this, "provider");
+    /** @internal */
+    __publicField(this, "avatarView");
+    /** @internal */
+    __publicField(this, "animationHandler");
+    /** @internal */
+    __publicField(this, "_isConnected", false);
+    /** @internal */
+    __publicField(this, "localAudioTrack", null);
+    /** @internal */
+    __publicField(this, "mediaStream", null);
+    this.provider = provider;
+    this.avatarView = avatarView;
+    if ((options == null ? void 0 : options.logLevel) !== void 0) {
+      configureLogger({ level: options.logLevel });
+    }
+    const renderer = this.createRendererAdapter();
+    this.animationHandler = new AnimationHandler(renderer);
+    this.setupProviderEvents();
+  }
+  /**
+   * Check if currently connected to RTC server.
+   */
+  get isConnected() {
+    return this._isConnected;
+  }
+  /**
+   * Connect to RTC server.
+   * @param config - Connection configuration (URL, token, room name, etc.)
+   * @throws Error if already connected or connection fails
+   */
+  async connect(config) {
+    if (this._isConnected) {
+      throw new Error("Already connected. Please disconnect first.");
+    }
+    await this.setupAnimationCallbacks();
+    await this.provider.connect(config);
+    this._isConnected = true;
+  }
+  /**
+   * Disconnect from RTC server.
+   * Stops all tracks and cleans up resources.
+   */
+  async disconnect() {
+    if (!this._isConnected) {
+      return;
+    }
+    if (this.localAudioTrack) {
+      await this.stopPublishing();
+    }
+    await this.provider.disconnect();
+    this.animationHandler.dispose();
+    this._isConnected = false;
+  }
+  /**
+   * Start publishing microphone audio to the RTC server.
+   * Requests microphone permission and starts publishing.
+   * @throws Error if permission denied or no microphone found
+   */
+  async startPublishing() {
+    if (this.localAudioTrack) {
+      return;
+    }
+    this.mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    this.localAudioTrack = this.mediaStream.getAudioTracks()[0];
+    await this.provider.publishAudioTrack(this.localAudioTrack);
+  }
+  /**
+   * Stop publishing microphone audio.
+   */
+  async stopPublishing() {
+    if (!this.localAudioTrack) {
+      return;
+    }
+    await this.provider.unpublishAudioTrack();
+    this.localAudioTrack.stop();
+    this.localAudioTrack = null;
+    if (this.mediaStream) {
+      this.mediaStream.getTracks().forEach((track) => track.stop());
+      this.mediaStream = null;
+    }
+  }
+  /**
+   * Get current connection state.
+   * @returns Connection state string (e.g., 'connected', 'disconnected')
+   */
+  getConnectionState() {
+    return this.provider.getConnectionState();
+  }
+  /**
+   * Get the native RTC client object.
+   * 
+   * Returns the underlying RTC client for advanced use cases:
+   * - LiveKit: Returns the Room instance
+   * - Agora: Returns the IAgoraRTCClient instance
+   * 
+   * @returns The native RTC client object, or null if not connected
+   * 
+   * @example
+   * ```typescript
+   * // Access LiveKit Room
+   * const room = player.getNativeClient() as Room;
+   * console.log('Participants:', room?.remoteParticipants.size);
+   * 
+   * // Access Agora Client
+   * const client = player.getNativeClient() as IAgoraRTCClient;
+   * console.log('State:', client?.connectionState);
+   * ```
+   */
+  getNativeClient() {
+    return this.provider.getNativeClient();
+  }
+  /**
+   * Add event listener.
+   * @param event - Event name ('connected', 'disconnected', 'error', etc.)
+   * @param handler - Event handler function
+   */
+  on(event, handler) {
+    this.provider.on(event, handler);
+  }
+  /**
+   * Remove event listener.
+   * @param event - Event name
+   * @param handler - Event handler function (must be same reference as added)
+   */
+  off(event, handler) {
+    this.provider.off(event, handler);
+  }
+  /**
+   * Create internal renderer adapter that bridges AnimationHandler to AvatarView.
+   * @internal
+   */
+  createRendererAdapter() {
+    const avatarView = this.avatarView;
+    return {
+      renderFrame(flame, startIdle) {
+        if (startIdle) {
+          avatarView.renderFlame(void 0, true);
+        } else if (flame) {
+          avatarView.renderFlame(flame);
+        }
+      },
+      async generateTransitionFromIdle(targetFrame, frameCount) {
+        return avatarView.generateTransition({
+          to: targetFrame,
+          frameCount,
+          useLinear: true
+          // Linear interpolation for idle->speaking
+        });
+      },
+      isReady() {
+        return true;
+      }
+    };
+  }
+  /**
+   * Setup animation track callbacks.
+   * @internal
+   */
+  async setupAnimationCallbacks() {
+    const callbacks = {
+      onAnimationData: (protobufData, metadata) => {
+        if (metadata.isStart) {
+          this.animationHandler.resetTracking();
+          this.provider.playRemoteAudio();
+        }
+        this.animationHandler.handleAnimationData(
+          protobufData,
+          metadata.frameSeq,
+          metadata.isRecovered
+        );
+      },
+      onTransition: (protobufData, transitionFrameCount) => {
+        this.provider.pauseRemoteAudio();
+        this.animationHandler.handleTransitionData(protobufData, transitionFrameCount);
+      },
+      onTransitionEnd: (protobufData, transitionFrameCount) => {
+        this.animationHandler.handleTransitionToIdle(protobufData, transitionFrameCount);
+      },
+      onSessionStart: () => {
+      },
+      onSessionEnd: () => {
+      },
+      onIdleStart: () => {
+        this.animationHandler.startIdle();
+      },
+      onStreamStats: () => {
+      }
+    };
+    await this.provider.subscribeAnimationTrack(callbacks);
+  }
+  /**
+   * Setup provider event handlers.
+   * @internal
+   */
+  setupProviderEvents() {
+    this.provider.on("disconnected", () => {
+      this._isConnected = false;
+      this.animationHandler.startIdle();
+    });
+  }
+}
+export {
+  AvatarPlayer
+};
+//# sourceMappingURL=index2.js.map

package/dist/index2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.js","sources":["../src/core/AvatarPlayer.ts"],"sourcesContent":["/**\n * AvatarPlayer - Unified entry point for RTC avatar streaming.\n *\n * This class provides a unified API that shields applications from\n * differences between different RTC providers (LiveKit, Agora, etc.)\n * and integrates seamlessly with @spatialwalk/avatarkit for rendering.\n *\n * @packageDocumentation\n */\n\nimport type { RTCProvider } from './RTCProvider';\nimport type { RTCConnectionConfig } from '../types';\nimport { AnimationHandler } from './AnimationHandler';\nimport type { AnimationTrackCallbacks, RTCProviderEvents } from './types';\nimport { configureLogger, type LogLevel } from '../utils';\n\n// Import AvatarView type from avatarkit\nimport type { AvatarView, KeyframeData } from '@spatialwalk/avatarkit';\n\n/**\n * Options for configuring AvatarPlayer.\n */\nexport interface AvatarPlayerOptions {\n  /**\n   * Log level for SDK output.\n   * - 'info': Show all logs (debug mode)\n   * - 'warning': Show warnings and errors (default)\n   * - 'error': Show only errors\n   * - 'none': Disable all logs\n   */\n  logLevel?: LogLevel;\n}\n\n/**\n * Unified Avatar Player.\n *\n * Main entry point for applications to interact with RTC avatar streaming.\n * Handles connection management, audio publishing, animation rendering,\n * and coordinates with avatarkit for display.\n *\n * @example\n * ```typescript\n * import { AvatarPlayer, LiveKitProvider } from '@spatialwalk/avatarkit-rtc';\n * import { AvatarView, Avatar } from '@spatialwalk/avatarkit';\n *\n * // Create avatar and view (from avatarkit)\n * const avatar = await Avatar.create(characterId);\n * const avatarView = new AvatarView(avatar, container);\n *\n * // Create player\n * const provider = new LiveKitProvider();\n * const player = new AvatarPlayer(provider, avatarView);\n *\n * // Connect and start\n * await player.connect({ url: 'wss://...', token: '...' });\n * await player.startPublishing(); // Start microphone\n *\n * // Disconnect when done\n * await player.disconnect();\n * ```\n */\nexport class AvatarPlayer {\n  /** @internal */\n  private provider: RTCProvider;\n\n  /** @internal */\n  private avatarView: AvatarView;\n\n  /** @internal */\n  private animationHandler: AnimationHandler;\n\n  /** @internal */\n  private _isConnected = false;\n\n  /** @internal */\n  private localAudioTrack: MediaStreamTrack | null = null;\n\n  /** @internal */\n  private mediaStream: MediaStream | null = null;\n\n  /**\n   * Create a new AvatarPlayer instance.\n   * @param provider - RTC provider implementation (e.g., LiveKitProvider)\n   * @param avatarView - AvatarView instance from @spatialwalk/avatarkit\n   * @param options - Optional configuration for transitions\n   */\n  constructor(\n    provider: RTCProvider,\n    avatarView: AvatarView,\n    options?: AvatarPlayerOptions\n  ) {\n    this.provider = provider;\n    this.avatarView = avatarView;\n\n    // Configure logging if specified\n    if (options?.logLevel !== undefined) {\n      configureLogger({ level: options.logLevel });\n    }\n\n    // Create internal renderer adapter\n    const renderer = this.createRendererAdapter();\n\n    this.animationHandler = new AnimationHandler(renderer);\n\n    // Setup provider event handlers\n    this.setupProviderEvents();\n  }\n\n  /**\n   * Check if currently connected to RTC server.\n   */\n  get isConnected(): boolean {\n    return this._isConnected;\n  }\n\n  /**\n   * Connect to RTC server.\n   * @param config - Connection configuration (URL, token, room name, etc.)\n   * @throws Error if already connected or connection fails\n   */\n  async connect(config: RTCConnectionConfig): Promise<void> {\n    if (this._isConnected) {\n      throw new Error('Already connected. Please disconnect first.');\n    }\n\n    // Setup animation callbacks before connecting\n    await this.setupAnimationCallbacks();\n    await this.provider.connect(config);\n    this._isConnected = true;\n  }\n\n  /**\n   * Disconnect from RTC server.\n   * Stops all tracks and cleans up resources.\n   */\n  async disconnect(): Promise<void> {\n    if (!this._isConnected) {\n      return;\n    }\n\n    // Stop publishing if active\n    if (this.localAudioTrack) {\n      await this.stopPublishing();\n    }\n\n    await this.provider.disconnect();\n    this.animationHandler.dispose();\n    this._isConnected = false;\n  }\n\n  /**\n   * Start publishing microphone audio to the RTC server.\n   * Requests microphone permission and starts publishing.\n   * @throws Error if permission denied or no microphone found\n   */\n  async startPublishing(): Promise<void> {\n    if (this.localAudioTrack) {\n      return; // Already publishing\n    }\n\n    // Request microphone permission\n    this.mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });\n    this.localAudioTrack = this.mediaStream.getAudioTracks()[0];\n\n    await this.provider.publishAudioTrack(this.localAudioTrack);\n  }\n\n  /**\n   * Stop publishing microphone audio.\n   */\n  async stopPublishing(): Promise<void> {\n    if (!this.localAudioTrack) {\n      return;\n    }\n\n    await this.provider.unpublishAudioTrack();\n\n    // Stop and cleanup tracks\n    this.localAudioTrack.stop();\n    this.localAudioTrack = null;\n\n    if (this.mediaStream) {\n      this.mediaStream.getTracks().forEach((track) => track.stop());\n      this.mediaStream = null;\n    }\n  }\n\n  /**\n   * Get current connection state.\n   * @returns Connection state string (e.g., 'connected', 'disconnected')\n   */\n  getConnectionState(): string {\n    return this.provider.getConnectionState();\n  }\n\n  /**\n   * Get the native RTC client object.\n   * \n   * Returns the underlying RTC client for advanced use cases:\n   * - LiveKit: Returns the Room instance\n   * - Agora: Returns the IAgoraRTCClient instance\n   * \n   * @returns The native RTC client object, or null if not connected\n   * \n   * @example\n   * ```typescript\n   * // Access LiveKit Room\n   * const room = player.getNativeClient() as Room;\n   * console.log('Participants:', room?.remoteParticipants.size);\n   * \n   * // Access Agora Client\n   * const client = player.getNativeClient() as IAgoraRTCClient;\n   * console.log('State:', client?.connectionState);\n   * ```\n   */\n  getNativeClient(): unknown {\n    return this.provider.getNativeClient();\n  }\n\n  /**\n   * Add event listener.\n   * @param event - Event name ('connected', 'disconnected', 'error', etc.)\n   * @param handler - Event handler function\n   */\n  on<K extends keyof RTCProviderEvents>(\n    event: K,\n    handler: RTCProviderEvents[K]\n  ): void {\n    this.provider.on(event, handler);\n  }\n\n  /**\n   * Remove event listener.\n   * @param event - Event name\n   * @param handler - Event handler function (must be same reference as added)\n   */\n  off<K extends keyof RTCProviderEvents>(\n    event: K,\n    handler: RTCProviderEvents[K]\n  ): void {\n    this.provider.off(event, handler);\n  }\n\n  /**\n   * Create internal renderer adapter that bridges AnimationHandler to AvatarView.\n   * @internal\n   */\n  private createRendererAdapter() {\n    const avatarView = this.avatarView;\n\n    return {\n      renderFrame(flame: KeyframeData | undefined, startIdle?: boolean): void {\n        if (startIdle) {\n          // Enable idle rendering mode\n          avatarView.renderFlame(undefined as unknown as KeyframeData, true);\n        } else if (flame) {\n          // Render the animation frame\n          avatarView.renderFlame(flame);\n        }\n      },\n\n      async generateTransitionFromIdle(\n        targetFrame: KeyframeData,\n        frameCount: number\n      ): Promise<KeyframeData[]> {\n        // Use avatarkit's generateTransition with from=undefined (current idle frame)\n        return avatarView.generateTransition({\n          to: targetFrame,\n          frameCount,\n          useLinear: true, // Linear interpolation for idle->speaking\n        });\n      },\n\n      isReady(): boolean {\n        return true; // AvatarView is always ready once created\n      },\n    };\n  }\n\n  /**\n   * Setup animation track callbacks.\n   * @internal\n   */\n  private async setupAnimationCallbacks(): Promise<void> {\n    const callbacks: AnimationTrackCallbacks = {\n      onAnimationData: (protobufData, metadata) => {\n        // Reset tracking on session start\n        if (metadata.isStart) {\n          this.animationHandler.resetTracking();\n          // Start audio playback on session start (fallback if transition didn't trigger it)\n          this.provider.playRemoteAudio();\n        }\n\n        this.animationHandler.handleAnimationData(\n          protobufData,\n          metadata.frameSeq,\n          metadata.isRecovered\n        );\n      },\n      onTransition: (protobufData, transitionFrameCount) => {\n        this.provider.pauseRemoteAudio();\n        this.animationHandler.handleTransitionData(protobufData, transitionFrameCount);\n      },\n      onTransitionEnd: (protobufData, transitionFrameCount) => {\n        this.animationHandler.handleTransitionToIdle(protobufData, transitionFrameCount);\n      },\n      onSessionStart: () => {\n        // Session started - can be used for UI feedback\n      },\n      onSessionEnd: () => {\n        // Session ended - can be used for UI feedback\n      },\n      onIdleStart: () => {\n        this.animationHandler.startIdle();\n      },\n      onStreamStats: () => {\n        // Stats can be forwarded to application layer if needed\n      },\n    };\n\n    await this.provider.subscribeAnimationTrack(callbacks);\n  }\n\n  /**\n   * Setup provider event handlers.\n   * @internal\n   */\n  private setupProviderEvents(): void {\n    this.provider.on('disconnected', () => {\n      this._isConnected = false;\n      // Return to idle animation when disconnected\n      this.animationHandler.startIdle();\n    });\n  }\n}\n"],"names":[],"mappings":"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"}