@drawdream/livespeech 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,555 @@
+/**
+ * Available regions for LiveSpeech SDK
+ */
+declare const Region: {
+    /** Asia Pacific (Seoul) */
+    readonly AP_NORTHEAST_2: "ap-northeast-2";
+    /** US West (Oregon) - Coming soon */
+    readonly US_WEST_2: "us-west-2";
+};
+type Region = (typeof Region)[keyof typeof Region];
+/**
+ * Get the WebSocket endpoint URL for a given region
+ * @param region The region identifier
+ * @returns The WebSocket endpoint URL
+ */
+declare function getEndpointForRegion(region: Region): string;
+/**
+ * Check if a string is a valid region
+ * @param value The string to check
+ * @returns True if the string is a valid region
+ */
+declare function isValidRegion(value: string): value is Region;
+
+/**
+ * Configuration options for the LiveSpeech client
+ *
+ * @example
+ * const client = new LiveSpeechClient({
+ *   region: 'ap-northeast-2',
+ *   apiKey: 'your-api-key',
+ * });
+ */
+interface LiveSpeechConfig {
+    /**
+     * Region for the LiveSpeech service
+     * @example 'ap-northeast-2'
+     */
+    region: Region;
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Connection timeout in milliseconds
+     * @default 30000
+     */
+    connectionTimeout?: number;
+    /**
+     * Enable automatic reconnection on disconnect
+     * @default true
+     */
+    autoReconnect?: boolean;
+    /**
+     * Maximum number of reconnection attempts
+     * @default 5
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Base delay between reconnection attempts in milliseconds
+     * Uses exponential backoff
+     * @default 1000
+     */
+    reconnectDelay?: number;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Session configuration options
+ */
+interface SessionConfig {
+    /**
+     * System prompt for the AI assistant
+     */
+    prePrompt: string;
+    /**
+     * Voice ID for text-to-speech output
+     * @default 'en-US-Standard-A'
+     */
+    voiceId?: string;
+    /**
+     * Language code for speech recognition
+     * @default 'en-US'
+     */
+    languageCode?: string;
+    /**
+     * Audio encoding format for input
+     * @default 'pcm16'
+     */
+    inputFormat?: AudioFormat;
+    /**
+     * Audio encoding format for output
+     * @default 'pcm16'
+     */
+    outputFormat?: AudioFormat;
+    /**
+     * Sample rate for audio in Hz
+     * @default 16000
+     */
+    sampleRate?: number;
+    /**
+     * Custom metadata to attach to the session
+     */
+    metadata?: Record<string, string>;
+}
+/**
+ * Supported audio formats
+ */
+type AudioFormat = 'pcm16' | 'opus' | 'wav';
+/**
+ * Internal resolved configuration with defaults applied
+ */
+interface ResolvedConfig {
+    endpoint: string;
+    apiKey: string;
+    connectionTimeout: number;
+    autoReconnect: boolean;
+    maxReconnectAttempts: number;
+    reconnectDelay: number;
+    debug: boolean;
+}
+
+/**
+ * Event types emitted by the LiveSpeech client
+ */
+type LiveSpeechEventType = 'connected' | 'disconnected' | 'sessionStarted' | 'sessionEnded' | 'transcript' | 'response' | 'audio' | 'error' | 'reconnecting';
+/**
+ * Event payload for 'connected' event
+ */
+interface ConnectedEvent {
+    type: 'connected';
+    connectionId: string;
+    timestamp: string;
+}
+/**
+ * Event payload for 'disconnected' event
+ */
+interface DisconnectedEvent {
+    type: 'disconnected';
+    reason: DisconnectReason;
+    code?: number;
+    timestamp: string;
+}
+/**
+ * Disconnect reason codes
+ */
+type DisconnectReason = 'normal' | 'error' | 'timeout' | 'server_close' | 'reconnect_failed';
+/**
+ * Event payload for 'sessionStarted' event
+ */
+interface SessionStartedEvent {
+    type: 'sessionStarted';
+    sessionId: string;
+    timestamp: string;
+}
+/**
+ * Event payload for 'sessionEnded' event
+ */
+interface SessionEndedEvent {
+    type: 'sessionEnded';
+    sessionId: string;
+    timestamp: string;
+}
+/**
+ * Event payload for 'transcript' event
+ */
+interface TranscriptEvent {
+    type: 'transcript';
+    text: string;
+    isFinal: boolean;
+    confidence?: number;
+    timestamp: string;
+}
+/**
+ * Event payload for 'response' event
+ */
+interface ResponseEvent {
+    type: 'response';
+    text: string;
+    isFinal: boolean;
+    timestamp: string;
+}
+/**
+ * Event payload for 'audio' event
+ */
+interface AudioEvent {
+    type: 'audio';
+    data: Uint8Array;
+    format: string;
+    sampleRate: number;
+    timestamp: string;
+}
+/**
+ * Event payload for 'error' event
+ */
+interface ErrorEvent {
+    type: 'error';
+    code: ErrorCode;
+    message: string;
+    details?: unknown;
+    timestamp: string;
+}
+/**
+ * Error codes
+ */
+type ErrorCode = 'connection_failed' | 'connection_timeout' | 'authentication_failed' | 'session_error' | 'audio_error' | 'stt_error' | 'llm_error' | 'tts_error' | 'rate_limit' | 'internal_error' | 'invalid_message';
+/**
+ * Event payload for 'reconnecting' event
+ */
+interface ReconnectingEvent {
+    type: 'reconnecting';
+    attempt: number;
+    maxAttempts: number;
+    delay: number;
+    timestamp: string;
+}
+/**
+ * Union type of all event payloads
+ */
+type LiveSpeechEvent = ConnectedEvent | DisconnectedEvent | SessionStartedEvent | SessionEndedEvent | TranscriptEvent | ResponseEvent | AudioEvent | ErrorEvent | ReconnectingEvent;
+/**
+ * Simplified event handlers for common use cases
+ */
+type TranscriptHandler = (text: string, isFinal: boolean) => void;
+type ResponseHandler = (text: string, isFinal: boolean) => void;
+type AudioHandler = (data: Uint8Array) => void;
+type ErrorHandler = (error: ErrorEvent) => void;
+
+/**
+ * WebSocket message types sent from client to server
+ */
+type ClientMessageType = 'startSession' | 'endSession' | 'audio' | 'ping';
+/**
+ * WebSocket message types received from server
+ */
+type ServerMessageType = 'connected' | 'sessionStarted' | 'sessionEnded' | 'transcript' | 'response' | 'audio' | 'error' | 'pong';
+/**
+ * Base interface for client messages
+ */
+interface BaseClientMessage {
+    action: ClientMessageType;
+    requestId?: string;
+}
+/**
+ * Start session message
+ */
+interface StartSessionMessage extends BaseClientMessage {
+    action: 'startSession';
+    prePrompt: string;
+    voiceId?: string;
+    languageCode?: string;
+    inputFormat?: string;
+    outputFormat?: string;
+    sampleRate?: number;
+    metadata?: Record<string, string>;
+}
+/**
+ * End session message
+ */
+interface EndSessionMessage extends BaseClientMessage {
+    action: 'endSession';
+}
+/**
+ * Audio data message
+ */
+interface AudioMessage extends BaseClientMessage {
+    action: 'audio';
+    data: string;
+    format?: string;
+    sampleRate?: number;
+    isFinal?: boolean;
+}
+/**
+ * Ping message for keep-alive
+ */
+interface PingMessage extends BaseClientMessage {
+    action: 'ping';
+}
+/**
+ * Union type of all client messages
+ */
+type ClientMessage = StartSessionMessage | EndSessionMessage | AudioMessage | PingMessage;
+/**
+ * Base interface for server messages
+ */
+interface BaseServerMessage {
+    type: ServerMessageType;
+    requestId?: string;
+    timestamp: string;
+}
+/**
+ * Connected message from server
+ */
+interface ServerConnectedMessage extends BaseServerMessage {
+    type: 'connected';
+    connectionId: string;
+}
+/**
+ * Session started message from server
+ */
+interface ServerSessionStartedMessage extends BaseServerMessage {
+    type: 'sessionStarted';
+    sessionId: string;
+}
+/**
+ * Session ended message from server
+ */
+interface ServerSessionEndedMessage extends BaseServerMessage {
+    type: 'sessionEnded';
+    sessionId: string;
+}
+/**
+ * Transcript message from server
+ */
+interface ServerTranscriptMessage extends BaseServerMessage {
+    type: 'transcript';
+    text: string;
+    isFinal: boolean;
+    confidence?: number;
+}
+/**
+ * Response message from server
+ */
+interface ServerResponseMessage extends BaseServerMessage {
+    type: 'response';
+    text: string;
+    isFinal: boolean;
+}
+/**
+ * Audio message from server
+ */
+interface ServerAudioMessage extends BaseServerMessage {
+    type: 'audio';
+    data: string;
+    format: string;
+    sampleRate: number;
+}
+/**
+ * Error message from server
+ */
+interface ServerErrorMessage extends BaseServerMessage {
+    type: 'error';
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * Pong message from server
+ */
+interface ServerPongMessage extends BaseServerMessage {
+    type: 'pong';
+}
+/**
+ * Union type of all server messages
+ */
+type ServerMessage = ServerConnectedMessage | ServerSessionStartedMessage | ServerSessionEndedMessage | ServerTranscriptMessage | ServerResponseMessage | ServerAudioMessage | ServerErrorMessage | ServerPongMessage;
+
+/**
+ * Connection state
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+/**
+ * Event types for the client
+ */
+type LiveSpeechEventMap = {
+    connected: ConnectedEvent;
+    disconnected: DisconnectedEvent;
+    sessionStarted: SessionStartedEvent;
+    sessionEnded: SessionEndedEvent;
+    transcript: TranscriptEvent;
+    response: ResponseEvent;
+    audio: AudioEvent;
+    error: ErrorEvent;
+    reconnecting: ReconnectingEvent;
+};
+/**
+ * LiveSpeech client for real-time speech-to-speech AI conversations
+ */
+declare class LiveSpeechClient {
+    private readonly config;
+    private readonly connection;
+    private readonly audioEncoder;
+    private readonly logger;
+    private sessionId;
+    private sessionConfig;
+    private readonly eventListeners;
+    private transcriptHandler;
+    private responseHandler;
+    private audioHandler;
+    private errorHandler;
+    constructor(config: LiveSpeechConfig);
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Get connection ID
+     */
+    get connectionId(): string | null;
+    /**
+     * Get current session ID
+     */
+    get currentSessionId(): string | null;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Check if session is active
+     */
+    get hasActiveSession(): boolean;
+    /**
+     * Connect to the server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Start a new session
+     */
+    startSession(config: SessionConfig): Promise<string>;
+    /**
+     * End the current session
+     */
+    endSession(): Promise<void>;
+    /**
+     * Send audio data
+     */
+    sendAudio(data: Uint8Array, options?: {
+        format?: AudioFormat;
+        isFinal?: boolean;
+    }): void;
+    /**
+     * Add event listener
+     */
+    on<K extends keyof LiveSpeechEventMap>(event: K, listener: (event: LiveSpeechEventMap[K]) => void): void;
+    /**
+     * Remove event listener
+     */
+    off<K extends keyof LiveSpeechEventMap>(event: K, listener: (event: LiveSpeechEventMap[K]) => void): void;
+    /**
+     * Set transcript handler (simplified)
+     */
+    setTranscriptHandler(handler: TranscriptHandler): void;
+    /**
+     * Set response handler (simplified)
+     */
+    setResponseHandler(handler: ResponseHandler): void;
+    /**
+     * Set audio handler (simplified)
+     */
+    setAudioHandler(handler: AudioHandler): void;
+    /**
+     * Set error handler (simplified)
+     */
+    setErrorHandler(handler: ErrorHandler): void;
+    private emit;
+    private handleConnected;
+    private handleDisconnected;
+    private handleReconnecting;
+    private handleError;
+    private handleMessage;
+}
+
+/**
+ * Audio encoder options
+ */
+interface AudioEncoderOptions {
+    format: AudioFormat;
+    sampleRate: number;
+    channels?: number;
+    bitDepth?: number;
+}
+/**
+ * Encode audio data to base64 for transmission
+ * Works in both Node.js and browser environments
+ */
+declare function encodeAudioToBase64(data: Uint8Array): string;
+/**
+ * Decode base64 audio data
+ * Works in both Node.js and browser environments
+ */
+declare function decodeBase64ToAudio(base64: string): Uint8Array;
+/**
+ * Convert Float32Array audio samples to Int16 PCM
+ */
+declare function float32ToInt16(float32Array: Float32Array): Int16Array;
+/**
+ * Convert Int16 PCM to Float32Array audio samples
+ */
+declare function int16ToFloat32(int16Array: Int16Array): Float32Array;
+/**
+ * Convert Int16Array to Uint8Array (little-endian)
+ */
+declare function int16ToUint8(int16Array: Int16Array): Uint8Array;
+/**
+ * Convert Uint8Array to Int16Array (little-endian)
+ */
+declare function uint8ToInt16(uint8Array: Uint8Array): Int16Array;
+/**
+ * Create a WAV header for PCM audio data
+ */
+declare function createWavHeader(dataLength: number, sampleRate: number, channels: number, bitDepth: number): Uint8Array;
+/**
+ * Wrap PCM data in a WAV container
+ */
+declare function wrapPcmInWav(pcmData: Uint8Array, options?: Partial<AudioEncoderOptions>): Uint8Array;
+/**
+ * Extract PCM data from a WAV file
+ */
+declare function extractPcmFromWav(wavData: Uint8Array): {
+    pcmData: Uint8Array;
+    sampleRate: number;
+    channels: number;
+    bitDepth: number;
+};
+/**
+ * Audio encoder class for managing audio format conversions
+ */
+declare class AudioEncoder {
+    private readonly options;
+    constructor(options?: Partial<AudioEncoderOptions>);
+    /**
+     * Get current options
+     */
+    get format(): AudioFormat;
+    get sampleRate(): number;
+    /**
+     * Encode audio data for transmission
+     */
+    encode(data: Uint8Array): string;
+    /**
+     * Decode received audio data
+     */
+    decode(base64: string): Uint8Array;
+    /**
+     * Convert Float32 samples to transmission-ready format
+     */
+    fromFloat32(samples: Float32Array): Uint8Array;
+    /**
+     * Convert received data to Float32 samples
+     */
+    toFloat32(data: Uint8Array): Float32Array;
+    /**
+     * Wrap data in WAV format if needed
+     */
+    wrapWav(data: Uint8Array): Uint8Array;
+}
+
+export { AudioEncoder, type AudioEncoderOptions, type AudioEvent, type AudioFormat, type AudioHandler, type ClientMessage, type ClientMessageType, type ConnectedEvent, type ConnectionState, type DisconnectReason, type DisconnectedEvent, type ErrorCode, type ErrorEvent, type ErrorHandler, LiveSpeechClient, type LiveSpeechConfig, type LiveSpeechEvent, type LiveSpeechEventMap, type LiveSpeechEventType, type ReconnectingEvent, Region, Region as RegionType, type ResolvedConfig, type ResponseEvent, type ResponseHandler, type ServerMessage, type ServerMessageType, type SessionConfig, type SessionEndedEvent, type SessionStartedEvent, type TranscriptEvent, type TranscriptHandler, createWavHeader, decodeBase64ToAudio, encodeAudioToBase64, extractPcmFromWav, float32ToInt16, getEndpointForRegion, int16ToFloat32, int16ToUint8, isValidRegion, uint8ToInt16, wrapPcmInWav };