@echopilot/web-sdk NPM

EchoPilot Web SDK

A powerful web SDK for integrating EchoPilot's voice AI capabilities into your web applications. This SDK provides a seamless way to add voice interactions, real-time transcription, and AI-powered conversations to your web apps.

Features

🎙️ Real-time voice interactions
🤖 AI-powered conversations
🔊 Text-to-speech capabilities
🎧 Audio device management
📊 Usage tracking
🔄 Event-driven architecture
🛡️ Error handling and logging
🎯 Smart Voice Activity Detection (VAD)

Installation

npm install @echopilot/web-sdk

Quick Start

import EchoPilot from '@echopilot/web-sdk';

// Initialize the SDK with your API key
const echopilot = new EchoPilot('your-api-key');

// Configure your assistant
const assistantConfig = {
  model: {
    provider: 'openai',
    model: 'gpt-4',
    messages: [
      {
        role: 'system',
        content: 'You are a helpful assistant.'
      }
    ]
  },
  voice: {
    provider: '11labs',
    voiceId: 'your-voice-id'
  }
};

// Start a conversation
await echopilot.start(assistantConfig);

// Send a message
await echopilot.send({
  type: 'add-message',
  message: {
    role: 'user',
    content: 'Hello!'
  }
});

// Listen for events
echopilot.on('message', (message) => {
  console.log('Received message:', message);
});

echopilot.on('error', (error) => {
  console.error('Error:', error);
});

// Stop the conversation
await echopilot.stop();

API Reference

Constructor

new EchoPilot(apiKey: string)

Creates a new EchoPilot instance.

apiKey - Your EchoPilot API key

Methods

start(assistant: AssistantConfig | string, assistantOverrides?: any)

Starts a conversation with the specified assistant configuration.

await echopilot.start(assistantConfig);

assistant - Assistant configuration object or ID
assistantOverrides - Optional overrides for the assistant configuration
Returns: Promise that resolves when the conversation starts
Throws: Error if initialization fails or conversation cannot be started

stop()

Ends the current conversation and tracks usage.

await echopilot.stop();

Returns: Promise that resolves when the conversation ends
Throws: Error if the conversation cannot be stopped

send(message: { type: 'add-message'; message: Message })

Sends a message to the assistant.

await echopilot.send({
  type: 'add-message',
  message: {
    role: 'user',
    content: 'Hello!'
  }
});

message - The message to send
Returns: Promise that resolves when the message is sent
Throws: Error if the message cannot be sent

on(event: EventType, callback: EventCallback)

Registers an event handler.

echopilot.on('message', (message) => {
  console.log('Received message:', message);
});

event - The event to listen for
callback - The callback function to handle the event

off(event: EventType, callback: EventCallback)

Removes an event handler.

echopilot.off('message', messageHandler);

event - The event to stop listening for
callback - The callback function to remove

setMuted(muted: boolean)

Controls the microphone mute state.

echopilot.setMuted(true);

muted - Whether to mute the microphone

isMuted(): boolean

Returns the current microphone mute state.

const isMuted = echopilot.isMuted();

Returns: boolean indicating if the microphone is muted

setSpeakerMuted(muted: boolean)

Controls the speaker mute state.

echopilot.setSpeakerMuted(true);

muted - Whether to mute the speaker

isSpeakerMuted(): boolean

Returns the current speaker mute state.

const isSpeakerMuted = echopilot.isSpeakerMuted();

Returns: boolean indicating if the speaker is muted

say(message: string, endCallAfterSpoken?: boolean)

Makes the assistant speak a message.

await echopilot.say('Hello!', false);

message - The message to speak
endCallAfterSpoken - Whether to end the call after speaking
Returns: Promise that resolves when the message is spoken

getAudioDevices(): Promise

Gets a list of available audio input and output devices.

const devices = await echopilot.getAudioDevices();
console.log('Input devices:', devices.inputs);
console.log('Output devices:', devices.outputs);

Returns: Promise Object containing arrays of input and output devices
Throws: Error if device access is denied or not available

setInputDevice(deviceId: string)

Set the active audio input device (microphone).

await echopilot.setInputDevice('device-id');

deviceId - The ID of the input device to use
Throws: Error if the device cannot be set or doesn't exist

setOutputDevice(deviceId: string)

Set the active audio output device (speaker/headphones).

await echopilot.setOutputDevice('device-id');

deviceId - The ID of the output device to use
Throws: Error if the device cannot be set or doesn't exist

configureVAD(config: Partial)

Configure Voice Activity Detection (VAD) settings.

echopilot.configureVAD({
  threshold: 0.15,        // Minimum volume level to consider as speech (0-1)
  silenceDuration: 800,   // Duration of silence to consider speech ended (ms)
  minSpeechDuration: 300, // Minimum duration of speech to consider valid (ms)
  enabled: true          // Whether VAD is enabled
});

config - Partial VAD configuration object
- threshold - Minimum volume level to consider as speech (0-1)
- silenceDuration - Duration of silence to consider speech ended (ms)
- minSpeechDuration - Minimum duration of speech to consider valid (ms)
- enabled - Whether VAD is enabled

getVADConfig(): VADConfig

Get current VAD configuration.

const config = echopilot.getVADConfig();
console.log('Current VAD config:', config);

Returns: Current VAD configuration object

Events

The SDK emits various events that you can listen to:

call-start: Fired when a call starts
call-end: Fired when a call ends
speech-start: Fired when speech begins
speech-end: Fired when speech ends
volume-level: Fired with current volume level (number)
user-speaking: Fired when VAD state changes (isSpeaking: boolean, volume: number)
message: Fired when a message is received
error: Fired when an error occurs
usage-update: Fired when usage tracking updates
error-logged: Fired when an error is logged

Types

AssistantConfig

interface AssistantConfig {
  model: {
    provider: 'openai';
    model: 'gpt-3.5-turbo' | 'gpt-4' | 'gpt-4-turbo-preview';
    messages: Array<{
      role: 'system' | 'user' | 'assistant' | 'function' | 'tool';
      content: string;
    }>;
  };
  voice: {
    provider: '11labs';
    voiceId: string;
  };
}

Message

type Message = TranscriptMessage | FunctionCallMessage | FunctionCallResultMessage;

interface TranscriptMessage {
  type: 'transcript';
  role: 'user' | 'system' | 'assistant';
  transcriptType: 'partial' | 'final';
  transcript: string;
}

interface FunctionCallMessage {
  type: 'function-call';
  functionCall: {
    name: string;
    parameters: unknown;
  };
}

interface FunctionCallResultMessage {
  type: 'function-call-result';
  functionCallResult: {
    forwardToClientEnabled?: boolean;
    result: unknown;
    [key: string]: unknown;
  };
}

AudioDevices

interface AudioDevices {
  inputs: Array<{
    deviceId: string;
    label: string;
    kind: 'audioinput';
  }>;
  outputs: Array<{
    deviceId: string;
    label: string;
    kind: 'audiooutput';
  }>;
}

VADConfig

interface VADConfig {
  /** Minimum volume level to consider as speech (0-1) */
  threshold: number;
  /** Duration of silence to consider speech ended (in milliseconds) */
  silenceDuration: number;
  /** Minimum duration of speech to consider valid (in milliseconds) */
  minSpeechDuration: number;
  /** Whether VAD is enabled */
  enabled: boolean;
}

Error Handling

The SDK provides comprehensive error handling:

All async methods throw errors that you should catch
The error event is emitted for runtime errors
Errors are automatically logged to the EchoPilot service
Error types include:
- InvalidKeyError: Invalid API key
- RateLimitError: Rate limit exceeded
- ServiceError: General service errors

Example error handling:

try {
  await echopilot.start(assistantConfig);
} catch (error) {
  if (error instanceof InvalidKeyError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Service error:', error);
  }
}

echopilot.on('error', (error) => {
  console.error('Runtime error:', error);
});