Framework-agnostic WebSocket library for real-time audio streaming with MessagePack and Opus encoding
npm install stormee-websocketFramework-agnostic WebSocket library for real-time audio streaming with MessagePack and Opus encoding.
- š WebSocket Management - Auto-reconnection, heartbeat, message queuing
- šµ Audio Streaming - MessagePack decoding, Opus audio playback
- š Resumption Support - Resume from last position after disconnect
- āļø React Integration - Ready-to-use React hooks
- š§ VS Code Extension Support - Adapter for VS Code webviews
- š¦ Framework Agnostic - Use in any JavaScript environment
``bash`
npm install ./npmPackages/@stormee-websocket-library-1.0.0.tgz
`bash`
npm install @stormee-websocket/library
Use in any JavaScript/TypeScript environment:
`typescript
import { StormeeService } from '@stormee-websocket/library/core';
const service = new StormeeService({
websocket: {
url: 'ws://localhost:8000/ws',
autoReconnect: true,
maxReconnectAttempts: 3,
},
audio: {
sampleRate: 24000,
channels: 1,
autoPlay: true,
initialVolume: 1.0,
},
eventHandlers: {
onTranscription: (text) => console.log('Transcription:', text),
onAudioChunk: (data) => console.log('Audio received'),
onStreamEnd: () => console.log('Stream ended'),
onError: (error) => console.error('Error:', error),
},
debug: true,
});
// Initialize
await service.initialize();
// Connect
await service.connect('session-uuid');
// Start streaming
await service.startStreaming({
sessionId: 'session-uuid',
conciergeName: 'Stormee',
userQuery: 'Hello, how are you?',
chat_history: [],
metadata: { userName: 'John' },
queryNumber: '1',
});
// Control playback
service.setVolume(0.8);
service.mute();
service.unmute();
service.stopStreaming();
// Disconnect
service.disconnect();
`
`typescript
import { useStormee } from '@stormee-websocket/library/react';
function MyComponent() {
const stormee = useStormee({
websocket: {
url: 'ws://localhost:8000/ws',
autoReconnect: true,
},
audio: {
sampleRate: 24000,
autoPlay: true,
},
sessionId: 'your-session-uuid',
eventHandlers: {
onTranscription: (text) => setTranscription(text),
onStreamEnd: () => console.log('Done'),
},
});
const handleSend = async () => {
await stormee.connect('session-uuid');
await stormee.startStreaming({
sessionId: 'session-uuid',
conciergeName: 'Stormee',
userQuery: 'Tell me a story',
chat_history: [],
metadata: {},
queryNumber: '1',
});
};
return (
$3
`typescript
import { StormeeVSCodeAdapter } from '@stormee-websocket/library/vscode';
import * as vscode from 'vscode';// In your extension activation
export function activate(context: vscode.ExtensionContext) {
const adapter = new StormeeVSCodeAdapter(
{
websocket: {
url: 'ws://localhost:8000/ws',
autoReconnect: true,
},
audio: {
sampleRate: 24000,
autoPlay: true,
},
extensionContext: context,
persistState: true, // Save state between sessions
eventHandlers: {
onTranscription: (text) => {
// Update webview with transcription
},
},
},
{
onStateSyncToWebview: (state) => {
// Send state to webview
webviewPanel.webview.postMessage({
type: 'stateUpdate',
state,
});
},
}
);
await adapter.initialize();
// Handle messages from webview
webviewPanel.webview.onDidReceiveMessage((message) => {
adapter.handleWebviewMessage(message);
});
// Cleanup
context.subscriptions.push({
dispose: () => adapter.dispose(),
});
}
`API Reference
$3
####
StormeeServiceMain service class for managing WebSocket connection and audio streaming.
Methods:
-
initialize() - Initialize audio processor
- connect(sessionId) - Connect to WebSocket
- disconnect() - Disconnect from WebSocket
- startStreaming(request) - Start audio streaming
- stopStreaming() - Stop streaming
- setVolume(volume) - Set volume (0-1)
- mute() - Mute audio
- unmute() - Unmute audio
- getState() - Get current state
- getAudioState() - Get audio state$3
####
useStormee(options)React hook that wraps StormeeService with automatic state management.
Returns:
-
state - Service state
- audioState - Audio state
- isConnected - Connection status
- isStreaming - Streaming status
- connect() - Connect function
- disconnect() - Disconnect function
- startStreaming() - Start streaming function
- stopStreaming() - Stop streaming function
- Audio control functions$3
####
StormeeVSCodeAdapterAdapter for VS Code extensions with webview messaging and state persistence.
Configuration
$3
`typescript
interface WebSocketConfig {
url: string; // WebSocket URL
autoReconnect?: boolean; // Auto-reconnect (default: true)
maxReconnectAttempts?: number; // Max attempts (default: 3)
reconnectDelay?: number; // Delay in ms (default: 500)
connectionTimeout?: number; // Timeout in ms (default: 10000)
heartbeatInterval?: number; // Heartbeat in ms (default: 30000)
}
`$3
`typescript
interface AudioConfig {
sampleRate?: number; // Sample rate (default: 24000)
channels?: number; // Channels (default: 1)
autoPlay?: boolean; // Auto-play (default: true)
initialVolume?: number; // Volume 0-1 (default: 1.0)
}
`Building from Source
`bash
Install dependencies
npm installBuild all targets
npm run buildBuild specific target
npm run build:core
npm run build:react
npm run build:vscodeCreate .tgz package
npm run pack:local
`Architecture
`
@stormee-websocket/
āāā core/ ā Framework-agnostic (works everywhere)
ā āāā StormeeService.ts - Main orchestrator
ā āāā WebSocketManager.ts - WebSocket with auto-reconnect
ā āāā MsgPackOpusProcessor.ts - Audio decoding & playback
ā āāā types.ts - Type definitions
āāā react/ ā React-specific wrapper
ā āāā useStormee.ts - React hook
āāā vscode/ ā VS Code extension adapter
āāā StormeeVSCodeAdapter.ts - Extension utilities
``MIT
Contributions welcome! Please open an issue or PR.
For issues and questions, please open a GitHub issue.