@drawdream/livespeech 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DrawDream Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# LiveSpeech SDK for TypeScript
+
+[![npm](https://img.shields.io/npm/v/@drawdream/livespeech.svg)](https://www.npmjs.com/package/@drawdream/livespeech)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A TypeScript/JavaScript SDK for real-time speech-to-speech AI conversations.
+
+## Installation
+
+```bash
+npm install @drawdream/livespeech
+# or
+yarn add @drawdream/livespeech
+# or
+pnpm add @drawdream/livespeech
+```
+
+## Quick Start
+
+```typescript
+import { LiveSpeechClient, Region } from '@drawdream/livespeech';
+
+const client = new LiveSpeechClient({
+  region: 'ap-northeast-2',  // or Region.AP_NORTHEAST_2
+  apiKey: 'your-api-key',
+});
+
+// Handle events
+client.setTranscriptHandler((text, isFinal) => {
+  console.log(`Transcript: ${text} (final: ${isFinal})`);
+});
+
+client.setResponseHandler((text, isFinal) => {
+  console.log(`AI Response: ${text}`);
+});
+
+client.setAudioHandler((audioData) => {
+  // Play audio through speakers
+});
+
+// Connect and start session
+await client.connect();
+await client.startSession({
+  prePrompt: 'You are a helpful assistant.',
+});
+
+// Send audio
+client.sendAudio(audioBuffer);
+```
+
+## API Reference
+
+### Regions
+
+The SDK provides built-in region support, so you don't need to remember endpoint URLs:
+
+| 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 |
+
+### LiveSpeechClient
+
+#### Constructor Options
+
+| 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 |
+
+#### Methods
+
+| 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 |
+
+#### Event Handlers
+
+```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) => {});
+```
+
+### SessionConfig
+
+| 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 |
+
+## Audio Utilities
+
+The SDK includes audio encoding/decoding utilities:
+
+```typescript
+import {
+  encodeAudioToBase64,
+  decodeBase64ToAudio,
+  float32ToInt16,
+  int16ToFloat32,
+  wrapPcmInWav,
+} from '@drawdream/livespeech';
+
+// Convert Float32 audio samples to PCM16
+const pcmData = float32ToInt16(float32Samples);
+
+// Create WAV file from PCM data
+const wavFile = wrapPcmInWav(pcmData, { sampleRate: 16000 });
+```
+
+## Browser Usage
+
+The SDK works in both Node.js and browser environments:
+
+```html
+<script type="module">
+import { LiveSpeechClient } from '@drawdream/livespeech';
+
+// 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>
+```
+
+## License
+
+MIT