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:

1. All async methods throw errors that you should catch
2. The error event is emitted for runtime errors
3. Errors are automatically logged to the EchoPilot service
4. 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);
});

Browser Support

The SDK works in all modern browsers that support:

• WebRTC
• MediaDevices API
• Web Audio API

License

MIT