@shivamprasad99/voice-client

Headless browser SDK for realtime voice sessions.

This package intentionally does not render UI. Host applications own rendering through onEvent and onStateChange.

Example

import { createVoiceSession } from '@shivamprasad99/voice-client';

const session = createVoiceSession({
  transport: 'mock',
  onEvent(event) {
    console.log(event.type, event);
  },
  onStateChange(state) {
    console.log(state.turnState, state.assistantText);
  }
});

await session.start();
await session.sendText('What does this product do?');
await session.interrupt();
await session.stop();

WebSocket Transport

const session = createVoiceSession({
  transport: 'websocket',
  realtimeUrl: 'wss://voice.example.com/session',
  token: 'ephemeral-session-token',
  onEvent(event) {
    renderCustomUi(event);
  }
});

Host Token Endpoint

const session = createVoiceSession({
  transport: 'websocket',
  tokenEndpoint: '/api/voice/session',
  onConfig(config) {
    // Host application can apply custom UI/branding.
  }
});

The endpoint must return ephemeral_token or token. For WebSocket sessions, it should also return realtime_url unless the client is created with realtimeUrl.

Browser Audio Primitives

The package exports optional browser controllers:

import {
  createBrowserMicrophoneController,
  createBrowserPlaybackController
} from '@shivamprasad99/voice-client';

These are low-level primitives. They do not render UI and do not choose a provider.

For Node-based smoke tests, pass a WebSocket implementation:

import { WebSocket } from 'ws';

const session = createVoiceSession({
  transport: 'websocket',
  realtimeUrl: 'ws://127.0.0.1:7071/session',
  token: 'dev-token',
  WebSocketImpl: WebSocket
});