@drawdream/livespeech 0.1.1 → 0.1.3

package/README.md

@@ -5,6 +5,15 @@
 
 A TypeScript/JavaScript SDK for real-time speech-to-speech AI conversations.
 
+## Features
+
+- 🎙️ **Real-time Voice Conversations** - Natural, low-latency voice interactions
+- 🌐 **Multi-language Support** - Korean, English, Japanese, Chinese, and more
+- 🔊 **Streaming Audio** - Send and receive audio in real-time
+- 📝 **Live Transcription** - Get transcriptions of both user and AI speech
+- 🔄 **Auto-reconnection** - Automatic recovery from network issues
+- 🌐 **Browser & Node.js** - Works in both environments
+
 ## Installation
 
 ```bash
@@ -18,137 +27,306 @@ pnpm add @drawdream/livespeech
 ## Quick Start
 
 ```typescript
-import { LiveSpeechClient, Region } from '@drawdream/livespeech';
+import { LiveSpeechClient } from '@drawdream/livespeech';
 
 const client = new LiveSpeechClient({
-  region: 'ap-northeast-2',  // or Region.AP_NORTHEAST_2
+  region: 'ap-northeast-2',
   apiKey: 'your-api-key',
 });
 
-// Handle events
-client.setTranscriptHandler((text, isFinal) => {
-  console.log(`Transcript: ${text} (final: ${isFinal})`);
+// Set up event handlers
+client.setUserTranscriptHandler((text) => {
+  console.log('You:', text);
 });
 
 client.setResponseHandler((text, isFinal) => {
-  console.log(`AI Response: ${text}`);
+  console.log('AI:', text);
 });
 
 client.setAudioHandler((audioData) => {
-  // Play audio through speakers
+  playAudio(audioData);  // PCM16 @ 24kHz
+});
+
+client.setErrorHandler((error) => {
+  console.error('Error:', error.message);
 });
 
-// Connect and start session
+// Connect and start conversation
 await client.connect();
 await client.startSession({
   prePrompt: 'You are a helpful assistant.',
+  language: 'ko-KR',
 });
 
-// Send audio
-client.sendAudio(audioBuffer);
+// Stream audio
+client.audioStart();
+client.sendAudioChunk(pcmData);  // PCM16 @ 16kHz
+client.audioEnd();
+
+// Cleanup
+await client.endSession();
+client.disconnect();
 ```
 
-## API Reference
+## Audio Flow
 
-### Regions
+```
+connect() → startSession() → audioStart() → sendAudioChunk()* → audioEnd() → endSession()
+```
 
-The SDK provides built-in region support, so you don't need to remember endpoint URLs:
+| Step | Description |
+|------|-------------|
+| `connect()` | Establish WebSocket connection |
+| `startSession(config)` | Start conversation with optional system prompt |
+| `audioStart()` | Begin audio streaming |
+| `sendAudioChunk(data)` | Send PCM16 audio (call multiple times) |
+| `audioEnd()` | End streaming, triggers AI response |
+| `endSession()` | End conversation |
+| `disconnect()` | Close connection |
 
-| Region | Identifier | Location |
-|--------|------------|----------|
-| `ap-northeast-2` | `Region.AP_NORTHEAST_2` | Asia Pacific (Seoul) |
-| `us-west-2` | `Region.US_WEST_2` | US West (Oregon) - Coming soon |
+## Configuration
+
+```typescript
+const client = new LiveSpeechClient({
+  region: 'ap-northeast-2',       // Required: Seoul region
+  apiKey: 'your-api-key',         // Required: Your API key
+  autoReconnect: true,            // Auto-reconnect on disconnect
+  maxReconnectAttempts: 5,        // Maximum reconnection attempts
+  debug: false,                   // Enable debug logging
+});
 
-### LiveSpeechClient
+await client.startSession({
+  prePrompt: 'You are a helpful assistant.',
+  language: 'ko-KR',              // Language: ko-KR, en-US, ja-JP, etc.
+});
+```
 
-#### Constructor Options
+## Events
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `region` | `string` | **required** | Region identifier |
-| `apiKey` | `string` | **required** | API key for authentication |
-| `connectionTimeout` | `number` | `30000` | Connection timeout in ms |
-| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
-| `maxReconnectAttempts` | `number` | `5` | Max reconnection attempts |
-| `reconnectDelay` | `number` | `1000` | Base reconnection delay in ms |
-| `debug` | `boolean` | `false` | Enable debug logging |
+| Event | Description | Key Properties |
+|-------|-------------|----------------|
+| `connected` | Connection established | `connectionId` |
+| `disconnected` | Connection closed | `reason`, `code` |
+| `sessionStarted` | Session created | `sessionId` |
+| `ready` | Ready for audio input | `timestamp` |
+| `userTranscript` | Your speech transcribed | `text` |
+| `response` | AI's response text | `text`, `isFinal` |
+| `audio` | AI's audio output | `data`, `sampleRate` |
+| `turnComplete` | AI finished speaking | `timestamp` |
+| `error` | Error occurred | `code`, `message` |
 
-#### Methods
+### Simple Handlers
 
-| Method | Description |
-|--------|-------------|
-| `connect()` | Connect to the server |
-| `disconnect()` | Disconnect from the server |
-| `startSession(config)` | Start a conversation session |
-| `endSession()` | End the current session |
-| `sendAudio(data, options?)` | Send audio data to be transcribed |
+```typescript
+// Your speech transcription
+client.setUserTranscriptHandler((text) => {
+  console.log('You said:', text);
+});
 
-#### Event Handlers
+// AI's text response
+client.setResponseHandler((text, isFinal) => {
+  console.log('AI:', text, isFinal ? '(done)' : '...');
+});
+
+// AI's audio output
+client.setAudioHandler((data: Uint8Array) => {
+  // data: PCM16 audio
+  // Sample rate: 24000 Hz
+  playAudio(data);
+});
+
+// Error handling
+client.setErrorHandler((error) => {
+  console.error(`Error [${error.code}]: ${error.message}`);
+});
+```
+
+### Full Event API
 
 ```typescript
-// Simple handlers
-client.setTranscriptHandler((text, isFinal) => {});
-client.setResponseHandler((text, isFinal) => {});
-client.setAudioHandler((audioData) => {});
-client.setErrorHandler((error) => {});
-
-// Full event API
-client.on('connected', (event) => {});
-client.on('disconnected', (event) => {});
-client.on('sessionStarted', (event) => {});
-client.on('sessionEnded', (event) => {});
-client.on('transcript', (event) => {});
-client.on('response', (event) => {});
-client.on('audio', (event) => {});
-client.on('error', (event) => {});
-client.on('reconnecting', (event) => {});
+client.on('connected', (event) => {
+  console.log('Connected:', event.connectionId);
+});
+
+client.on('ready', () => {
+  console.log('Ready for audio');
+});
+
+client.on('userTranscript', (event) => {
+  console.log('You:', event.text);
+});
+
+client.on('response', (event) => {
+  console.log('AI:', event.text, event.isFinal);
+});
+
+client.on('audio', (event) => {
+  // event.data: Uint8Array (PCM16)
+  // event.sampleRate: 24000
+  playAudio(event.data);
+});
+
+client.on('turnComplete', () => {
+  console.log('AI finished speaking');
+});
+
+client.on('error', (event) => {
+  console.error('Error:', event.code, event.message);
+});
 ```
 
-### SessionConfig
+## Audio Format
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `prePrompt` | `string` | **required** | System prompt for the AI |
-| `voiceId` | `string` | `'en-US-Standard-A'` | TTS voice ID |
-| `languageCode` | `string` | `'en-US'` | Language for STT |
-| `inputFormat` | `AudioFormat` | `'pcm16'` | Input audio format |
-| `outputFormat` | `AudioFormat` | `'pcm16'` | Output audio format |
-| `sampleRate` | `number` | `16000` | Sample rate in Hz |
-| `metadata` | `Record<string,string>` | `{}` | Custom metadata |
+### Input (Your Microphone)
 
-## Audio Utilities
+| Property | Value |
+|----------|-------|
+| Format | PCM16 (16-bit signed, little-endian) |
+| Sample Rate | 16,000 Hz |
+| Channels | 1 (Mono) |
+| Chunk Size | ~3200 bytes (100ms) |
+
+### Output (AI Response)
+
+| Property | Value |
+|----------|-------|
+| Format | PCM16 (16-bit signed, little-endian) |
+| Sample Rate | 24,000 Hz |
+| Channels | 1 (Mono) |
+
+## Browser Example
+
+```typescript
+import { LiveSpeechClient, float32ToInt16, int16ToUint8 } from '@drawdream/livespeech';
+
+const client = new LiveSpeechClient({
+  region: 'ap-northeast-2',
+  apiKey: 'your-api-key',
+});
+
+// Handlers
+client.setUserTranscriptHandler((text) => console.log('You:', text));
+client.setResponseHandler((text) => console.log('AI:', text));
+client.setAudioHandler((data) => playAudioChunk(data));
+
+// Connect
+await client.connect();
+await client.startSession({ prePrompt: 'You are a helpful assistant.' });
+
+// Capture microphone
+const stream = await navigator.mediaDevices.getUserMedia({
+  audio: { sampleRate: 16000, channelCount: 1 }
+});
+
+const audioContext = new AudioContext({ sampleRate: 16000 });
+const source = audioContext.createMediaStreamSource(stream);
+const processor = audioContext.createScriptProcessor(4096, 1, 1);
+
+processor.onaudioprocess = (e) => {
+  const float32 = e.inputBuffer.getChannelData(0);
+  const int16 = float32ToInt16(float32);
+  const pcm = int16ToUint8(int16);
+  client.sendAudioChunk(pcm);
+};
+
+source.connect(processor);
+processor.connect(audioContext.destination);
 
-The SDK includes audio encoding/decoding utilities:
+// Start streaming
+client.audioStart();
+
+// Stop later
+client.audioEnd();
+stream.getTracks().forEach(track => track.stop());
+```
+
+## Audio Utilities
 
 ```typescript
 import {
-  encodeAudioToBase64,
-  decodeBase64ToAudio,
-  float32ToInt16,
-  int16ToFloat32,
-  wrapPcmInWav,
+  float32ToInt16,    // Web Audio Float32 → PCM16
+  int16ToFloat32,    // PCM16 → Float32
+  int16ToUint8,      // Int16Array → Uint8Array
+  uint8ToInt16,      // Uint8Array → Int16Array
+  wrapPcmInWav,      // Create WAV file
+  AudioEncoder,      // Base64 encoding/decoding
 } from '@drawdream/livespeech';
 
-// Convert Float32 audio samples to PCM16
-const pcmData = float32ToInt16(float32Samples);
+// Convert Web Audio to PCM16 for sending
+const float32 = audioBuffer.getChannelData(0);
+const int16 = float32ToInt16(float32);
+const pcmBytes = int16ToUint8(int16);
+client.sendAudioChunk(pcmBytes);
 
-// Create WAV file from PCM data
-const wavFile = wrapPcmInWav(pcmData, { sampleRate: 16000 });
+// Convert received PCM16 to Web Audio
+const receivedInt16 = uint8ToInt16(audioEvent.data);
+const float32Data = int16ToFloat32(receivedInt16);
 ```
 
-## Browser Usage
+## Error Handling
 
-The SDK works in both Node.js and browser environments:
+```typescript
+client.on('error', (event) => {
+  switch (event.code) {
+    case 'authentication_failed':
+      console.error('Invalid API key');
+      break;
+    case 'connection_timeout':
+      console.error('Connection timed out');
+      break;
+    case 'rate_limit':
+      console.error('Rate limit exceeded');
+      break;
+    default:
+      console.error(`Error: ${event.message}`);
+  }
+});
 
-```html
-<script type="module">
-import { LiveSpeechClient } from '@drawdream/livespeech';
+client.on('disconnected', (event) => {
+  if (event.reason === 'error') {
+    console.log('Will auto-reconnect...');
+  }
+});
 
-// Use the Web Audio API to capture microphone
-const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-const audioContext = new AudioContext({ sampleRate: 16000 });
-// ... process audio and send to client
-</script>
+client.on('reconnecting', (event) => {
+  console.log(`Reconnecting ${event.attempt}/${event.maxAttempts}`);
+});
+```
+
+## Client Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isConnected` | `boolean` | Connection status |
+| `hasActiveSession` | `boolean` | Session status |
+| `isAudioStreaming` | `boolean` | Streaming status |
+| `connectionId` | `string \| null` | Current connection ID |
+| `currentSessionId` | `string \| null` | Current session ID |
+
+## Regions
+
+| Region | Code | Location |
+|--------|------|----------|
+| Asia Pacific (Seoul) | `ap-northeast-2` | Korea |
+
+## TypeScript Types
+
+```typescript
+import type {
+  LiveSpeechConfig,
+  SessionConfig,
+  LiveSpeechEvent,
+  ConnectedEvent,
+  DisconnectedEvent,
+  SessionStartedEvent,
+  ReadyEvent,
+  UserTranscriptEvent,
+  ResponseEvent,
+  AudioEvent,
+  TurnCompleteEvent,
+  ErrorEvent,
+  ErrorCode,
+} from '@drawdream/livespeech';
 ```
 
 ## License

package/dist/index.d.mts

@@ -21,6 +21,12 @@ declare function getEndpointForRegion(region: Region): string;
  */
 declare function isValidRegion(value: string): value is Region;
 
+/**
+ * Pipeline mode for audio processing
+ * - 'live': Direct audio-to-audio conversation (default, lower latency)
+ * - 'composed': Uses separate STT + LLM + TTS services (more customizable)
+ */
+type PipelineMode = 'live' | 'composed';
 /**
  * Configuration options for the LiveSpeech client
  *
@@ -75,6 +81,25 @@ interface SessionConfig {
      * System prompt for the AI assistant
      */
     prePrompt?: string;
+    /**
+     * Language code for speech recognition (e.g., "en-US", "ko-KR")
+     * @default "en-US"
+     */
+    language?: string;
+    /**
+     * Pipeline mode for audio processing
+     * - 'live': Direct audio-to-audio conversation (default, lower latency)
+     * - 'composed': Uses separate STT + LLM + TTS services (more customizable)
+     * @default "live"
+     */
+    pipelineMode?: PipelineMode;
+    /**
+     * Enable AI to speak first before user input (live mode only)
+     * When enabled, the AI will initiate the conversation based on the prePrompt.
+     * Make sure your prePrompt includes instructions for how the AI should greet the user.
+     * @default false
+     */
+    aiSpeaksFirst?: boolean;
 }
 /**
  * Internal resolved configuration with defaults applied
@@ -92,7 +117,7 @@ interface ResolvedConfig {
 /**
  * Event types emitted by the LiveSpeech client
  */
-type LiveSpeechEventType = 'connected' | 'disconnected' | 'sessionStarted' | 'sessionEnded' | 'streamingStarted' | 'speechStart' | 'speechEnd' | 'transcript' | 'response' | 'audio' | 'error' | 'reconnecting';
+type LiveSpeechEventType = 'connected' | 'disconnected' | 'reconnecting' | 'sessionStarted' | 'sessionEnded' | 'ready' | 'userTranscript' | 'response' | 'audio' | 'turnComplete' | 'error';
 /**
  * Event payload for 'connected' event
  */
@@ -131,34 +156,19 @@ interface SessionEndedEvent {
     timestamp: string;
 }
 /**
- * Event payload for 'streamingStarted' event - acknowledgment of audioStart
- */
-interface StreamingStartedEvent {
-    type: 'streamingStarted';
-    timestamp: string;
-}
-/**
- * Event payload for 'speechStart' event - VAD detected speech begin
- */
-interface SpeechStartEvent {
-    type: 'speechStart';
-    timestamp: string;
-}
-/**
- * Event payload for 'speechEnd' event - VAD detected speech end
+ * Event payload for 'ready' event
  */
-interface SpeechEndEvent {
-    type: 'speechEnd';
+interface ReadyEvent {
+    type: 'ready';
     timestamp: string;
 }
 /**
- * Event payload for 'transcript' event
+ * Event payload for 'userTranscript' event
+ * User's speech transcription
  */
-interface TranscriptEvent {
-    type: 'transcript';
+interface UserTranscriptEvent {
+    type: 'userTranscript';
     text: string;
-    isFinal: boolean;
-    confidence?: number;
     timestamp: string;
 }
 /**
@@ -204,14 +214,22 @@ interface ReconnectingEvent {
     delay: number;
     timestamp: string;
 }
+/**
+ * Event payload for 'turnComplete' event (both modes)
+ * Indicates the AI has finished its response turn
+ */
+interface TurnCompleteEvent {
+    type: 'turnComplete';
+    timestamp: string;
+}
 /**
  * Union type of all event payloads
  */
-type LiveSpeechEvent = ConnectedEvent | DisconnectedEvent | SessionStartedEvent | SessionEndedEvent | StreamingStartedEvent | SpeechStartEvent | SpeechEndEvent | TranscriptEvent | ResponseEvent | AudioEvent | ErrorEvent | ReconnectingEvent;
+type LiveSpeechEvent = ConnectedEvent | DisconnectedEvent | ReconnectingEvent | SessionStartedEvent | SessionEndedEvent | ReadyEvent | UserTranscriptEvent | ResponseEvent | AudioEvent | TurnCompleteEvent | ErrorEvent;
 /**
  * Simplified event handlers for common use cases
  */
-type TranscriptHandler = (text: string, isFinal: boolean) => void;
+type UserTranscriptHandler = (text: string) => void;
 type ResponseHandler = (text: string, isFinal: boolean) => void;
 type AudioHandler = (data: Uint8Array) => void;
 type ErrorHandler = (error: ErrorEvent) => void;
@@ -223,7 +241,7 @@ type ClientMessageType = 'startSession' | 'endSession' | 'audioStart' | 'audioCh
 /**
  * WebSocket message types received from server
  */
-type ServerMessageType = 'sessionStarted' | 'sessionEnded' | 'streamingStarted' | 'speechStart' | 'speechEnd' | 'transcript' | 'response' | 'audio' | 'error' | 'pong';
+type ServerMessageType = 'sessionStarted' | 'sessionEnded' | 'ready' | 'userTranscript' | 'response' | 'audio' | 'turnComplete' | 'error' | 'pong';
 /**
  * Base interface for client messages
  */
@@ -236,6 +254,8 @@ interface BaseClientMessage {
 interface StartSessionMessage extends BaseClientMessage {
     action: 'startSession';
     prePrompt?: string;
+    language?: string;
+    pipelineMode?: 'live' | 'composed';
 }
 /**
  * End session message
@@ -294,31 +314,11 @@ interface ServerSessionEndedMessage extends BaseServerMessage {
     sessionId: string;
 }
 /**
- * Streaming started message - acknowledgment of audioStart
+ * User transcript message from server (user's speech transcription)
  */
-interface ServerStreamingStartedMessage extends BaseServerMessage {
-    type: 'streamingStarted';
-}
-/**
- * Speech start message - VAD detected speech begin
- */
-interface ServerSpeechStartMessage extends BaseServerMessage {
-    type: 'speechStart';
-}
-/**
- * Speech end message - VAD detected speech end
- */
-interface ServerSpeechEndMessage extends BaseServerMessage {
-    type: 'speechEnd';
-}
-/**
- * Transcript message from server
- */
-interface ServerTranscriptMessage extends BaseServerMessage {
-    type: 'transcript';
+interface ServerUserTranscriptMessage extends BaseServerMessage {
+    type: 'userTranscript';
     text: string;
-    isFinal: boolean;
-    confidence?: number;
 }
 /**
  * Response message from server
@@ -351,10 +351,24 @@ interface ServerErrorMessage extends BaseServerMessage {
 interface ServerPongMessage extends BaseServerMessage {
     type: 'pong';
 }
+/**
+ * Turn complete message from server
+ * Indicates the AI has finished its response turn
+ */
+interface ServerTurnCompleteMessage extends BaseServerMessage {
+    type: 'turnComplete';
+}
+/**
+ * Ready message from server
+ * Indicates the session is ready for audio input
+ */
+interface ServerReadyMessage extends BaseServerMessage {
+    type: 'ready';
+}
 /**
  * Union type of all server messages
  */
-type ServerMessage = ServerSessionStartedMessage | ServerSessionEndedMessage | ServerStreamingStartedMessage | ServerSpeechStartMessage | ServerSpeechEndMessage | ServerTranscriptMessage | ServerResponseMessage | ServerAudioMessage | ServerErrorMessage | ServerPongMessage;
+type ServerMessage = ServerSessionStartedMessage | ServerSessionEndedMessage | ServerReadyMessage | ServerUserTranscriptMessage | ServerResponseMessage | ServerAudioMessage | ServerTurnCompleteMessage | ServerErrorMessage | ServerPongMessage;
 
 /**
  * Connection state
@@ -367,16 +381,15 @@ type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecti
 type LiveSpeechEventMap = {
     connected: ConnectedEvent;
     disconnected: DisconnectedEvent;
+    reconnecting: ReconnectingEvent;
     sessionStarted: SessionStartedEvent;
     sessionEnded: SessionEndedEvent;
-    streamingStarted: StreamingStartedEvent;
-    speechStart: SpeechStartEvent;
-    speechEnd: SpeechEndEvent;
-    transcript: TranscriptEvent;
+    ready: ReadyEvent;
+    userTranscript: UserTranscriptEvent;
     response: ResponseEvent;
     audio: AudioEvent;
+    turnComplete: TurnCompleteEvent;
     error: ErrorEvent;
-    reconnecting: ReconnectingEvent;
 };
 /**
  * LiveSpeech client for real-time speech-to-speech AI conversations
@@ -389,7 +402,7 @@ declare class LiveSpeechClient {
     private sessionId;
     private isStreaming;
     private readonly eventListeners;
-    private transcriptHandler;
+    private userTranscriptHandler;
     private responseHandler;
     private audioHandler;
     private errorHandler;
@@ -455,17 +468,17 @@ declare class LiveSpeechClient {
      */
     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)
+     * Set response handler
      */
     setResponseHandler(handler: ResponseHandler): void;
     /**
      * Set audio handler (simplified)
      */
     setAudioHandler(handler: AudioHandler): void;
+    /**
+     * Set user transcript handler
+     */
+    setUserTranscriptHandler(handler: UserTranscriptHandler): void;
     /**
      * Set error handler (simplified)
      */
@@ -567,4 +580,4 @@ declare class AudioEncoder {
     wrapWav(data: Uint8Array): Uint8Array;
 }
 
-export { AudioEncoder, type AudioEncoderOptions, type AudioEvent, 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 SpeechEndEvent, type SpeechStartEvent, type StreamingStartedEvent, type TranscriptEvent, type TranscriptHandler, createWavHeader, decodeBase64ToAudio, encodeAudioToBase64, extractPcmFromWav, float32ToInt16, getEndpointForRegion, int16ToFloat32, int16ToUint8, isValidRegion, uint8ToInt16, wrapPcmInWav };
+export { AudioEncoder, type AudioEncoderOptions, type AudioEvent, 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 PipelineMode, type ReadyEvent, type ReconnectingEvent, Region, Region as RegionType, type ResolvedConfig, type ResponseEvent, type ResponseHandler, type ServerMessage, type ServerMessageType, type SessionConfig, type SessionEndedEvent, type SessionStartedEvent, type TurnCompleteEvent, type UserTranscriptEvent, type UserTranscriptHandler, createWavHeader, decodeBase64ToAudio, encodeAudioToBase64, extractPcmFromWav, float32ToInt16, getEndpointForRegion, int16ToFloat32, int16ToUint8, isValidRegion, uint8ToInt16, wrapPcmInWav };

package/dist/index.d.ts

@@ -21,6 +21,12 @@ declare function getEndpointForRegion(region: Region): string;
  */
 declare function isValidRegion(value: string): value is Region;
 
+/**
+ * Pipeline mode for audio processing
+ * - 'live': Direct audio-to-audio conversation (default, lower latency)
+ * - 'composed': Uses separate STT + LLM + TTS services (more customizable)
+ */
+type PipelineMode = 'live' | 'composed';
 /**
  * Configuration options for the LiveSpeech client
  *
@@ -75,6 +81,25 @@ interface SessionConfig {
      * System prompt for the AI assistant
      */
     prePrompt?: string;
+    /**
+     * Language code for speech recognition (e.g., "en-US", "ko-KR")
+     * @default "en-US"
+     */
+    language?: string;
+    /**
+     * Pipeline mode for audio processing
+     * - 'live': Direct audio-to-audio conversation (default, lower latency)
+     * - 'composed': Uses separate STT + LLM + TTS services (more customizable)
+     * @default "live"
+     */
+    pipelineMode?: PipelineMode;
+    /**
+     * Enable AI to speak first before user input (live mode only)
+     * When enabled, the AI will initiate the conversation based on the prePrompt.
+     * Make sure your prePrompt includes instructions for how the AI should greet the user.
+     * @default false
+     */
+    aiSpeaksFirst?: boolean;
 }
 /**
  * Internal resolved configuration with defaults applied
@@ -92,7 +117,7 @@ interface ResolvedConfig {
 /**
  * Event types emitted by the LiveSpeech client
  */
-type LiveSpeechEventType = 'connected' | 'disconnected' | 'sessionStarted' | 'sessionEnded' | 'streamingStarted' | 'speechStart' | 'speechEnd' | 'transcript' | 'response' | 'audio' | 'error' | 'reconnecting';
+type LiveSpeechEventType = 'connected' | 'disconnected' | 'reconnecting' | 'sessionStarted' | 'sessionEnded' | 'ready' | 'userTranscript' | 'response' | 'audio' | 'turnComplete' | 'error';
 /**
  * Event payload for 'connected' event
  */
@@ -131,34 +156,19 @@ interface SessionEndedEvent {
     timestamp: string;
 }
 /**
- * Event payload for 'streamingStarted' event - acknowledgment of audioStart
- */
-interface StreamingStartedEvent {
-    type: 'streamingStarted';
-    timestamp: string;
-}
-/**
- * Event payload for 'speechStart' event - VAD detected speech begin
- */
-interface SpeechStartEvent {
-    type: 'speechStart';
-    timestamp: string;
-}
-/**
- * Event payload for 'speechEnd' event - VAD detected speech end
+ * Event payload for 'ready' event
  */
-interface SpeechEndEvent {
-    type: 'speechEnd';
+interface ReadyEvent {
+    type: 'ready';
     timestamp: string;
 }
 /**
- * Event payload for 'transcript' event
+ * Event payload for 'userTranscript' event
+ * User's speech transcription
  */
-interface TranscriptEvent {
-    type: 'transcript';
+interface UserTranscriptEvent {
+    type: 'userTranscript';
     text: string;
-    isFinal: boolean;
-    confidence?: number;
     timestamp: string;
 }
 /**
@@ -204,14 +214,22 @@ interface ReconnectingEvent {
     delay: number;
     timestamp: string;
 }
+/**
+ * Event payload for 'turnComplete' event (both modes)
+ * Indicates the AI has finished its response turn
+ */
+interface TurnCompleteEvent {
+    type: 'turnComplete';
+    timestamp: string;
+}
 /**
  * Union type of all event payloads
  */
-type LiveSpeechEvent = ConnectedEvent | DisconnectedEvent | SessionStartedEvent | SessionEndedEvent | StreamingStartedEvent | SpeechStartEvent | SpeechEndEvent | TranscriptEvent | ResponseEvent | AudioEvent | ErrorEvent | ReconnectingEvent;
+type LiveSpeechEvent = ConnectedEvent | DisconnectedEvent | ReconnectingEvent | SessionStartedEvent | SessionEndedEvent | ReadyEvent | UserTranscriptEvent | ResponseEvent | AudioEvent | TurnCompleteEvent | ErrorEvent;
 /**
  * Simplified event handlers for common use cases
  */
-type TranscriptHandler = (text: string, isFinal: boolean) => void;
+type UserTranscriptHandler = (text: string) => void;
 type ResponseHandler = (text: string, isFinal: boolean) => void;
 type AudioHandler = (data: Uint8Array) => void;
 type ErrorHandler = (error: ErrorEvent) => void;
@@ -223,7 +241,7 @@ type ClientMessageType = 'startSession' | 'endSession' | 'audioStart' | 'audioCh
 /**
  * WebSocket message types received from server
  */
-type ServerMessageType = 'sessionStarted' | 'sessionEnded' | 'streamingStarted' | 'speechStart' | 'speechEnd' | 'transcript' | 'response' | 'audio' | 'error' | 'pong';
+type ServerMessageType = 'sessionStarted' | 'sessionEnded' | 'ready' | 'userTranscript' | 'response' | 'audio' | 'turnComplete' | 'error' | 'pong';
 /**
  * Base interface for client messages
  */
@@ -236,6 +254,8 @@ interface BaseClientMessage {
 interface StartSessionMessage extends BaseClientMessage {
     action: 'startSession';
     prePrompt?: string;
+    language?: string;
+    pipelineMode?: 'live' | 'composed';
 }
 /**
  * End session message
@@ -294,31 +314,11 @@ interface ServerSessionEndedMessage extends BaseServerMessage {
     sessionId: string;
 }
 /**
- * Streaming started message - acknowledgment of audioStart
+ * User transcript message from server (user's speech transcription)
  */
-interface ServerStreamingStartedMessage extends BaseServerMessage {
-    type: 'streamingStarted';
-}
-/**
- * Speech start message - VAD detected speech begin
- */
-interface ServerSpeechStartMessage extends BaseServerMessage {
-    type: 'speechStart';
-}
-/**
- * Speech end message - VAD detected speech end
- */
-interface ServerSpeechEndMessage extends BaseServerMessage {
-    type: 'speechEnd';
-}
-/**
- * Transcript message from server
- */
-interface ServerTranscriptMessage extends BaseServerMessage {
-    type: 'transcript';
+interface ServerUserTranscriptMessage extends BaseServerMessage {
+    type: 'userTranscript';
     text: string;
-    isFinal: boolean;
-    confidence?: number;
 }
 /**
  * Response message from server
@@ -351,10 +351,24 @@ interface ServerErrorMessage extends BaseServerMessage {
 interface ServerPongMessage extends BaseServerMessage {
     type: 'pong';
 }
+/**
+ * Turn complete message from server
+ * Indicates the AI has finished its response turn
+ */
+interface ServerTurnCompleteMessage extends BaseServerMessage {
+    type: 'turnComplete';
+}
+/**
+ * Ready message from server
+ * Indicates the session is ready for audio input
+ */
+interface ServerReadyMessage extends BaseServerMessage {
+    type: 'ready';
+}
 /**
  * Union type of all server messages
  */
-type ServerMessage = ServerSessionStartedMessage | ServerSessionEndedMessage | ServerStreamingStartedMessage | ServerSpeechStartMessage | ServerSpeechEndMessage | ServerTranscriptMessage | ServerResponseMessage | ServerAudioMessage | ServerErrorMessage | ServerPongMessage;
+type ServerMessage = ServerSessionStartedMessage | ServerSessionEndedMessage | ServerReadyMessage | ServerUserTranscriptMessage | ServerResponseMessage | ServerAudioMessage | ServerTurnCompleteMessage | ServerErrorMessage | ServerPongMessage;
 
 /**
  * Connection state
@@ -367,16 +381,15 @@ type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecti
 type LiveSpeechEventMap = {
     connected: ConnectedEvent;
     disconnected: DisconnectedEvent;
+    reconnecting: ReconnectingEvent;
     sessionStarted: SessionStartedEvent;
     sessionEnded: SessionEndedEvent;
-    streamingStarted: StreamingStartedEvent;
-    speechStart: SpeechStartEvent;
-    speechEnd: SpeechEndEvent;
-    transcript: TranscriptEvent;
+    ready: ReadyEvent;
+    userTranscript: UserTranscriptEvent;
     response: ResponseEvent;
     audio: AudioEvent;
+    turnComplete: TurnCompleteEvent;
     error: ErrorEvent;
-    reconnecting: ReconnectingEvent;
 };
 /**
  * LiveSpeech client for real-time speech-to-speech AI conversations
@@ -389,7 +402,7 @@ declare class LiveSpeechClient {
     private sessionId;
     private isStreaming;
     private readonly eventListeners;
-    private transcriptHandler;
+    private userTranscriptHandler;
     private responseHandler;
     private audioHandler;
     private errorHandler;
@@ -455,17 +468,17 @@ declare class LiveSpeechClient {
      */
     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)
+     * Set response handler
      */
     setResponseHandler(handler: ResponseHandler): void;
     /**
      * Set audio handler (simplified)
      */
     setAudioHandler(handler: AudioHandler): void;
+    /**
+     * Set user transcript handler
+     */
+    setUserTranscriptHandler(handler: UserTranscriptHandler): void;
     /**
      * Set error handler (simplified)
      */
@@ -567,4 +580,4 @@ declare class AudioEncoder {
     wrapWav(data: Uint8Array): Uint8Array;
 }
 
-export { AudioEncoder, type AudioEncoderOptions, type AudioEvent, 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 SpeechEndEvent, type SpeechStartEvent, type StreamingStartedEvent, type TranscriptEvent, type TranscriptHandler, createWavHeader, decodeBase64ToAudio, encodeAudioToBase64, extractPcmFromWav, float32ToInt16, getEndpointForRegion, int16ToFloat32, int16ToUint8, isValidRegion, uint8ToInt16, wrapPcmInWav };
+export { AudioEncoder, type AudioEncoderOptions, type AudioEvent, 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 PipelineMode, type ReadyEvent, type ReconnectingEvent, Region, Region as RegionType, type ResolvedConfig, type ResponseEvent, type ResponseHandler, type ServerMessage, type ServerMessageType, type SessionConfig, type SessionEndedEvent, type SessionStartedEvent, type TurnCompleteEvent, type UserTranscriptEvent, type UserTranscriptHandler, createWavHeader, decodeBase64ToAudio, encodeAudioToBase64, extractPcmFromWav, float32ToInt16, getEndpointForRegion, int16ToFloat32, int16ToUint8, isValidRegion, uint8ToInt16, wrapPcmInWav };

package/dist/index.js

@@ -46,7 +46,7 @@ var Region = {
 };
 var REGION_ENDPOINTS = {
   "ap-northeast-2": "wss://talk.drawdream.co.kr",
-  "us-west-2": "wss://talk..drawdream.ca"
+  "us-west-2": "wss://talk.drawdream.ca"
   // Coming soon
 };
 function getEndpointForRegion(region) {
@@ -614,7 +614,7 @@ var LiveSpeechClient = class {
   // Event listeners using a simple map
   eventListeners = /* @__PURE__ */ new Map();
   // Simplified handlers
-  transcriptHandler = null;
+  userTranscriptHandler = null;
   responseHandler = null;
   audioHandler = null;
   errorHandler = null;
@@ -730,6 +730,13 @@ var LiveSpeechClient = class {
       if (config?.prePrompt) {
         startMessage.prePrompt = config.prePrompt;
       }
+      if (config?.language) {
+        startMessage.language = config.language;
+      }
+      startMessage.pipelineMode = config?.pipelineMode ?? "live";
+      if (config?.aiSpeaksFirst) {
+        startMessage.aiSpeaksFirst = config.aiSpeaksFirst;
+      }
       this.connection.send(startMessage);
     });
   }
@@ -819,13 +826,7 @@ var LiveSpeechClient = class {
     }
   }
   /**
-   * Set transcript handler (simplified)
-   */
-  setTranscriptHandler(handler) {
-    this.transcriptHandler = handler;
-  }
-  /**
-   * Set response handler (simplified)
+   * Set response handler
    */
   setResponseHandler(handler) {
     this.responseHandler = handler;
@@ -836,6 +837,12 @@ var LiveSpeechClient = class {
   setAudioHandler(handler) {
     this.audioHandler = handler;
   }
+  /**
+   * Set user transcript handler
+   */
+  setUserTranscriptHandler(handler) {
+    this.userTranscriptHandler = handler;
+  }
   /**
    * Set error handler (simplified)
    */
@@ -914,36 +921,12 @@ var LiveSpeechClient = class {
           timestamp: message.timestamp
         });
         break;
-      case "streamingStarted":
-        this.emit("streamingStarted", {
-          type: "streamingStarted",
-          timestamp: message.timestamp
-        });
-        break;
-      case "speechStart":
-        this.emit("speechStart", {
-          type: "speechStart",
-          timestamp: message.timestamp
-        });
-        break;
-      case "speechEnd":
-        this.emit("speechEnd", {
-          type: "speechEnd",
-          timestamp: message.timestamp
-        });
-        break;
-      case "transcript": {
-        const transcriptEvent = {
-          type: "transcript",
-          text: message.text,
-          isFinal: message.isFinal,
+      case "ready": {
+        const readyEvent = {
+          type: "ready",
           timestamp: message.timestamp
         };
-        if (message.confidence !== void 0) {
-          transcriptEvent.confidence = message.confidence;
-        }
-        this.emit("transcript", transcriptEvent);
-        this.transcriptHandler?.(message.text, message.isFinal);
+        this.emit("ready", readyEvent);
         break;
       }
       case "response": {
@@ -970,6 +953,24 @@ var LiveSpeechClient = class {
         this.audioHandler?.(audioData);
         break;
       }
+      case "userTranscript": {
+        const userTranscriptEvent = {
+          type: "userTranscript",
+          text: message.text,
+          timestamp: message.timestamp
+        };
+        this.emit("userTranscript", userTranscriptEvent);
+        this.userTranscriptHandler?.(message.text);
+        break;
+      }
+      case "turnComplete": {
+        const turnCompleteEvent = {
+          type: "turnComplete",
+          timestamp: message.timestamp
+        };
+        this.emit("turnComplete", turnCompleteEvent);
+        break;
+      }
       case "error":
         this.handleError(message.code, message.message);
         break;

package/dist/index.mjs

@@ -7,7 +7,7 @@ var Region = {
 };
 var REGION_ENDPOINTS = {
   "ap-northeast-2": "wss://talk.drawdream.co.kr",
-  "us-west-2": "wss://talk..drawdream.ca"
+  "us-west-2": "wss://talk.drawdream.ca"
   // Coming soon
 };
 function getEndpointForRegion(region) {
@@ -575,7 +575,7 @@ var LiveSpeechClient = class {
   // Event listeners using a simple map
   eventListeners = /* @__PURE__ */ new Map();
   // Simplified handlers
-  transcriptHandler = null;
+  userTranscriptHandler = null;
   responseHandler = null;
   audioHandler = null;
   errorHandler = null;
@@ -691,6 +691,13 @@ var LiveSpeechClient = class {
       if (config?.prePrompt) {
         startMessage.prePrompt = config.prePrompt;
       }
+      if (config?.language) {
+        startMessage.language = config.language;
+      }
+      startMessage.pipelineMode = config?.pipelineMode ?? "live";
+      if (config?.aiSpeaksFirst) {
+        startMessage.aiSpeaksFirst = config.aiSpeaksFirst;
+      }
       this.connection.send(startMessage);
     });
   }
@@ -780,13 +787,7 @@ var LiveSpeechClient = class {
     }
   }
   /**
-   * Set transcript handler (simplified)
-   */
-  setTranscriptHandler(handler) {
-    this.transcriptHandler = handler;
-  }
-  /**
-   * Set response handler (simplified)
+   * Set response handler
    */
   setResponseHandler(handler) {
     this.responseHandler = handler;
@@ -797,6 +798,12 @@ var LiveSpeechClient = class {
   setAudioHandler(handler) {
     this.audioHandler = handler;
   }
+  /**
+   * Set user transcript handler
+   */
+  setUserTranscriptHandler(handler) {
+    this.userTranscriptHandler = handler;
+  }
   /**
    * Set error handler (simplified)
    */
@@ -875,36 +882,12 @@ var LiveSpeechClient = class {
           timestamp: message.timestamp
         });
         break;
-      case "streamingStarted":
-        this.emit("streamingStarted", {
-          type: "streamingStarted",
-          timestamp: message.timestamp
-        });
-        break;
-      case "speechStart":
-        this.emit("speechStart", {
-          type: "speechStart",
-          timestamp: message.timestamp
-        });
-        break;
-      case "speechEnd":
-        this.emit("speechEnd", {
-          type: "speechEnd",
-          timestamp: message.timestamp
-        });
-        break;
-      case "transcript": {
-        const transcriptEvent = {
-          type: "transcript",
-          text: message.text,
-          isFinal: message.isFinal,
+      case "ready": {
+        const readyEvent = {
+          type: "ready",
           timestamp: message.timestamp
         };
-        if (message.confidence !== void 0) {
-          transcriptEvent.confidence = message.confidence;
-        }
-        this.emit("transcript", transcriptEvent);
-        this.transcriptHandler?.(message.text, message.isFinal);
+        this.emit("ready", readyEvent);
         break;
       }
       case "response": {
@@ -931,6 +914,24 @@ var LiveSpeechClient = class {
         this.audioHandler?.(audioData);
         break;
       }
+      case "userTranscript": {
+        const userTranscriptEvent = {
+          type: "userTranscript",
+          text: message.text,
+          timestamp: message.timestamp
+        };
+        this.emit("userTranscript", userTranscriptEvent);
+        this.userTranscriptHandler?.(message.text);
+        break;
+      }
+      case "turnComplete": {
+        const turnCompleteEvent = {
+          type: "turnComplete",
+          timestamp: message.timestamp
+        };
+        this.emit("turnComplete", turnCompleteEvent);
+        break;
+      }
       case "error":
         this.handleError(message.code, message.message);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawdream/livespeech",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Real-time speech-to-speech AI conversation SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",