@sanseng/livekit-ws-sdk 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,1789 @@
+/**
+ * Disposable Resource Interface
+ * Classes implementing this interface must provide resource cleanup logic
+ *
+ * @author sansen
+ * @interface IDisposable
+ */
+interface IDisposable {
+    /**
+     * Releases all resources held by the object
+     *
+     * @author sansen
+     */
+    dispose(): void;
+}
+/**
+ * Abstract base class for disposable resources
+ * Provides standardized disposal pattern with safety checks
+ *
+ * @author sansen
+ * @abstract
+ * @class Disposable
+ * @implements {IDisposable}
+ */
+declare abstract class Disposable implements IDisposable {
+    private _disposed;
+    /**
+     * Checks if the object has been disposed
+     *
+     * @type {boolean}
+     * @protected
+     * @author sansen
+     */
+    protected get isDisposed(): boolean;
+    /**
+     * Releases all resources held by the object
+     * Subclasses should override onDispose method to implement specific cleanup logic
+     *
+     * @author sansen
+     */
+    dispose(): void;
+    /**
+     * Abstract method for subclasses to implement specific resource cleanup logic
+     *
+     * @abstract
+     * @protected
+     * @author sansen
+     */
+    protected abstract onDispose(): void;
+    /**
+     * Ensures the object has not been disposed, throws error if already disposed
+     *
+     * @protected
+     * @throws {SDKError} If object has been disposed
+     * @author sansen
+     */
+    protected ensureNotDisposed(): void;
+}
+
+/**
+ * Video-related events
+ *
+ * @author sansen
+ * @interface VideoEvents
+ */
+interface VideoEvents {
+  videoTrackAdded: { trackId: string; participantId: string };
+  videoTrackRemoved: { trackId: string; participantId: string };
+  videoRenderModeChanged: { mode: string };
+}
+
+/**
+ * Audio-related events
+ *
+ * @author sansen
+ * @interface AudioEvents
+ */
+interface AudioEvents {
+  audioInputStarted: void;
+  audioInputStopped: void;
+  audioFrame: { data: Float32Array; sampleRate: number };
+  /**
+   * Raw audio payload event
+   * Contains PCM audio data and metadata (without protocol header)
+   *
+   * @author sansen
+   */
+  audioPayload: {
+    /**
+     * PCM audio data (Uint8Array, 16-bit little-endian)
+     * Does not contain protocol header
+     *
+     * @type {Uint8Array}
+     */
+    payload: Uint8Array;
+    /**
+     * Sample rate in Hz
+     *
+     * @type {number}
+     */
+    sampleRate: number;
+    /**
+     * Number of channels (1=mono, 2=stereo)
+     *
+     * @type {number}
+     */
+    channels: number;
+    /**
+     * Sequence number (0-4095)
+     *
+     * @type {number}
+     */
+    sequenceNumber: number;
+    /**
+     * Timestamp in milliseconds (from capture start)
+     *
+     * @type {number}
+     */
+    timestamp: number;
+    /**
+     * Indicates if this is a key frame
+     *
+     * @type {boolean}
+     */
+    keyFrame: boolean;
+    /**
+     * Frame size in samples
+     *
+     * @type {number}
+     */
+    frameSize: number;
+  };
+  audioTrackAdded: { trackId: string; participantId: string };
+  audioTrackRemoved: { trackId: string };
+  audioVolumeChanged: { volume: number };
+  audioMuted: void;
+  audioUnmuted: void;
+}
+
+/**
+ * Conversation-related events
+ *
+ * @author sansen
+ * @interface ConversationEvents
+ */
+interface ConversationEvents {
+  questionSent: { questionId: string; text: string };
+  answerWaiting: { questionId: string };
+  answerChunk: { questionId: string; chunk: string; isComplete: boolean };
+  answerCompleted: { questionId: string; fullAnswer: string };
+  serverMessage: { questionId: string; message: string; type: string };
+  asrReceived: { questionId: string; text: string };
+}
+
+/**
+ * Connection-related events
+ *
+ * @author sansen
+ * @interface ConnectionEvents
+ */
+interface ConnectionEvents {
+  connected: { source: 'livekit' | 'ws' };
+  disconnected: { source: 'livekit' | 'ws'; reason?: string };
+  error: { error: Error };
+}
+
+/**
+ * SDK public stable event interface
+ * Exposed to external consumers of the SDK
+ *
+ * @author sansen
+ * @interface PublicSDKEvents
+ */
+interface PublicSDKEvents {
+  // Connection status
+  'sdk:connected': { livekit: boolean; ws: boolean; all: boolean };
+  'sdk:disconnected': { reason?: string };
+  'sdk:error': { message: string; code: string };
+
+  // Media status (hides internal trackId and participantId)
+  'media:video:trackAdded': { isLocal: boolean };
+  'media:audio:captureStarted': undefined;
+
+  // Conversation flow (maintains clear business logic)
+  'conversation:question:sent': { questionId: string; text: string };
+  'conversation:answer:waiting': { questionId: string };
+  'conversation:server:message': { questionId: string; message: string; type: string };
+  'conversation:asr:received': { questionId: string; text: string };
+  'conversation:answer:chunk': { questionId: string; chunk: string; isComplete: boolean };
+  'conversation:answer:completed': { questionId: string; fullAnswer: string };
+}
+
+/**
+ * Union type of all SDK events
+ *
+ * @author sansen
+ * @typedef {SDKEvents}
+ */
+type SDKEvents = PublicSDKEvents & VideoEvents & AudioEvents & ConversationEvents & ConnectionEvents;
+
+/**
+ * Event listener function type
+ *
+ * @template T - Event data type
+ * @author sansen
+ */
+type EventListener<T = unknown> = (data: T) => void;
+/**
+ * Event Bus
+ * Implements observer pattern for decoupled communication between modules
+ *
+ * @author sansen
+ * @class EventBus
+ * @extends {Disposable}
+ */
+declare class EventBus extends Disposable {
+    private _listeners;
+    /**
+     * Subscribes to an event
+     *
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {EventListener<SDKEvents[K]>} listener - Event listener function
+     * @returns {() => void} Unsubscribe function
+     * @author sansen
+     */
+    on<K extends keyof SDKEvents>(event: K, listener: EventListener<SDKEvents[K]>): () => void;
+    /**
+     * Subscribes to an event for one-time execution
+     *
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {EventListener<SDKEvents[K]>} listener - Event listener function
+     * @returns {() => void} Unsubscribe function
+     * @author sansen
+     */
+    once<K extends keyof SDKEvents>(event: K, listener: EventListener<SDKEvents[K]>): () => void;
+    /**
+     * Unsubscribes from an event
+     *
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {EventListener<SDKEvents[K]>} listener - Event listener function to remove
+     * @author sansen
+     */
+    off<K extends keyof SDKEvents>(event: K, listener: EventListener<SDKEvents[K]>): void;
+    /**
+     * Emits an event to all registered listeners
+     *
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @param {SDKEvents[K]} data - Event data
+     * @author sansen
+     */
+    emit<K extends keyof SDKEvents>(event: K, data: SDKEvents[K]): void;
+    /**
+     * Removes all event listeners
+     *
+     * @author sansen
+     */
+    removeAllListeners(): void;
+    /**
+     * Gets the count of listeners for a specific event
+     *
+     * @template K - Event key type
+     * @param {K} event - Event name
+     * @returns {number} Number of listeners for the event
+     * @author sansen
+     */
+    listenerCount<K extends keyof SDKEvents>(event: K): number;
+    /**
+     * Cleanup method called when the event bus is disposed
+     *
+     * @protected
+     * @author sansen
+     */
+    protected onDispose(): void;
+}
+
+/**
+ * Video State Management
+ * Pure data container without business logic
+ *
+ * @author sansen
+ * @class VideoState
+ */
+declare class VideoState {
+    /**
+     * Current video track identifier
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    currentTrackId: string | null;
+    /**
+     * Current participant identifier
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    currentParticipantId: string | null;
+    /**
+     * Current video rendering mode
+     *
+     * @type {'raw' | 'processed'}
+     * @default 'raw'
+     * @author sansen
+     */
+    renderMode: 'raw' | 'processed';
+    /**
+     * Indicates if video is currently being rendered
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isRendering: boolean;
+    /**
+     * Resets all video state properties to default values
+     *
+     * @author sansen
+     */
+    reset(): void;
+}
+
+/**
+ * Audio State Management
+ * Pure data container without business logic
+ *
+ * @author sansen
+ * @class AudioState
+ */
+declare class AudioState {
+    /**
+     * Indicates if audio capture (input) is active
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isCapturing: boolean;
+    /**
+     * Current audio sample rate in Hz
+     *
+     * @type {number}
+     * @default 48000
+     * @author sansen
+     */
+    sampleRate: number;
+    /**
+     * Current number of audio channels (1=mono, 2=stereo)
+     *
+     * @type {number}
+     * @default 1
+     * @author sansen
+     */
+    channels: number;
+    /**
+     * Indicates if Voice Activity Detection (VAD) is enabled
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    vadEnabled: boolean;
+    /**
+     * Indicates if 3A processing (Noise Suppression/Echo Cancellation/Automatic Gain Control) is enabled
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    threeAEnabled: boolean;
+    /**
+     * Indicates if audio playback (output) is active
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isPlaying: boolean;
+    /**
+     * Current output audio track identifier
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    currentOutputTrackId: string | null;
+    /**
+     * Audio volume level (0.0 - 1.0)
+     *
+     * @type {number}
+     * @default 1.0
+     * @author sansen
+     */
+    volume: number;
+    /**
+     * Indicates if audio is muted
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isMuted: boolean;
+    /**
+     * Resets all audio state properties to default values
+     *
+     * @author sansen
+     */
+    reset(): void;
+}
+
+/**
+ * Conversation State Enumeration
+ *
+ * @author sansen
+ * @enum {ConversationStateType}
+ */
+declare enum ConversationStateType {
+    /**
+     * No active conversation
+     *
+     * @author sansen
+     */
+    IDLE = "idle",
+    /**
+     * Waiting for server response
+     *
+     * @author sansen
+     */
+    WAITING = "waiting",
+    /**
+     * Receiving streaming answer chunks
+     *
+     * @author sansen
+     */
+    STREAMING = "streaming",
+    /**
+     * Answer stream completed
+     *
+     * @author sansen
+     */
+    COMPLETED = "completed",
+    /**
+     * Conversation error occurred
+     *
+     * @author sansen
+     */
+    ERROR = "error"
+}
+/**
+ * Conversation State Management
+ * Pure data container without business logic
+ *
+ * @author sansen
+ * @class ConversationState
+ */
+declare class ConversationState {
+    /**
+     * Current conversation state
+     *
+     * @type {ConversationStateType}
+     * @default ConversationStateType.IDLE
+     * @author sansen
+     */
+    state: ConversationStateType;
+    /**
+     * Current session identifier
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    currentSessionId: string | null;
+    /**
+     * Current question identifier
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    currentQuestionId: string | null;
+    /**
+     * Current accumulated answer text
+     *
+     * @type {string}
+     * @default ''
+     * @author sansen
+     */
+    currentAnswer: string;
+    /**
+     * Indicates if waiting for answer from server
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isWaiting: boolean;
+    /**
+     * Indicates if receiving streaming answer chunks
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isStreaming: boolean;
+    /**
+     * Last error message from conversation
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    lastError: string | null;
+    /**
+     * Resets all conversation state properties to default values
+     *
+     * @author sansen
+     */
+    reset(): void;
+}
+
+/**
+ * Session Status Enumeration
+ *
+ * @author sansen
+ * @enum {SessionStatus}
+ */
+declare enum SessionStatus {
+    /**
+     * Not connected to server
+     *
+     * @author sansen
+     */
+    DISCONNECTED = "disconnected",
+    /**
+     * Currently establishing connection
+     *
+     * @author sansen
+     */
+    CONNECTING = "connecting",
+    /**
+     * Successfully connected to server
+     *
+     * @author sansen
+     */
+    CONNECTED = "connected",
+    /**
+     * Connection lost, attempting to reconnect
+     *
+     * @author sansen
+     */
+    RECONNECTING = "reconnecting",
+    /**
+     * Connection error occurred
+     *
+     * @author sansen
+     */
+    ERROR = "error"
+}
+/**
+ * Session State Management
+ * Pure data container without business logic
+ *
+ * @author sansen
+ * @class SessionState
+ */
+declare class SessionState {
+    /**
+     * Current session status
+     *
+     * @type {SessionStatus}
+     * @default SessionStatus.DISCONNECTED
+     * @author sansen
+     */
+    status: SessionStatus;
+    /**
+     * Indicates if currently connected to server
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isConnected: boolean;
+    /**
+     * Indicates if currently attempting to reconnect
+     *
+     * @type {boolean}
+     * @default false
+     * @author sansen
+     */
+    isReconnecting: boolean;
+    /**
+     * Number of reconnection attempts made
+     *
+     * @type {number}
+     * @default 0
+     * @author sansen
+     */
+    reconnectAttempts: number;
+    /**
+     * Last error message from session
+     *
+     * @type {string|null}
+     * @default null
+     * @author sansen
+     */
+    lastError: string | null;
+    /**
+     * Timestamp when connection was established (null if disconnected)
+     *
+     * @type {number|null}
+     * @default null
+     * @author sansen
+     */
+    connectedAt: number | null;
+    /**
+     * Resets all session state properties to default values
+     *
+     * @author sansen
+     */
+    reset(): void;
+}
+
+/**
+ * Common Type Definitions
+ *
+ * @author sansen
+ */
+
+/**
+ * Generic callback function type
+ *
+ * @template T - Callback data type
+ * @author sansen
+ * @typedef {Callback}
+ */
+type Callback<T = void> = (data: T) => void;
+
+/**
+ * Error callback function type
+ *
+ * @author sansen
+ * @typedef {ErrorCallback}
+ */
+type ErrorCallback = (error: Error) => void;
+
+/**
+ * Asynchronous operation result wrapper
+ *
+ * @template T - Result data type
+ * @author sansen
+ * @interface AsyncResult
+ */
+interface AsyncResult<T> {
+  /**
+   * Indicates if the operation was successful
+   *
+   * @type {boolean}
+   */
+  success: boolean;
+  /**
+   * Operation result data (if successful)
+   *
+   * @type {T|undefined}
+   */
+  data?: T;
+  /**
+   * Error information (if operation failed)
+   *
+   * @type {Error|undefined}
+   */
+  error?: Error;
+}
+
+/**
+ * Base configuration options interface
+ *
+ * @author sansen
+ * @interface BaseOptions
+ */
+interface BaseOptions {
+  /**
+   * Indicates if debug logging is enabled
+   *
+   * @type {boolean}
+   */
+  debug?: boolean;
+}
+
+/**
+ * Video Configuration Options
+ *
+ * @author sansen
+ */
+
+/**
+ * Video rendering mode
+ *
+ * @author sansen
+ * @typedef {VideoRenderMode}
+ */
+type VideoRenderMode = 'raw' | 'processed';
+
+/**
+ * Green Screen Processing Options
+ *
+ * @author sansen
+ * @interface GreenScreenOptions
+ */
+interface GreenScreenOptions {
+  /**
+   * Indicates if green screen processing is enabled
+   *
+   * @type {boolean}
+   */
+  enabled: boolean;
+
+  /**
+   * Chroma key color (RGB), default [0, 255, 0] (pure green)
+   *
+   * @type {[number, number, number]}
+   * @default [0, 255, 0]
+   */
+  chromaKey?: [number, number, number];
+
+  /**
+   * Similarity threshold (0-1), default 0.4
+   * Lower values make matching stricter
+   *
+   * @type {number}
+   * @default 0.4
+   */
+  similarity?: number;
+
+  /**
+   * Smoothness (0-1), default 0.1
+   * Controls smoothness of alpha transition
+   *
+   * @type {number}
+   * @default 0.1
+   */
+  smoothness?: number;
+
+  /**
+   * Despill strength (0-1), default 0.5
+   * Controls intensity of green spill removal
+   *
+   * @type {number}
+   * @default 0.5
+   */
+  despillStrength?: number;
+
+}
+
+/**
+ * Video Configuration Options Interface
+ *
+ * @author sansen
+ * @interface VideoOptions
+ * @extends {BaseOptions}
+ */
+interface VideoOptions extends BaseOptions {
+  /**
+   * Video rendering mode
+   *
+   * @type {VideoRenderMode}
+   * @default 'raw'
+   */
+  renderMode?: VideoRenderMode;
+
+  /**
+   * Green screen processing options
+   *
+   * @type {GreenScreenOptions}
+   */
+  greenScreen?: GreenScreenOptions;
+
+  /**
+   * Video element for playing video
+   *
+   * @type {HTMLVideoElement}
+   */
+  element?: HTMLVideoElement;
+}
+
+/**
+ * Audio Input Configuration Options
+ *
+ * @author sansen
+ * @interface AudioInputOptions
+ */
+interface AudioInputOptions {
+  /**
+   * Indicates if audio input is enabled
+   *
+   * @type {boolean}
+   */
+  enabled?: boolean;
+
+  /**
+   * Audio sample rate in Hz (default 24000)
+   *
+   * @type {number}
+   */
+  sampleRate?: number;
+
+  /**
+   * Audio bit depth in bits (default 16)
+   *
+   * @type {number}
+   */
+  bitDepth?: number;
+
+  /**
+   * Number of audio channels, default 1 (mono)
+   *
+   * @type {number}
+   */
+  channels?: number;
+
+  /**
+   * Media track constraints for audio input
+   *
+   * @type {MediaTrackConstraints}
+   */
+  constraints?: MediaTrackConstraints;
+}
+
+/**
+ * Audio Output Configuration Options
+ *
+ * @author sansen
+ * @interface AudioOutputOptions
+ */
+interface AudioOutputOptions {
+  /**
+   * Indicates if audio output is enabled
+   *
+   * @type {boolean}
+   */
+  enabled?: boolean;
+
+  /**
+   * Default volume level (0.0 - 1.0)
+   *
+   * @type {number}
+   */
+  volume?: number;
+
+  /**
+   * Indicates if audio output is muted by default
+   *
+   * @type {boolean}
+   */
+  muted?: boolean;
+}
+
+/**
+ * Audio Configuration Options (backward compatible, also supports separated configuration)
+ *
+ * @author sansen
+ * @interface AudioOptions
+ * @extends {BaseOptions}
+ */
+interface AudioOptions extends BaseOptions {
+  /**
+   * Audio input configuration (new configuration format)
+   *
+   * @type {AudioInputOptions}
+   */
+  input?: AudioInputOptions;
+
+  /**
+   * Audio output configuration (new configuration format)
+   *
+   * @type {AudioOutputOptions}
+   */
+  output?: AudioOutputOptions;
+}
+
+/**
+ * Conversation Configuration Options
+ *
+ * @author sansen
+ */
+
+/**
+ * Input mode for conversation
+ *
+ * @author sansen
+ * @typedef {InputMode}
+ */
+type InputMode = 'text' | 'voice' | 'both';
+
+/**
+ * Conversation Configuration Options Interface
+ *
+ * @author sansen
+ * @interface ConversationOptions
+ * @extends {BaseOptions}
+ */
+interface ConversationOptions extends BaseOptions {
+  /**
+   * Input mode for conversation interaction
+   *
+   * @type {InputMode}
+   * @default 'both'
+   */
+  // inputMode?: InputMode;
+
+  /**
+   * Indicates if automatic sending is enabled (for voice input)
+   *
+   * @type {boolean}
+   * @default false
+   */
+  // autoSend?: boolean;
+
+  /**
+   * Voice input timeout in milliseconds
+   *
+   * @type {number}
+   */
+  // voiceTimeout?: number;
+}
+
+/**
+ * Client Configuration Options
+ *
+ * @author sansen
+ * @interface ClientOptions
+ * @extends {BaseOptions}
+ */
+interface ClientOptions extends BaseOptions {
+  /**
+   * WebSocket server URL prefix (for upstream communication)
+   *
+   * @type {string}
+   * @default ''
+   * @author sansen
+   */
+  wsUrlPrefix?: string;
+
+  /**
+   * Avatar name identifier
+   *
+   * @type {string}
+   * @default ''
+   * @author sansen
+   */
+  avatarName: string;
+
+  /**
+   * Audio configuration options
+   *
+   * @type {AudioOptions}
+   * @default undefined
+   * @author sansen
+   */
+  audio?: AudioOptions;
+
+  /**
+   * Video configuration options
+   *
+   * @type {VideoOptions}
+   * @default undefined
+   * @author sansen
+   */
+  video?: VideoOptions;
+
+  /**
+   * Reconnection configuration
+   *
+   * @type {Object}
+   */
+  reconnect?: {
+    /**
+     * Maximum reconnection attempts
+     *
+     * @type {number}
+     */
+    maxAttempts?: number;
+    /**
+     * Reconnection delay in milliseconds
+     *
+     * @type {number}
+     */
+    delay?: number;
+  };
+
+  /**
+   * HTTP service configuration
+   *
+   * @type {Object}
+   */
+  http?: {
+    /**
+     * Base URL for HTTP requests
+     *
+     * @type {string}
+     */
+    baseURL?: string;
+    /**
+     * Default HTTP request headers
+     *
+     * @type {Record<string, string>}
+     */
+    headers?: Record<string, string>;
+  };
+}
+
+/**
+ * SDK Custom Error Class
+ * All SDK internal errors should be converted to SDKError instances
+ *
+ * @author sansen
+ * @class SDKError
+ * @extends {Error}
+ */
+declare class SDKError extends Error {
+    /**
+     * Error code for categorizing and identifying error types
+     *
+     * @type {string}
+     * @author sansen
+     */
+    readonly code: string;
+    /**
+     * Original error that caused this SDKError (if any)
+     *
+     * @type {unknown}
+     * @author sansen
+     */
+    readonly cause?: unknown;
+    /**
+     * Creates an SDKError instance
+     *
+     * @param {string} message - Error description message
+     * @param {string} [code='SDK_ERROR'] - Error code for categorization
+     * @param {unknown} [cause] - Original error that caused this SDKError
+     * @author sansen
+     */
+    constructor(message: string, code?: string, cause?: unknown);
+    /**
+     * Creates an SDKError from any error type
+     *
+     * @param {unknown} error - Original error to convert
+     * @param {string} [code] - Optional error code, defaults to 'SDK_ERROR'
+     * @returns {SDKError} SDKError instance
+     * @author sansen
+     */
+    static fromError(error: unknown, code?: string): SDKError;
+}
+
+/**
+ * SDK Context
+ * Contains all shared states and event bus
+ *
+ * @author sansen
+ * @class SDKContext
+ */
+declare class SDKContext {
+    /**
+     * Event bus for SDK-wide communication
+     *
+     * @type {EventBus}
+     * @memberof SDKContext
+     */
+    readonly eventBus: EventBus;
+    /**
+     * Video state management
+     *
+     * @type {VideoState}
+     * @memberof SDKContext
+     */
+    readonly videoState: VideoState;
+    /**
+     * Audio state management
+     *
+     * @type {AudioState}
+     * @memberof SDKContext
+     */
+    readonly audioState: AudioState;
+    /**
+     * Conversation state management
+     *
+     * @type {ConversationState}
+     * @memberof SDKContext
+     */
+    readonly conversationState: ConversationState;
+    /**
+     * Session state management
+     *
+     * @type {SessionState}
+     * @memberof SDKContext
+     */
+    readonly sessionState: SessionState;
+    /**
+     * Client configuration options
+     *
+     * @type {ClientOptions}
+     * @memberof SDKContext
+     */
+    readonly options: ClientOptions;
+    private _livekitUrl;
+    private _token;
+    private _roomId;
+    private _wsUrl;
+    /**
+     * Creates an SDK context instance
+     *
+     * @param {ClientOptions} options - Client configuration options
+     * @author sansen
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Sets LiveKit configuration parameters
+     *
+     * @param {string} livekitUrl - LiveKit server URL
+     * @param {string} token - Authentication token
+     * @param {string} roomId - Room identifier
+     * @author sansen
+     */
+    setLivekitConfig(livekitUrl: string, token: string, roomId: string): void;
+    /**
+     * Emits an error event and creates SDKError instance
+     *
+     * @param {unknown} error - Original error
+     * @param {string} code - Error code
+     * @returns {SDKError} Created SDKError instance
+     * @author sansen
+     */
+    emitError(error: unknown, code: string): SDKError;
+    /**
+     * Sets WebSocket URL
+     *
+     * @param {string} wsUrl - WebSocket server URL
+     * @author sansen
+     */
+    setWsUrl(wsUrl: string): void;
+    /**
+     * Gets WebSocket URL
+     *
+     * @type {string}
+     * @author sansen
+     */
+    get wsUrl(): string;
+    /**
+     * Gets LiveKit server URL
+     *
+     * @type {string}
+     * @author sansen
+     */
+    get livekitUrl(): string;
+    /**
+     * Gets authentication token
+     *
+     * @type {string}
+     * @author sansen
+     */
+    get token(): string;
+    /**
+     * Gets room identifier
+     *
+     * @type {string|undefined}
+     * @author sansen
+     */
+    get roomId(): string | undefined;
+    /**
+     * Gets LiveKit configuration
+     *
+     * @returns {Object} LiveKit configuration object
+     * @author sansen
+     */
+    getLivekitConfig(): {
+        livekitUrl: string;
+        token: string;
+    };
+    /**
+     * Disposes all resources and cleans up states
+     *
+     * @author sansen
+     */
+    dispose(): void;
+}
+
+interface PublicEmitterAPI {
+    on<K extends keyof PublicSDKEvents>(event: K, listener: (data: PublicSDKEvents[K]) => void): () => void;
+    off<K extends keyof PublicSDKEvents>(event: K, listener: (data: PublicSDKEvents[K]) => void): void;
+    once<K extends keyof PublicSDKEvents>(event: K, listener: (data: PublicSDKEvents[K]) => void): () => void;
+}
+
+/**
+ * SDK client
+ * Provides a unified API surface.
+ * Orchestrates the lifecycles of all subsystems.
+ * @author sansen
+ */
+declare class SDKClient extends Disposable {
+    /**
+     * SDK context
+     * @author sansen
+     */
+    protected readonly _context: SDKContext;
+    private _publicEventAPI?;
+    private _publicEmitter?;
+    /**
+     * Video controller
+     * @author sansen
+     */
+    private _videoController;
+    /**
+     * Audio controller
+     * @author sansen
+     */
+    private _audioController;
+    /**
+     * Conversation controller
+     * @author sansen
+     */
+    private _conversationController;
+    /**
+     * LiveKit service
+     * @author sansen
+     */
+    private _liveKitService;
+    /**
+     * Conversation transport service
+     * @author sansen
+     */
+    private _conversationTransport;
+    /**
+     * Whether the SDK has been Connected
+     * @author sansen
+     */
+    private _isConnected;
+    /**
+     * HTTP controller
+     * @author sansen
+     */
+    private _httpController;
+    private _preConnectPromise;
+    /**
+     * Create SDK client
+     * @param options Client configuration options
+     * @author sansen
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Get public event bus API
+     * @author sansen
+     */
+    get events(): PublicEmitterAPI;
+    /**
+     * Push actions to the server
+     * @param onceActions One-time actions
+     * @param loopActions Repeating/loop actions
+     * @returns Promise<string> resolves to 'success' on success, or rejects with an error
+     * @author sansen
+     */
+    pushActions({ onceActions, loopActions }: {
+        onceActions?: string[];
+        loopActions?: string[];
+    }): Promise<string> | undefined;
+    /**
+     * Interrupt the current conversation connection
+     * @returns Promise<string> resolves to 'success' on success, or rejects with an error
+     * @author sansen
+     */
+    interruptConnection(): Promise<string> | undefined;
+    /**
+     * Send a text question/message
+     * @param text The question text to send
+     * @returns Promise<string> resolves with the message UID
+     * @author sansen
+     */
+    sendTextQuestion(text: string): Promise<string>;
+    /**
+     * Start audio capture
+     * Begins microphone capture and starts sending audio frames over WebSocket
+     * @returns Promise<void>
+     * @throws SDKError if the SDK is not initialized or capture fails to start
+     * @author sansen
+     */
+    startAudioCapture(): Promise<void>;
+    /**
+     * Stop audio capture
+     * Stops microphone capture and stops sending audio frames over WebSocket
+     * @throws SDKError if the SDK is not initialized
+     * @author sansen
+     */
+    stopAudioCapture(): Promise<void>;
+    /**
+     * Sets the audio volume level
+     * @param volume Volume value (0.0 - 1.0)
+     * @author sansen
+     */
+    setVolume(volume: number): void;
+    /**
+     * Get audio volume
+     * Gets the current audio volume level
+     * @returns Volume value (0.0 - 1.0)
+     * @author sansen
+     */
+    getVolume(): number;
+    /**
+     * Mute audio
+     * Mutes the audio output
+     * @author sansen
+     */
+    mute(): void;
+    /**
+     * Check if audio is currently being captured
+     * @returns boolean true if capturing, false otherwise
+     * @throws SDKError if the SDK is not initialized
+     * @author sansen
+     */
+    get isAudioCapturing(): boolean;
+    /**
+     * Pre-connect to remote services
+     * Performs pre-connection steps: fetches auth token and LiveKit configuration
+     * @returns Promise<boolean> resolves to true on success
+     * @author sansen
+     */
+    preConnect(): Promise<boolean>;
+    /**
+     * Connect to the server
+     * Initializes controllers and establishes required connections
+     * @returns Promise<void>
+     * @author sansen
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect
+     * Tears down active connections but retains controller instances to allow reconnect
+     * @author sansen
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnect
+     * Disconnects and then reconnects the SDK
+     * @throws SDKError if the SDK is not initialized
+     * @returns Promise<void>
+     * @author sansen
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Cleanup all resources (internal)
+     * @author sansen
+     */
+    private _cleanup;
+    /**
+     * Check whether the SDK is connected
+     * @author sansen
+     */
+    get isConnected(): boolean;
+    /**
+     * Ensure the SDK has been initialized
+     * @throws SDKError if the SDK is not initialized
+     * @author sansen
+     */
+    private _ensureInitialized;
+    /**
+     * Release resources
+     * @author sansen
+     */
+    protected onDispose(): void;
+}
+
+/**
+ * Create an SDK client instance
+ * @param options Client configuration options
+ * @returns SDK client instance
+ * @throws SDKError if the configuration is invalid
+ * @author sansen
+ */
+declare function createClient(options: ClientOptions): SDKClient;
+
+/**
+ * Log Level Enumeration
+ *
+ * @author sansen
+ * @enum {LogLevel}
+ */
+declare enum LogLevel {
+    /**
+     * Debug level for detailed diagnostic information
+     *
+     * @author sansen
+     */
+    DEBUG = 0,
+    /**
+     * Information level for general operational events
+     *
+     * @author sansen
+     */
+    INFO = 1,
+    /**
+     * Warning level for potentially harmful situations
+     *
+     * @author sansen
+     */
+    WARN = 2,
+    /**
+     * Error level for error events that might still allow the application to continue
+     *
+     * @author sansen
+     */
+    ERROR = 3,
+    /**
+     * No logging (disabled)
+     *
+     * @author sansen
+     */
+    NONE = 4
+}
+/**
+ * Logger Utility
+ * Provides configurable logging with different severity levels
+ *
+ * @author sansen
+ * @class Logger
+ */
+declare class Logger {
+    private static _level;
+    private static _prefix;
+    /**
+     * Sets the current log level
+     *
+     * @param {LogLevel} level - Log level to set
+     * @author sansen
+     */
+    static setLevel(level: LogLevel): void;
+    /**
+     * Sets the log prefix
+     *
+     * @param {string} prefix - Prefix to prepend to all log messages
+     * @author sansen
+     */
+    static setPrefix(prefix: string): void;
+    /**
+     * Logs debug-level messages for detailed diagnostic information
+     *
+     * @param {string} message - Log message
+     * @param {...unknown[]} args - Additional arguments to log
+     * @author sansen
+     */
+    static debug(message: string, ...args: unknown[]): void;
+    /**
+     * Logs info-level messages for general operational events
+     *
+     * @param {string} message - Log message
+     * @param {...unknown[]} args - Additional arguments to log
+     * @author sansen
+     */
+    static info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs warning-level messages for potentially harmful situations
+     *
+     * @param {string} message - Log message
+     * @param {...unknown[]} args - Additional arguments to log
+     * @author sansen
+     */
+    static warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs error-level messages for error events
+     *
+     * @param {string} message - Log message
+     * @param {...unknown[]} args - Additional arguments to log
+     * @author sansen
+     */
+    static error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * SDK Default Configuration Constants
+ *
+ * @author sansen
+ */
+/**
+ * Default reconnection attempt count
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_RECONNECT_ATTEMPTS = 3;
+/**
+ * Default reconnection delay in milliseconds
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_RECONNECT_DELAY = 1000;
+/**
+ * Default WebSocket connection timeout in milliseconds
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_WS_TIMEOUT = 10000;
+/**
+ * Default audio sample rate (input)
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_AUDIO_SAMPLE_RATE = 24000;
+/**
+ * Default audio channel count
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_AUDIO_CHANNELS = 1;
+/**
+ * Default audio buffer size
+ *
+ * @constant {number}
+ * @default
+ */
+declare const DEFAULT_AUDIO_BUFFER_SIZE = 4096;
+
+/**
+ * Video Processor Interface
+ * Defines contract for video processing implementations
+ *
+ * @author sansen
+ * @interface IVideoProcessor
+ */
+interface IVideoProcessor {
+  /**
+   * Processes a video frame
+   *
+   * @param {VideoFrame} frame - Input video frame
+   * @returns {VideoFrame | null} Processed video frame or null if no processing occurred
+   * @author sansen
+   */
+  process(frame: VideoFrame): VideoFrame | null;
+
+  /**
+   * Cleans up resources
+   *
+   * @author sansen
+   */
+  dispose(): void;
+}
+
+/**
+ * Local Video Debug Source
+ * Loads a local video via HTMLVideoElement and provides VideoFrame capture utilities
+ * Operates independently of LiveKit and uses only browser native APIs
+ *
+ * @author sansen
+ * @class LocalVideoDebugSource
+ * @extends {Disposable}
+ */
+declare class LocalVideoDebugSource extends Disposable {
+    private _videoElement;
+    private _videoUrl;
+    private _isPlaying;
+    private _frameCallbackId;
+    /**
+     * Creates a local video debug source instance
+     *
+     * @param {string} videoUrl - Video file URL (can be local file path or remote URL)
+     * @param {HTMLVideoElement} [videoElement] - Optional HTMLVideoElement (will be created if not provided)
+     * @author sansen
+     */
+    constructor(videoUrl: string, videoElement?: HTMLVideoElement);
+    /**
+     * Gets the underlying video element
+     *
+     * @type {HTMLVideoElement|null}
+     * @author sansen
+     */
+    get videoElement(): HTMLVideoElement | null;
+    /**
+     * Loads the video resource
+     *
+     * @returns {Promise<void>} Promise that resolves when video is loaded
+     * @author sansen
+     */
+    load(): Promise<void>;
+    /**
+     * Starts video playback
+     *
+     * @returns {Promise<void>} Promise that resolves when playback starts
+     * @author sansen
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses video playback
+     *
+     * @author sansen
+     */
+    pause(): void;
+    /**
+     * Stops video playback and resets to start
+     *
+     * @author sansen
+     */
+    stop(): void;
+    /**
+     * Checks whether the video is currently playing
+     *
+     * @type {boolean}
+     * @author sansen
+     */
+    get isPlaying(): boolean;
+    /**
+     * Gets video width in pixels
+     *
+     * @type {number}
+     * @author sansen
+     */
+    get videoWidth(): number;
+    /**
+     * Gets video height in pixels
+     *
+     * @type {number}
+     * @author sansen
+     */
+    get videoHeight(): number;
+    /**
+     * Creates a VideoFrame from the current video frame
+     * Uses requestVideoFrameCallback when available, otherwise falls back to drawImage + createImageBitmap
+     *
+     * @returns {Promise<VideoFrame|null>} Promise resolving to VideoFrame or null if capture fails
+     * @author sansen
+     */
+    captureFrame(): Promise<VideoFrame | null>;
+    /**
+     * Registers a video frame callback
+     * Uses requestVideoFrameCallback when supported or falls back to requestAnimationFrame
+     *
+     * @param {(frame: VideoFrame) => void} callback - Frame callback function
+     * @author sansen
+     */
+    onFrame(callback: (frame: VideoFrame) => void): void;
+    /**
+     * Cancels the video frame callback
+     *
+     * @author sansen
+     */
+    offFrame(): void;
+    /**
+     * Cleanup method called when the source is disposed
+     *
+     * @protected
+     * @author sansen
+     */
+    protected onDispose(): void;
+}
+
+/**
+ * Standalone Video Debugger
+ * Completely independent from LiveKit, uses local video files for green screen processing debugging
+ *
+ * Features:
+ * - Load local video files
+ * - Extract video frames
+ * - Process through green screen processor
+ * - Output to Canvas (preserving transparent background)
+ *
+ * Usage example:
+ * ```typescript
+ * const debugger = new StandaloneVideoDebugger('/path/to/video.mp4', canvas);
+ * await debugger.start();
+ * // Video will automatically play and process
+ * ```
+ *
+ * @author sansen
+ * @class StandaloneVideoDebugger
+ * @extends {Disposable}
+ */
+declare class StandaloneVideoDebugger extends Disposable {
+    private _videoSource;
+    private readonly _pipelineRunner;
+    private _isRunning;
+    private _options;
+    /**
+     * Creates a standalone video debugger instance
+     *
+     * @param {string} videoUrl - Video file URL (can be local file path or remote URL)
+     * @param {HTMLVideoElement} [videoElement] - Optional video element to use for playback
+     * @param {HTMLCanvasElement} [outputCanvas] - Output canvas element (optional, will be created if not provided)
+     * @param {VideoOptions} [options] - Video configuration options (including green screen settings)
+     * @author sansen
+     */
+    constructor(videoUrl: string, videoElement?: HTMLVideoElement, outputCanvas?: HTMLCanvasElement, options?: VideoOptions);
+    /**
+     * Switches video source seamlessly
+     *
+     * @param {string} videoUrl - New video URL
+     * @param {HTMLVideoElement} [videoElement] - Optional video element to use
+     * @returns {Promise<void>} Promise that resolves when source is switched
+     * @author sansen
+     */
+    switchSource(videoUrl: string, videoElement?: HTMLVideoElement): Promise<void>;
+    /**
+     * Gets the output canvas element
+     *
+     * @type {HTMLCanvasElement|null}
+     * @author sansen
+     */
+    get outputCanvas(): HTMLCanvasElement | null;
+    /**
+     * Gets the video source instance
+     *
+     * @type {LocalVideoDebugSource}
+     * @author sansen
+     */
+    get videoSource(): LocalVideoDebugSource;
+    /**
+     * Gets the current video processor
+     *
+     * @type {import('../video/video.d').IVideoProcessor|null}
+     * @author sansen
+     */
+    get processor(): IVideoProcessor | null;
+    /**
+     * Sets a new video processor
+     *
+     * @param {import('../video/video.d').IVideoProcessor|null} processor - Video processor to use
+     * @author sansen
+     */
+    setProcessor(processor: IVideoProcessor | null): void;
+    /**
+     * Updates green screen configuration options
+     *
+     * @param {Partial<GreenScreenOptions>} greenScreenOptions - Green screen configuration options
+     * @author sansen
+     */
+    updateGreenScreenOptions(greenScreenOptions: Partial<GreenScreenOptions>): void;
+    /**
+     * Initializes and loads the video
+     *
+     * @returns {Promise<void>} Promise that resolves when initialization is complete
+     * @author sansen
+     */
+    initialize(): Promise<void>;
+    /**
+     * Starts debugging (loads video and begins processing)
+     *
+     * @returns {Promise<void>} Promise that resolves when debugging is started
+     * @author sansen
+     */
+    start(): Promise<void>;
+    /**
+     * Stops debugging
+     *
+     * @author sansen
+     */
+    stop(): void;
+    /**
+     * Pauses debugging
+     *
+     * @author sansen
+     */
+    pause(): void;
+    /**
+     * Resumes debugging
+     *
+     * @returns {Promise<void>} Promise that resolves when debugging is resumed
+     * @author sansen
+     */
+    resume(): Promise<void>;
+    /**
+     * Checks if debugger is currently running
+     *
+     * @type {boolean}
+     * @author sansen
+     */
+    get isRunning(): boolean;
+    /**
+     * Cleanup method called when the debugger is disposed
+     *
+     * @protected
+     * @author sansen
+     */
+    protected onDispose(): void;
+}
+
+export { AudioState, ConversationState, ConversationStateType, DEFAULT_AUDIO_BUFFER_SIZE, DEFAULT_AUDIO_CHANNELS, DEFAULT_AUDIO_SAMPLE_RATE, DEFAULT_RECONNECT_ATTEMPTS, DEFAULT_RECONNECT_DELAY, DEFAULT_WS_TIMEOUT, Disposable, EventBus, LogLevel, Logger, SDKClient, SDKContext, SDKError, SessionState, SessionStatus, StandaloneVideoDebugger, VideoState, createClient };
+export type { AsyncResult, AudioEvents, AudioOptions, BaseOptions, Callback, ClientOptions, ConnectionEvents, ConversationEvents, ConversationOptions, ErrorCallback, GreenScreenOptions, IDisposable, InputMode, SDKEvents, VideoEvents, VideoOptions, VideoRenderMode };