@stormee-websocket/library

Framework-agnostic WebSocket library for real-time audio streaming with MessagePack and Opus encoding.

Features

- 🔌 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

Installation

$3

``bash
npm install ./npmPackages/@stormee-websocket-library-1.0.0.tgz
`

$3

`bash
npm install @stormee-websocket/library
`

Usage

$3

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();
`

$3

`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 (


`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

#### StormeeService

Main 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

#### StormeeVSCodeAdapter

Adapter 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

`
@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
``

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Support

For issues and questions, please open a GitHub issue.