JavaScript API Reference

`VoiceAgentClient`

The main class for real-time voice conversations. Manages the WebSocket connection, audio pipeline, conversation state, and event dispatching.

Constructor

new VoiceAgentClient(config: {
  apiKey: string;
  prompt: string;
  voice?: VoiceStyle;
  language?: Language;
  visemes?: boolean;
  enableAudio?: boolean;
  serverUrl?: string;
  tools?: ToolDefinition[];
  onTranscription?: (text: string) => void;
  onResponse?: (text: string) => void;
  onVisemes?: (visemes: Viseme[]) => void;
  onStatus?: (status: string) => void;
  onError?: (error: any) => void;
})

Config Options

Option	Type	Required	Default	Description
`apiKey`	`string`	Yes	—	Lokutor API key. Passed as `api_key` query parameter.
`prompt`	`string`	Yes	—	System prompt sent to the LLM. Defines personality and behavior.
`voice`	`VoiceStyle`	No	`F1`	Voice style ID. See `VoiceStyle` enum.
`language`	`Language`	No	`ENGLISH`	Conversation language. Affects STT and TTS. The agent can speak all nine languages but only understands six of them (which).
`visemes`	`boolean`	No	`false`	Request lip-sync metadata. Produces nothing on the current speech model — see Visemes.
`enableAudio`	`boolean`	No	`false`	Automatically manage microphone and speaker in browser.
`serverUrl`	`string`	No	`wss://api.lokutor.com/ws/agent`	Custom WebSocket endpoint. Use for local development or proxies.
`tools`	`ToolDefinition[]`	No	`[]`	OpenAI-format tool definitions for LLM function calling.
`agentId`	`string`	No	—	Agent ID for server-side agent configuration loading.
`onTranscription`	`(text: string) => void`	No	—	Called when user speech is transcribed.
`onResponse`	`(text: string) => void`	No	—	Called when the agent generates a text response.
`onVisemes`	`(visemes: Viseme[]) => void`	No	—	Called when viseme metadata arrives.
`onStatus`	`(status: string) => void`	No	—	Called on state transitions.
`onError`	`(error: LokutorError) => void`	No	—	Called on connection or protocol errors.

Methods

`connect(customAudioManager?: AudioManager): Promise<boolean>`

Opens a WebSocket connection to the voice agent server.

If enableAudio is true (or customAudioManager is provided), initializes the audio pipeline.
Sends configuration messages immediately after onopen, in this order: voice, language, tools (only if any are set), visemes, prompt, rates.
Starts the microphone if audio management is enabled.
Returns true on successful connection.
Rejects if the connection fails (e.g., invalid API key, network error).

const connected = await client.connect();
if (connected) {
  console.log('Connected');
}

`startManaged(config?: { audioManager?: AudioManager }): Promise<this>`

The “Golden Path.” Enables audio management automatically and connects.

Sets enableAudio = true.
Creates a BrowserAudioManager if in a browser.
Throws if called outside a browser without a custom AudioManager.
Returns the client instance for chaining.

await client.startManaged();

Must be called inside a user gesture in browsers (e.g., button click).

`sendAudio(audioData: Uint8Array): void`

Sends raw PCM16 audio data to the server.

Format: Int16 PCM, little-endian, 16 kHz, mono
Chunk size: ~320 bytes (20 ms)
Silently ignored if the WebSocket is not open.

const pcmData = new Uint8Array(320); // 20ms of 16kHz mono PCM
client.sendAudio(pcmData);

`disconnect(): void`

Closes the WebSocket connection and releases all resources.

Sets isUserDisconnect = true to prevent auto-reconnection.
Stops microphone and playback.
Cleans up the audio manager.

client.disconnect();

`toggleMute(): boolean`

Toggles the microphone mute state.

Returns the new mute state (true = muted).
No-op if no audio manager is attached.

const isMuted = client.toggleMute();
console.log('Muted:', isMuted);

`getAmplitude(): number`

Returns the current microphone amplitude.

Range: 0 to 1
Useful for driving VU meters or visualization.
Returns 0 if no audio manager is attached.

const volume = client.getAmplitude();
document.getElementById('vu-meter').style.width = `${volume * 100}%`;

`updatePrompt(newPrompt: string): void`

Updates the system prompt mid-conversation.

client.updatePrompt('You are now a pirate. Speak like one.');

`updateVoice(voice: VoiceStyle): void`

Changes the voice mid-conversation.

client.updateVoice(VoiceStyle.M2);

`updateLanguage(language: Language): void`

Changes the language mid-conversation.

client.updateLanguage(Language.SPANISH);

`updateTools(tools: ToolDefinition[]): void`

Replaces the tool definitions mid-conversation.

client.updateTools([{ type: 'function', function: { name: 'get_weather', ... } }]);

`submitToolResult(callId: string, result: string | object): void`

Submits the result of a tool execution back to the LLM.

client.on('tool_call', ({ call_id, name, arguments: args }) => {
  const result = myTool(name, JSON.parse(args));
  client.submitToolResult(call_id, result);
});

`getTranscript(): Array<{ role: 'user' | 'agent'; text: string; timestamp: number }>`

Returns the full conversation history.

Each entry includes the speaker role, text, and Unix timestamp.
Returns a shallow copy; modifying the array does not affect internal state.

const history = client.getTranscript();
history.forEach(msg => {
  console.log(`${msg.role}: ${msg.text}`);
});

`getTranscriptText(): string`

Returns the conversation as a formatted text string.

const text = client.getTranscriptText();
// You: Hello
// Agent: Hi there!

`on(event: string, callback: Function): this`

Subscribes to an event. Chainable. Supported events: transcription, response, audio, visemes, status, error, tool_call, reconnected, ended ({ code, reason }, the server ended the session), session_limit ({ seconds, reason }, the session’s remaining time when it has a limit).

client
  .on('transcription', (text) => console.log('User:', text))
  .on('response', (text) => console.log('Agent:', text))
  .on('audio', (data) => playAudio(data));

`onAudio(callback: (data: Uint8Array) => void): void`

Convenience method equivalent to on('audio', callback).

`onVisemes(callback: (visemes: Viseme[]) => void): void`

Convenience method equivalent to on('visemes', callback).

Properties

Property	Type	Description
`prompt`	`string`	Current system prompt
`voice`	`VoiceStyle`	Current voice style
`language`	`Language`	Current language
`tools`	`ToolDefinition[]`	Registered tool definitions
`connected`	`boolean`	Whether the WebSocket is currently open
`generation`	`number`	Current utterance generation counter

Static Discovery Methods

All REST discovery endpoints are public (no API key). The SDK automatically converts wss:// to https://.

Method	Returns	Description
`VoiceAgentClient.fetchVoices(baseUrl?)`	`Promise<VoiceInfo[]>`	Available voice styles
`VoiceAgentClient.fetchLanguages(baseUrl?)`	`Promise<LanguageInfo[]>`	Supported languages
`VoiceAgentClient.fetchModels(baseUrl?)`	`Promise<ModelInfo[]>`	Loaded TTS model versions
`VoiceAgentClient.fetchConfig(baseUrl?)`	`Promise<ServerConfig>`	Server limits and defaults
`VoiceAgentClient.fetchStatus(baseUrl?)`	`Promise<ServerStatus>`	Rich runtime status
`VoiceAgentClient.fetchHealth(baseUrl?)`	`Promise<HealthStatus>`	Liveness probe

const voices = await VoiceAgentClient.fetchVoices();
const config = await VoiceAgentClient.fetchConfig();
console.log('Max text length:', config.max_text_length);

// Custom endpoint
const local = await VoiceAgentClient.fetchVoices('ws://localhost:8080/ws/agent');

`TTSClient`

Standalone client for text-to-speech synthesis without the conversational agent.

Constructor

new TTSClient(config: { apiKey: string })

Methods

`synthesize(options: SynthesizeOptions): Promise<void>`

Opens a temporary WebSocket, sends the synthesis request, and streams back audio.

await client.synthesize({
  text: 'Hello world',
  voice: VoiceStyle.F1,
  language: Language.ENGLISH,
  speed: 1.0,
  steps: 24,
  visemes: true,
  onAudio: (data) => playAudio(data),
  onVisemes: (visemes) => animateMouth(visemes),
  onTTFB: (ms) => console.log(`TTFB: ${ms}ms`),
  onError: (err) => console.error(err),
});

SynthesizeOptions

Option	Type	Required	Default	Description
`text`	`string`	Yes	—	Text to synthesize
`voice`	`VoiceStyle`	No	`F1`	Voice style
`language`	`Language`	No	`ENGLISH`	Language
`speed`	`number`	No	`1.0`	Accepted for compatibility, but has no effect — the current model has no rate control. See Voices, Languages & Models.
`steps`	`number`	No	Server/agent default	Diffusion steps (`nfe` server-side). Accepted, but has no effect on the current voice model, which runs a fixed `4`. See Voices, Languages & Models.
`visemes`	`boolean`	No	`false`	Request viseme metadata
`onAudio`	`(data: Uint8Array) => void`	No	—	Audio chunk callback
`onVisemes`	`(visemes: Viseme[]) => void`	No	—	Viseme callback
`onTTFB`	`(ms: number) => void`	No	—	Time-to-first-byte callback
`onError`	`(error: any) => void`	No	—	Error callback

The promise resolves when synthesis completes (server sends EOS or closes).

`STTClient`

Standalone client for one-shot transcription of a complete, pre-recorded audio clip. See Speech-to-Text for the full guide.

Constructor

new STTClient(config: { apiKey: string; serverUrl?: string })

Methods

`transcribe(options: TranscribeOptions): Promise<TranscribeResult>`

const result = await client.transcribe({
  audio: fileBlobOrBuffer,
  language: Language.ENGLISH,
});
console.log(result.text);

Option	Type	Required	Default	Description
`audio`	`Blob \| ArrayBuffer \| Uint8Array`	Yes	—	A complete WAV file, or raw PCM16 with `format: "pcm16"`
`format`	`"wav" \| "pcm16"`	No	`"wav"`	Only needed for raw PCM16 input
`sampleRate`	`number`	No	—	Required when `format` is `"pcm16"`
`language`	`Language`	No	server default	ISO language code

Returns TranscribeResult: { text, latencyMs, engine, sampleRate, language, durationSeconds, segments? }.

`SpeechToTextClient`

Standalone client for continuous/live transcription from a microphone, with server-side VAD detecting utterance boundaries. See Speech-to-Text for the full guide.

Constructor

new SpeechToTextClient(config: SpeechToTextOptions)

Option	Type	Required	Default	Description
`apiKey`	`string`	Yes	—	—
`serverUrl`	`string`	No	`wss://api.lokutor.com/ws/stt`	—
`language`	`Language`	No	`ENGLISH`	—
`vad`	`"silero" \| "rms"`	No	`"silero"`	VAD engine
`onPartialTranscript`	`(text: string) => void`	No	—	Fires repeatedly mid-utterance
`onFinalTranscript`	`(text: string) => void`	No	—	Fires once the utterance ends
`onError`	`(error: LokutorError) => void`	No	—	—
`onStatusChange`	`(status) => void`	No	—	`"connecting" \| "connected" \| "disconnected"`

Methods

`connect(customAudioManager?: AudioManager): Promise<boolean>`

Requests microphone access (or uses customAudioManager, e.g. NodeAudioManager) and starts streaming.

`endUtterance(): void`

Force-finalizes whatever utterance is currently in progress, instead of waiting for VAD silence.

`disconnect(): void`

Stops the microphone and closes the connection.

`BrowserAudioManager`

Manages the Web Audio API pipeline for browser environments.

Constructor

new BrowserAudioManager(config?: BrowserAudioConfig)

BrowserAudioConfig

Option	Type	Default	Description
`inputSampleRate`	`number`	`16000`	Target microphone sample rate
`outputSampleRate`	`number`	`44100`	Speaker output sample rate
`autoGainControl`	`boolean`	`true`	Enable AGC
`echoCancellation`	`boolean`	`true`	Enable echo cancellation
`noiseSuppression`	`boolean`	`true`	Enable noise suppression
`keepAwake`	`boolean`	`true`	Keep the screen awake while the microphone is live (Screen Wake Lock)
`microphone`	`MediaStream \| Promise<MediaStream>`	—	A stream from `requestMicrophone()`, requested inside the tap that started the call; used instead of asking again when the connection opens
`onInputError`	`(error: Error) => void`	—	Microphone error handler

requestMicrophone()

requestMicrophone(constraints?: { autoGainControl?: boolean; echoCancellation?: boolean; noiseSuppression?: boolean }): Promise<MediaStream>

Asks for the microphone immediately. Call it synchronously in the click or tap handler that starts a call, before any await, and pass the promise as microphone. iOS Safari reliably shows its permission prompt only for a request made inside a user gesture, and refuses capture outright while the page’s audio session is in 'playback' mode; this function moves that session back to 'auto' first.

button.onclick = () => {
  const microphone = requestMicrophone();          // inside the tap
  const client = new VoiceAgentClient({ apiKey, prompt });
  client.connect(new BrowserAudioManager({ microphone }))
    .catch((e) => { if (e.code === 'audio.microphone_unavailable') showMicHelp(e); });
};

Methods

Method	Returns	Description
`init()`	`Promise<void>`	Initialize AudioContext
`startMicrophone(onAudioInput)`	`Promise<void>`	Begin capturing microphone
`stopMicrophone()`	`void`	Stop microphone
`playAudio(pcm16Data)`	`void`	Schedule audio for playback
`stopPlayback()`	`void`	Stop all playing audio
`setMuted(muted)`	`void`	Mute/unmute microphone
`isMicMuted()`	`boolean`	Current mute state
`getAmplitude()`	`number`	Current RMS amplitude (0-1)
`getFrequencyData()`	`Uint8Array`	FFT data for visualization
`getWaveformData()`	`Uint8Array`	Time-domain data for waveform
`cleanup()`	`void`	Release resources
`getState()`	`string \| null`	AudioContext state
`isRecording()`	`boolean`	Whether mic is active

`NodeAudioManager`

Node.js audio implementation using speaker and node-record-lpcm16.

import { NodeAudioManager } from '@lokutor/sdk';

const audio = new NodeAudioManager();
await audio.init();
await audio.startMicrophone((data) => client.sendAudio(data));
audio.playAudio(pcmData);

Dependencies must be installed separately:

npm install speaker node-record-lpcm16

Enums

`VoiceStyle`

enum VoiceStyle {
  F1 = "F1",
  F2 = "F2",
  F3 = "F3",
  F4 = "F4",
  F5 = "F5",
  M1 = "M1",
  M2 = "M2",
  M3 = "M3",
  M4 = "M4",
  M5 = "M5",
}

`Language`

enum Language {
  ENGLISH = "en",     SPANISH = "es",   CATALAN = "ca",
  GALICIAN = "gl",    BASQUE = "eu",    PORTUGUESE = "pt",
  FRENCH = "fr",      ITALIAN = "it",   GERMAN = "de",
}

Interfaces

`Viseme`

interface Viseme {
  v: number;      // Character index in source text
  c: string;      // Normalized character/phoneme
  t: number;      // Timestamp in seconds from audio start
}

The SDK receives v, c, t from the server and passes them through as-is.

`ToolDefinition`

interface ToolDefinition {
  type: 'function';
  function: {
    name: string;
    description: string;
    parameters: {
      type: 'object';
      properties: Record<string, any>;
      required?: string[];
    };
  };
}

`ToolCall`

interface ToolCall {
  name: string;
  arguments: string; // JSON string
  call_id: string;   // Unique ID for this invocation
}

`LokutorConfig`

interface LokutorConfig {
  apiKey: string;
  onTranscription?: (text: string) => void;
  onResponse?: (text: string) => void;
  onAudio?: (data: Uint8Array) => void;
  onStatus?: (status: string) => void;
  onError?: (error: any) => void;
}

`SynthesizeOptions`

interface SynthesizeOptions {
  text: string;
  voice?: VoiceStyle;
  language?: Language;
  speed?: number;
  steps?: number;
  visemes?: boolean;
}

`BrowserAudioOptions`

interface BrowserAudioOptions {
  inputSampleRate?: number;    // Target mic rate (default 16000)
  outputSampleRate?: number;   // Speaker rate (default 44100)
  autoGainControl?: boolean;   // Enable AGC (default true)
  echoCancellation?: boolean;  // Enable echo cancellation (default true)
  noiseSuppression?: boolean;  // Enable noise suppression (default true)
  keepAwake?: boolean;         // Keep the screen awake while the mic is live (default true)
  microphone?: MediaStream | Promise<MediaStream>; // From requestMicrophone(), called in the tap
  analyserEnabled?: boolean;   // Enable FFT/waveform analysis
  onInputError?: (error: Error) => void;
}

Constants

`AUDIO_CONFIG`

const AUDIO_CONFIG = {
  SAMPLE_RATE: 16000,          // Microphone input rate
  SAMPLE_RATE_INPUT: 16000,    // Alias for SAMPLE_RATE
  SPEAKER_SAMPLE_RATE: 44100,  // Agent audio output rate
  SAMPLE_RATE_OUTPUT: 44100,   // Alias for SPEAKER_SAMPLE_RATE
  CHANNELS: 1,                 // Mono
  CHUNK_DURATION_MS: 20,       // 20ms chunks
  CHUNK_SIZE: 320,             // Computed: (16000 * 20) / 1000
};

`DEFAULT_URLS`

const DEFAULT_URLS = {
  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
  TTS: "wss://api.lokutor.com/ws/tts",
  STT: "wss://api.lokutor.com/ws/stt",
};

Utility Functions

`pcm16ToFloat32(int16Data: Int16Array): Float32Array`

Converts Int16 PCM to Float32 (-1.0 to 1.0).

`float32ToPcm16(float32Data: Float32Array): Int16Array`

Converts Float32 to Int16 PCM. Clamps to [-1, 1] before conversion.

`resample(input: Float32Array, inputRate: number, outputRate: number): Float32Array`

Linear interpolation resampling.

`resampleWithAntiAliasing(input: Float32Array, inputRate: number, outputRate: number): Float32Array`

Resamples with a low-pass filter to prevent aliasing when downsampling.

`normalizeAudio(data: Float32Array, targetPeak?: number): Float32Array`

Normalizes audio to a target peak amplitude.

`calculateRMS(data: Float32Array | Uint8Array): number`

Calculates Root Mean Square amplitude.

`StreamResampler`

Stateful resampler for streaming audio chunks.

const resampler = new StreamResampler(48000, 16000);
const output = resampler.process(chunk);
const final = resampler.process(new Float32Array(0), true); // flush

Quick Helpers

`simpleConversation(config)`

One-liner to create and connect a VoiceAgentClient.

const client = await simpleConversation({
  apiKey: 'your-key',
  prompt: 'You are helpful.',
});

`simpleTTS(options)`

One-liner for TTS synthesis.

await simpleTTS({
  apiKey: 'your-key',
  text: 'Hello world',
  onAudio: (data) => playAudio(data),
});

Error Handling

`LokutorError`

All SDK errors are instances of LokutorError:

class LokutorError extends Error {
  code: ErrorCode;
  message: string;
  detail?: string;
  retryable: boolean;
  original?: unknown;
}

Property	Type	Description
`code`	`ErrorCode`	Machine-readable error identifier (e.g. `auth.invalid_key`)
`message`	`string`	Human-readable description
`detail`	`string`	Additional context (may contain internal data)
`retryable`	`boolean`	Whether the client should retry
`original`	`unknown`	Original underlying error, if any

`isRetryable(error: unknown): boolean`

Returns true if the error is a retryable LokutorError:

import { isRetryable } from '@lokutor/sdk';

client.onError = (error) => {
  if (isRetryable(error)) {
    console.warn('Will retry:', error.code);
  } else {
    console.error('Fatal:', error.message);
  }
};

Error Codes

See the Error Catalog for a complete list of codes, HTTP status mappings, and retry strategies.

Debug Tracing

Enable debug tracing by setting window.LOKUTOR_TRACE = true or localStorage.setItem('lokutorTrace', '1').

​VoiceAgentClient

​Constructor

​Config Options

​Methods

​connect(customAudioManager?: AudioManager): Promise<boolean>

​startManaged(config?: { audioManager?: AudioManager }): Promise<this>

​sendAudio(audioData: Uint8Array): void

​disconnect(): void

​toggleMute(): boolean

​getAmplitude(): number

​updatePrompt(newPrompt: string): void

​updateVoice(voice: VoiceStyle): void

​updateLanguage(language: Language): void

​updateTools(tools: ToolDefinition[]): void

​submitToolResult(callId: string, result: string | object): void

​getTranscript(): Array<{ role: 'user' | 'agent'; text: string; timestamp: number }>

​getTranscriptText(): string

​on(event: string, callback: Function): this

​onAudio(callback: (data: Uint8Array) => void): void

​onVisemes(callback: (visemes: Viseme[]) => void): void

​Properties

​Static Discovery Methods

​TTSClient

​Constructor

​Methods

​synthesize(options: SynthesizeOptions): Promise<void>

​SynthesizeOptions

​STTClient

​Constructor

​Methods

​transcribe(options: TranscribeOptions): Promise<TranscribeResult>

​SpeechToTextClient

​Constructor

​Methods

​connect(customAudioManager?: AudioManager): Promise<boolean>

​endUtterance(): void

​disconnect(): void

​BrowserAudioManager

​Constructor

​BrowserAudioConfig

​requestMicrophone()

​Methods

​NodeAudioManager

​Enums

​VoiceStyle

​Language

​Interfaces

​Viseme

​ToolDefinition

​ToolCall

​LokutorConfig

​SynthesizeOptions

​BrowserAudioOptions

​Constants

​AUDIO_CONFIG

​DEFAULT_URLS

​Utility Functions

​pcm16ToFloat32(int16Data: Int16Array): Float32Array

​float32ToPcm16(float32Data: Float32Array): Int16Array

​resample(input: Float32Array, inputRate: number, outputRate: number): Float32Array

​resampleWithAntiAliasing(input: Float32Array, inputRate: number, outputRate: number): Float32Array

​normalizeAudio(data: Float32Array, targetPeak?: number): Float32Array

​calculateRMS(data: Float32Array | Uint8Array): number

​StreamResampler

​Quick Helpers

​simpleConversation(config)

​simpleTTS(options)

​Error Handling

​LokutorError

​isRetryable(error: unknown): boolean

​Error Codes

​Debug Tracing

​Related Pages

`VoiceAgentClient`

Constructor

Config Options

Methods

`connect(customAudioManager?: AudioManager): Promise<boolean>`

`startManaged(config?: { audioManager?: AudioManager }): Promise<this>`

`sendAudio(audioData: Uint8Array): void`

`disconnect(): void`

`toggleMute(): boolean`

`getAmplitude(): number`

`updatePrompt(newPrompt: string): void`

`updateVoice(voice: VoiceStyle): void`

`updateLanguage(language: Language): void`

`updateTools(tools: ToolDefinition[]): void`

`submitToolResult(callId: string, result: string | object): void`

`getTranscript(): Array<{ role: 'user' | 'agent'; text: string; timestamp: number }>`

`getTranscriptText(): string`

`on(event: string, callback: Function): this`

`onAudio(callback: (data: Uint8Array) => void): void`

`onVisemes(callback: (visemes: Viseme[]) => void): void`

Properties

Static Discovery Methods

`TTSClient`

Constructor

Methods

`synthesize(options: SynthesizeOptions): Promise<void>`

SynthesizeOptions

`STTClient`

Constructor

Methods

`transcribe(options: TranscribeOptions): Promise<TranscribeResult>`

`SpeechToTextClient`

Constructor

Methods

`connect(customAudioManager?: AudioManager): Promise<boolean>`

`endUtterance(): void`

`disconnect(): void`

`BrowserAudioManager`

Constructor

BrowserAudioConfig

requestMicrophone()

Methods

`NodeAudioManager`

Enums

`VoiceStyle`

`Language`

Interfaces

`Viseme`

`ToolDefinition`

`ToolCall`

`LokutorConfig`

`SynthesizeOptions`

`BrowserAudioOptions`

Constants

`AUDIO_CONFIG`

`DEFAULT_URLS`

Utility Functions

`pcm16ToFloat32(int16Data: Int16Array): Float32Array`

`float32ToPcm16(float32Data: Float32Array): Int16Array`

`resample(input: Float32Array, inputRate: number, outputRate: number): Float32Array`

`resampleWithAntiAliasing(input: Float32Array, inputRate: number, outputRate: number): Float32Array`

`normalizeAudio(data: Float32Array, targetPeak?: number): Float32Array`

`calculateRMS(data: Float32Array | Uint8Array): number`

`StreamResampler`

Quick Helpers

`simpleConversation(config)`

`simpleTTS(options)`

Error Handling

`LokutorError`

`isRetryable(error: unknown): boolean`

Error Codes

Debug Tracing

Related Pages