@voxhq/web-sdk

The official web SDK for VoxHQ for audio recording and AI note generation.

Installation

npm install @voxhq/web-sdk
# or
pnpm add @voxhq/web-sdk
# or
yarn add @voxhq/web-sdk

Usage

Initialize the client with your API token.

import { initializeVox } from '@voxhq/web-sdk';

// Initialize the client
const vox = initializeVox('your-api-token', {
  // Optional: Custom API URL
  // baseUrl: 'https://api.your-domain.com'
});

// 1. Setup Event Listeners (before starting)
const unsubscribeNotes = vox.on('notes', (notes) => {
  console.log('Notes updated:', notes);
  // notes is an array of Note objects
});

const unsubscribeStatus = vox.on('status', (status) => {
  console.log('Current status:', status);
  // status is 'processing' | 'writing' | 'completed'
});

const unsubscribeError = vox.on('error', (error) => {
  console.error('Session error:', error);
});

// 2. Start Recording a Session
// Pass a unique session ID (e.g., user_id/appointment_id)
const sessionId = 'user_123/appt_456';
vox.start(sessionId);

// ... Recording in progress ...

// 3. Stop Recording
// This stops recording but continues polling for final notes
vox.stop();

// 4. Clean up when done
// Remove event listeners
unsubscribeNotes();
unsubscribeStatus();
unsubscribeError();

// Close the client (stops all polling and cleans up resources)
vox.close();

File Upload

Upload a pre-recorded audio file for a session instead of recording live. Useful for testing.

import { uploadFile } from '@voxhq/web-sdk';

const file = document.querySelector('input[type=file]').files[0];
const handle = uploadFile('your-api-token', 'user_123/appt_456', file);

handle.on('progress', ({ loaded, total }) => {
  console.log(`${Math.round(loaded / total * 100)}%`);
});

handle.on('notes', (notes) => {
  console.log('Notes updated:', notes);
});

handle.on('status', (status) => {
  if (status === 'completed') handle.close();
});

handle.on('error', (error) => {
  console.error('Upload error:', error);
});

uploadFile(token, sessionId, file, options?)

Uploads a pre-recorded audio file for a session.

Parameters:

• token (string | () => string): Your Vox API token or a getter function
• sessionId (string): Unique identifier for this session
• file (Blob): The audio file to upload
• options (object, optional):
  • baseUrl (string): Custom API base URL
  • chunkSize (number): Upload chunk size in bytes. Default: 5MB
  • mimeType (string): Override the file's MIME type

Returns: UploadHandle

UploadHandle

• on(event, listener) - Subscribe to events (notes, status, error, progress). Returns unsubscribe function.
• off(event, listener) - Remove a listener
• close() - Cancel upload and clean up resources

API Reference

initializeVox(token, options?)

Creates a new Vox client instance.

Parameters:

• token (string): Your Vox API token
• options (object, optional):
  • baseUrl (string, optional): Custom API base URL. Defaults to https://api.voxdenta.com/v1

Returns: VoxClient

VoxClient

on(event, listener)

Subscribe to client events. Returns an unsubscribe function.

Events:

• 'notes': Emitted when notes are updated. Listener receives (notes: Note[])
• 'status': Emitted when session status changes. Listener receives (status: SessionStatus)
• 'error': Emitted when an error occurs. Listener receives (error: Error)

Example:

const unsubscribe = vox.on('notes', (notes) => {
  console.log('Received', notes.length, 'notes');
});
// Later...
unsubscribe();

off(event, listener)

Remove a specific event listener.

start(sessionId)

Start recording audio for a session. Automatically begins polling for notes.

Parameters:

• sessionId (string): Unique identifier for this recording session

stop()

Stop the current recording. Note polling continues until notes are completed.

close()

Close the client and clean up all resources (stops recording, polling, and removes all listeners).

getAnalyzerBandLevels(bands)

Get current audio analyzer band levels for visualization.

Parameters:

• bands (number): Number of frequency bands to analyze

Returns: Float32Array of audio levels

Types

Note

interface Note {
  id: string;
  name: string;
  status: 'pending' | 'generating' | 'ready' | 'failed';
  content: string;
  updatedAt: string | Date;
}

SessionStatus

type SessionStatus = 'processing' | 'writing' | 'completed';

Features

• Audio Recording: Robust in-browser audio capture with automatic retry handling.
• Real-time Updates: Event-driven API for note generation events.
• Smart Polling: Automatic polling with exponential backoff and visibility-aware pausing.
• Audio Visualization: Built-in analyzer for frequency band visualization.
• AI Integration: Seamlessly connect with VoxHQ backend services.