@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

Local Installation (Development)

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

From npm Registry

npm install @stormee-websocket/library

Usage

1. Core (Framework-Agnostic)

Use in any JavaScript/TypeScript environment:

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

2. React Integration

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 (
    <div>
      <button onClick={handleSend}>Send</button>
      <button onClick={() => stormee.setVolume(0.5)}>50% Volume</button>
      <button onClick={() => stormee.mute()}>Mute</button>
      
      <div>Connected: {stormee.isConnected ? 'Yes' : 'No'}</div>
      <div>Streaming: {stormee.isStreaming ? 'Yes' : 'No'}</div>
      <div>Volume: {stormee.audioState.volume}</div>
    </div>
  );
}

3. VS Code Extension

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

Core Classes

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

React Hook

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

VS Code Adapter

StormeeVSCodeAdapter

Adapter for VS Code extensions with webview messaging and state persistence.

Configuration

WebSocket Config

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)
}

Audio Config

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

# Install dependencies
npm install

# Build all targets
npm run build

# Build specific target
npm run build:core
npm run build:react
npm run build:vscode

# Create .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

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Support

For issues and questions, please open a GitHub issue.