@livefantasia/speechengine-client 0.5.1-alpha

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LiveFantasia.ai
+
+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,402 @@
+# LiveFantasia SpeechEngine Client for Node.js
+
+[![npm version](https://badge.fury.io/js/%40livefantasia%2Fspeechengine-client.svg)](https://badge.fury.io/js/%40livefantasia%2Fspeechengine-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+
+A powerful Node.js client library for the LiveFantasia SpeechEngine platform, providing real-time speech recognition capabilities through WebSocket streaming.
+
+## Features
+
+- 🎤 **Real-time Speech Recognition**: Stream audio data and receive live transcription results
+- 🌐 **WebSocket Streaming**: Efficient real-time communication with the SpeechEngine API
+- 🔄 **Multiple Sessions**: Support for concurrent streaming sessions
+- 🎯 **TypeScript Support**: Full TypeScript definitions included
+- 📊 **Session Management**: Built-in session lifecycle management and statistics
+- 🛠️ **Utility Classes**: Helper classes like `TranscriptionManager` for easy result handling
+- 🎵 **Audio Format Support**: Support 16KHz, 16Bits, mono Wave format.
+- 🌍 **Multi-language**: Support for multiple languages
+- 📝 **Comprehensive Examples**: Rich set of examples for different use cases
+
+## Installation
+
+```bash
+npm install @livefantasia/speechengine-client
+```
+
+### Optional Dependencies
+
+For real-time microphone examples, you may want to install one of these packages depending on your platform:
+
+```bash
+# For Apple Silicon compatibility (recommended)
+npm install mic
+```
+
+> **Note**: These packages are only required if you want to run the real-time microphone examples. They are not needed for the core library functionality.
+
+#### Platform Compatibility Notes
+
+**Apple Silicon (M1/M2/M3) Macs:**
+- ✅ **Recommended**: Use `mic` module for real-time microphone examples
+- ❌ **Avoid**: `naudiodon` can cause segmentation faults and build failures on ARM architecture
+
+**Intel/x86 Systems:**
+- ✅ Both `mic` and `naudiodon` should work
+- 💡 **Tip**: `mic` is more universally compatible across platforms
+
+**CI/CD Environments:**
+- ⚠️ **Important**: `naudiodon` requires native compilation and may fail in containerized environments (Ubuntu, Alpine Linux)
+- ✅ **Solution**: Use `mic` or exclude audio dependencies from CI builds if not needed
+
+**Build Issues with `naudiodon`:**
+If you encounter build failures related to `naudiodon`, this is typically due to:
+- Missing system audio libraries (ALSA, PulseAudio on Linux)
+- Incompatible architecture (ARM vs x86)
+- Missing build tools (node-gyp, Python, C++ compiler)
+
+**Recommended approach**: Use the `real-time-microphone-node-mic.ts` example with the `mic` module for better cross-platform compatibility.
+
+## Quick Start
+
+### 1. Set up your API key
+
+```bash
+export SPEECHENGINE_API_KEY="your-api-key-here"
+```
+
+### 2. Basic streaming example
+
+```typescript
+import { SpeechEngineClient, TranscriptionManager } from '@livefantasia/speechengine-client';
+import * as fs from 'fs';
+
+async function basicExample() {
+  // Initialize the client
+  const client = new SpeechEngineClient({
+    apiKey: process.env.SPEECHENGINE_API_KEY!
+  });
+
+  try {
+    // Create a streaming session
+    const session = await client.createSession({
+      language: 'en',
+    });
+
+    // Use TranscriptionManager for easy result handling
+    const transcriptionManager = new TranscriptionManager();
+
+    // Set up event handlers
+    session.on('ready', () => {
+      console.log('Session ready, starting audio stream...');
+    });
+
+    session.on('transcriptionUpdate', (message) => {
+      transcriptionManager.processUpdate(message);
+      console.log('Live transcription:', transcriptionManager.getCurrentTranscription());
+    });
+
+    session.on('end', () => {
+      console.log('Final transcription:', transcriptionManager.getFinalTranscription());
+    });
+
+    // Connect to the session
+    await session.connect();
+
+    // Stream audio data
+    const audioData = fs.readFileSync('path/to/your/audio.wav');
+    await session.sendAudio(audioData);
+    await session.endStream();
+
+  } catch (error) {
+    console.error('Error:', error);
+  } finally {
+    await client.close();
+  }
+}
+
+basicExample();
+```
+
+## Conventions
+
+- All message payloads emitted to your handlers use camelCase, consistent with Node.js conventions.
+  - `segmentId`, `text`, `startMs`, `endMs`, `isFinal`, `utteranceOrder`, `words[]` with `word`, `startMs`, `endMs`.
+- Stream start options are provided in camelCase via `startStream(options)` and are converted internally to the server’s snake_case.
+- Configure defaults at session creation using `SessionConfig` camelCase fields.
+
+### Stream Start Options
+
+Use `startStream(options)` to enable word timestamps and Voice Activity Detection (VAD):
+
+```typescript
+await session.startStream({
+  wordTimestamp: true,
+  vadThreshold: 0.6,              // number in (0,1)
+  vadMinSilenceDuration: 0.2,     // number in (0,1)
+  vadMinSpeechDuration: 0.2       // number in (0,1)
+});
+```
+
+These options are validated locally; invalid values throw a `ClientErrorCode.INVALID_PARAMETER` error before any network call.
+
+## API Reference
+
+### SpeechEngineClient
+
+The main client class for interacting with the SpeechEngine API.
+
+#### Constructor
+
+```typescript
+const client = new SpeechEngineClient(config: SpeechEngineClientConfig);
+```
+
+**Configuration Options:**
+- `apiKey: string` - Your SpeechEngine API key
+- `baseUrl?: string` - Base URL for the API (optional)
+- `timeout?: number` - Connection timeout in milliseconds (default: 10000)
+
+#### Methods
+
+##### `createSession(config: SessionConfig): Promise<StreamingSession>`
+
+Creates a new streaming session.
+
+**Session Configuration:**
+- `language: Language` - Language code (e.g., 'en', 'es', 'fr')
+- `enableWordTimestamps?: boolean` - Enable word-level timestamps
+- `maxAlternatives?: number` - Maximum number of alternative transcriptions
+
+##### `close(): Promise<void>`
+
+Closes the client and all active sessions.
+
+### StreamingSession
+
+Represents an active streaming session.
+
+#### Events
+
+- `ready` - Session is ready to receive audio
+- `transcriptionUpdate` - New transcription data received
+- `end` - Session ended
+- `error` - Error occurred
+
+#### Methods
+
+##### `connect(): Promise<void>`
+
+Connects to the streaming session.
+
+##### `sendAudio(audioData: Buffer): Promise<void>`
+
+Sends audio data to the session.
+
+##### `endStream(): Promise<void>`
+
+Ends the audio stream and finalizes transcription.
+
+##### `disconnect(): Promise<void>`
+
+Disconnects from the session.
+
+### TranscriptionManager
+
+Utility class for managing transcription results.
+
+#### Methods
+
+##### `processUpdate(message: TranscriptionUpdateMessage): void`
+
+Processes a transcription update message.
+
+##### `getCurrentTranscription(): string`
+
+Gets the current assembled transcription.
+
+##### `getFinalTranscription(): string`
+
+Gets the final transcription result.
+
+##### `getSegments(): TranscriptionSegment[]`
+
+Gets all transcription segments.
+
+## Examples
+
+The library comes with comprehensive examples in the `examples/` directory:
+
+### Basic Examples
+
+- **`simple-streaming.ts`** - Recommended streaming workflow using TranscriptionManager
+- **`minimal-streaming.ts`** - Direct event handling without utilities
+
+### Advanced Examples
+
+- **`multiple-sessions.ts`** - Managing multiple concurrent sessions
+- **`error-handling.ts`** - Comprehensive error handling patterns
+
+### Streaming Examples
+
+- **`real-time-microphone-node-mic.ts`** - Real-time microphone streaming with mic module (Apple Silicon compatible)
+- **`file-streaming.ts`** - Streaming audio from files
+
+### Running Examples
+
+```bash
+# Basic streaming example
+npx ts-node examples/basic/simple-streaming.ts
+
+# Streaming with VAD options
+npx ts-node examples/basic/simple-streaming-vad.ts
+
+# Real-time microphone (Apple Silicon compatible)
+npm install mic
+npx ts-node examples/streaming/real-time-microphone-node-mic.ts
+
+# Multiple sessions
+npx ts-node examples/advanced/multiple-sessions.ts
+```
+
+## Apple Silicon Compatibility
+
+The real-time microphone example uses the `mic` module which provides excellent compatibility with Apple Silicon Macs (M1/M2/M3). This avoids the known issues with `naudiodon`/PortAudio that can cause segmentation faults on ARM-based Macs.
+
+```bash
+npm install mic
+npx ts-node examples/streaming/real-time-microphone-node-mic.ts
+```
+
+### Why `mic` over `naudiodon`?
+
+**Cross-Platform Stability:**
+- `mic` works reliably across macOS (Intel & Apple Silicon), Linux, and Windows
+- `naudiodon` has known compatibility issues with ARM architecture and CI/CD environments
+
+**Build Reliability:**
+- `mic` has fewer native dependencies and simpler build requirements
+- `naudiodon` requires PortAudio and can fail in containerized environments (Docker, CI/CD)
+
+**Development Experience:**
+- `mic` provides a simpler API for basic microphone access
+- Less prone to segmentation faults and memory issues on Apple Silicon
+
+If you encounter build issues with audio dependencies in your CI/CD pipeline, consider excluding them from your production dependencies or using the file-based streaming examples instead.
+
+
+
+## Supported Languages
+
+- English (`en`)
+- Spanish (`es`)
+- French (`fr`)
+- German (`de`)
+- Italian (`it`)
+- Portuguese (`pt`)
+- And more...
+
+## Error Handling
+
+The library provides comprehensive error handling with specific error types:
+
+```typescript
+import { SpeechEngineError } from '@livefantasia/speechengine-client';
+
+try {
+  await session.connect();
+} catch (error) {
+  if (error instanceof SpeechEngineError) {
+    console.error('SpeechEngine Error:', error.code, error.message);
+    console.error('Category:', error.category);
+    console.error('Retryable:', error.retryable);
+  }
+}
+```
+
+## Logging
+The client’s logs can be routed into your application’s logger. By default, logs print to the console at `info` level. 
+
+### Winston integration example
+
+```typescript
+import { createSpeechEngineClient } from '@livefantasia/speechengine-client';
+import winston from 'winston';
+
+const appLogger = winston.createLogger({
+  level: 'info',
+  transports: [new winston.transports.Console()],
+});
+
+const client = createSpeechEngineClient({
+  baseUrl: 'https://api.livefantasia.com',
+  apiKey: process.env.SPEECHENGINE_API_KEY!,
+  logger: {
+    level: 'info',
+    enableConsole: false,
+    customHandler: (entry) => {
+      const level = entry.level.toLowerCase();
+      const prefix = `${entry.component}${entry.sessionId ? ':' + entry.sessionId : ''}`;
+      const message = `${prefix} - ${entry.message}`;
+      const meta = entry.data ? { data: entry.data, ts: entry.timestamp.toISOString() } : { ts: entry.timestamp.toISOString() };
+      appLogger.log({ level, message, ...meta });
+    },
+  },
+});
+```
+
+Notes:
+- Set `enableConsole: false` to prevent duplicate console output.
+- `customHandler` receives structured entries; you control formatting and routing.
+- Sensitive auth data (JWTs and `Bearer` tokens) is redacted before logging.
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+npm run test:coverage
+```
+
+### Linting
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### Type Checking
+
+```bash
+npm run type-check
+```
+
+## Requirements
+
+- Node.js >= 20.0.0
+- TypeScript >= 5.1.0 (for development)
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [API Documentation](docs/)
+- **Issues**: [GitHub Issues](https://github.com/livefantasia/speechengine-client-node/issues)
+- **Examples**: See the `examples/` directory for comprehensive usage examples
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines for more information.
+
+---
+
+Made with ❤️ by [LiveFantasia](https://livefantasia.com)

package/dist/client/SpeechEngineClient.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Main SpeechEngine Client for LiveFantasia SpeechEngine Platform
+ * Provides session management and WebSocket streaming capabilities
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import { SpeechEngineClientConfig, SessionConfig } from '../types';
+import { StreamingSession } from '../session/StreamingSession';
+/**
+ * Main client class for interacting with LiveFantasia SpeechEngine
+ * Supports multiple concurrent sessions and thread-safe operations
+ */
+export declare class SpeechEngineClient extends EventEmitter {
+    private readonly config;
+    private readonly activeSessions;
+    private readonly sessionStats;
+    private readonly logger;
+    constructor(config: SpeechEngineClientConfig);
+    /**
+     * Create a new streaming session by initiating with the Control Plane.
+     * This method handles token generation and WebSocket connection.
+     * @param config Configuration for the session, like language and sample rate.
+     * @returns A StreamingSession instance ready to be connected.
+     */
+    createSession(config?: Partial<SessionConfig>): Promise<StreamingSession>;
+    /**
+     * Validates an API response and returns detailed error information
+     */
+    private validateApiResponse;
+    /**
+     * Intelligently parse ControlPlane error responses and map to appropriate error codes
+     */
+    private parseControlPlaneError;
+    getSession(sessionId: string): StreamingSession | undefined;
+    getActiveSessions(): string[];
+    getActiveSessionCount(): number;
+    closeSession(sessionId: string): Promise<void>;
+    closeAllSessions(): Promise<void>;
+    getStats(): {
+        activeSessionCount: number;
+        totalSessionsCreated: number;
+    };
+    private validateAndSetDefaults;
+    private setupLogger;
+    private mapLogLevel;
+    private setupSessionEventHandlers;
+    private cleanupSession;
+    /**
+     * Validate VAD parameters to ensure they are within valid ranges
+     */
+    private validateVadParameters;
+}
+export declare function createSpeechEngineClient(config: SpeechEngineClientConfig): SpeechEngineClient;