Classes

SonioxClient

Main entry point for the Soniox client SDK.

Example

// Recommended: async config with region
const client = new SonioxClient({
  config: async () => {
    const res = await fetch('/api/soniox-config', { method: 'POST' });
    return await res.json(); // { api_key, region }
  },
});

// High-level: record from microphone
const recording = client.realtime.record({ model: 'stt-rt-v4' });
recording.on('result', (r) => console.log(r.tokens));
await recording.stop();

// Low-level: direct session access
const session = client.realtime.stt({ model: 'stt-rt-v4' }, { api_key: key });
await session.connect();

permissions

get permissions(): PermissionResolver | undefined;

Permission resolver, if configured. Returns undefined if no resolver was provided (SSR-safe).

Example

const mic = await client.permissions?.check('microphone');
if (mic?.status === 'denied') {
  showSettingsMessage();
}

Returns

PermissionResolver | undefined

Constructor

new SonioxClient(options): SonioxClient;

Parameters

Returns

SonioxClient

Properties

Recording

state

get state(): RecordingState;

Current recording state

Returns

RecordingState

cancel()

cancel(): void;

Immediately cancel recording without waiting for final results

Returns

void

finalize()

finalize(options?): void;

Request the server to finalize current non-final tokens.

Parameters

Returns

void

off()

off<E>(event, handler): this;

Remove an event handler

Type Parameters

Parameters

Returns

this

on()

on<E>(event, handler): this;

Register an event handler

Type Parameters

Parameters

Returns

this

once()

once<E>(event, handler): this;

Register a one-time event handler

Type Parameters

Parameters

Returns

this

pause()

pause(): void;

Pause recording.

Pauses the audio source (stops microphone capture) and pauses the session (activates automatic keepalive to prevent server disconnect).

Returns

void

reconnect()

reconnect(): void;

Force a reconnection — tears down the current session and audio encoder, then establishes a new session via the standard reconnect flow (backoff, config re-resolution, buffer drain).

Use this to recover from stale connections after platform lifecycle events such as laptop sleep/wake (web visibilitychange) or app backgrounding (React Native AppState).

Requires auto_reconnect to be enabled. No-op when the recording is not in recording or paused state.

Returns

void

resume()

resume(): void;

Resume recording after pause.

Resumes the audio source and session. Audio capture and transmission continue from where they left off. If audio was buffered during a reconnect while paused, the buffer is drained now.

Returns

void

stop()

stop(): Promise<void>;

Gracefully stop recording

Stops the audio source and waits for the server to process all buffered audio and return final results.

Returns

Promise<void>

Promise that resolves when the server acknowledges completion

MicrophoneSource

Browser microphone audio source

Uses navigator.mediaDevices.getUserMedia to capture audio from the microphone and MediaRecorder to encode it into chunks.

Example

const source = new MicrophoneSource();
await source.start({
  onData: (chunk) => session.sendAudio(chunk),
  onError: (err) => console.error(err),
});
// Later:
source.stop();

Constructor

new MicrophoneSource(options): MicrophoneSource;

Parameters

Returns

MicrophoneSource

pause()

pause(): void;

Pause audio capture

Returns

void

restart()

restart(): void;

Reinitialize the MediaRecorder on the existing stream so the next chunks contain a fresh container header (required after reconnecting to a new server session).

Returns

void

resume()

resume(): void;

Resume audio capture

Returns

void

start()

start(handlers): Promise<void>;

Request microphone access and start recording

Parameters

Returns

Promise<void>

Throws

AudioUnavailableError if getUserMedia or MediaRecorder is not supported

Throws

AudioPermissionError if microphone access is denied

Throws

AudioDeviceError if no microphone is found

stop()

stop(): void;

Stop recording and release all resources

Returns

void

BrowserPermissionResolver

Browser permission resolver for checking and requesting microphone access.

Example

const resolver = new BrowserPermissionResolver();
const mic = await resolver.check('microphone');
if (mic.status === 'prompt') {
  const result = await resolver.request('microphone');
  if (result.status === 'denied') {
    showDeniedMessage();
  }
}

Constructor

new BrowserPermissionResolver(): BrowserPermissionResolver;

Returns

BrowserPermissionResolver

check()

check(permission): Promise<PermissionResult>;

Check current microphone permission status without prompting the user.

Parameters

Returns

Promise<PermissionResult>

request()

request(permission): Promise<PermissionResult>;

Request microphone permission from the user. This may show a browser permission prompt.

Parameters

Returns

Promise<PermissionResult>

AudioPermissionError

Thrown when microphone access is denied by the user or blocked by the browser.

Maps to getUserMedia NotAllowedError DOMException.

Extends

• SonioxError

toJSON()

toJSON(): Record<string, unknown>;

Converts to a plain object for logging/serialization

Returns

Record<string, unknown>

Inherited from

SonioxError.toJSON

toString()

toString(): string;

Creates a human-readable string representation

Returns

string

Inherited from

SonioxError.toString

Properties

AudioDeviceError

Thrown when no audio input device is found

Maps to getUserMedia NotFoundError DOMException.

Extends

• SonioxError

toJSON()

toJSON(): Record<string, unknown>;

Converts to a plain object for logging/serialization

Returns

Record<string, unknown>

Inherited from

SonioxError.toJSON

toString()

toString(): string;

Creates a human-readable string representation

Returns

string

Inherited from

SonioxError.toString

Properties

AudioUnavailableError

Thrown when audio capture is not supported in the current environment

For example, when getUserMedia or MediaRecorder is not available.

Extends

• SonioxError

toJSON()

toJSON(): Record<string, unknown>;

Converts to a plain object for logging/serialization

Returns

Record<string, unknown>

Inherited from

SonioxError.toJSON

toString()

toString(): string;

Creates a human-readable string representation

Returns

string

Inherited from

SonioxError.toString

Properties

RealtimeTtsConnection

WebSocket connection for real-time Text-to-Speech.

Supports up to 5 concurrent streams multiplexed by stream_id. The connection automatically sends keepalive messages while open.

Example

const conn = new RealtimeTtsConnection(apiKey, wsUrl, ttsDefaults);
await conn.connect();

const s1 = conn.stream({ model, voice, language, audio_format });
s1.sendText("Hello");
s1.finish();
for await (const chunk of s1) { ... }

conn.close();

Extends

• TypedEmitter<TtsConnectionEvents>

isConnected

get isConnected(): boolean;

Whether the WebSocket is connected.

Returns

boolean

Constructor

new RealtimeTtsConnection(
   apiKey, 
   wsUrl, 
   ttsDefaults?, 
   options?): RealtimeTtsConnection;

Parameters

Returns

RealtimeTtsConnection

Overrides

TypedEmitter<TtsConnectionEvents>.constructor

close()

close(): void;

Close the WebSocket connection and terminate all active streams.

Returns

void

connect()

connect(): Promise<void>;

Open the WebSocket connection and start keepalive. Called automatically by stream if not yet connected.

Returns

Promise<void>

emit()

emit<E>(event, ...args): void;

Emit an event to all registered handlers. Handler errors do not prevent other handlers from running. Errors are reported to an error event if present, otherwise rethrown async.

Type Parameters

Parameters

Returns

void

Inherited from

TypedEmitter.emit

off()

off<E>(event, handler): this;

Remove an event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.off

on()

on<E>(event, handler): this;

Register an event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.on

once()

once<E>(event, handler): this;

Register a one-time event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.once

removeAllListeners()

removeAllListeners(event?): void;

Remove all event handlers.

Parameters

Returns

void

Inherited from

TypedEmitter.removeAllListeners

stream()

stream(input?): Promise<RealtimeTtsStream>;

Open a new TTS stream on this connection. Auto-connects if the WebSocket is not yet open.

Parameters

Returns

Promise<RealtimeTtsStream>

A ready-to-use stream handle

RealtimeTtsStream

Handle for one TTS stream on a WebSocket connection.

Emits typed events and supports async iteration over decoded audio chunks.

Examples

stream.on('audio', (chunk) => process(chunk));
stream.on('terminated', () => console.log('done'));
stream.sendText("Hello world");
stream.finish();

stream.sendText("Hello world");
stream.finish();
for await (const chunk of stream) {
  process(chunk);
}

Extends

• TypedEmitter<TtsStreamEvents>

state

get state(): TtsStreamState;

Current stream lifecycle state.

Returns

TtsStreamState

[asyncIterator]()

asyncIterator: AsyncIterator<Uint8Array<ArrayBufferLike>>;

Async iterator that yields decoded audio chunks.

Returns

AsyncIterator<Uint8Array<ArrayBufferLike>>

cancel()

cancel(): void;

Cancel this stream. The server will stop generating and send terminated.

Returns

void

close()

close(): void;

Close this stream. For single-stream usage (created via tts(input)), also closes the underlying WebSocket connection.

Returns

void

emit()

emit<E>(event, ...args): void;

Emit an event to all registered handlers. Handler errors do not prevent other handlers from running. Errors are reported to an error event if present, otherwise rethrown async.

Type Parameters

Parameters

Returns

void

Inherited from

TypedEmitter.emit

finish()

finish(): void;

Signal that no more text will be sent for this stream. The server will finish generating audio and send terminated.

Returns

void

off()

off<E>(event, handler): this;

Remove an event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.off

on()

on<E>(event, handler): this;

Register an event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.on

once()

once<E>(event, handler): this;

Register a one-time event handler.

Type Parameters

Parameters

Returns

this

Inherited from

TypedEmitter.once

removeAllListeners()

removeAllListeners(event?): void;

Remove all event handlers.

Parameters

Returns

void

Inherited from

TypedEmitter.removeAllListeners

sendStream()

sendStream(source): Promise<void>;

Pipe an async iterable of text chunks into the stream. Automatically calls finish when the iterable completes.

Designed for concurrent use: call sendStream() and consume audio via for await or events simultaneously.

Parameters

Returns

Promise<void>

Example

stream.sendStream(llmTokenStream);
for await (const audio of stream) { forward(audio); }

sendText()

sendText(text, options?): void;

Send one text chunk to the TTS stream.

Parameters

Returns

void

Properties

SonioxError

Extends

• Error

Extended by

• AudioPermissionError
• AudioDeviceError
• AudioUnavailableError
• SonioxHttpError

Constructor

new SonioxError(
   message, 
   code?, 
   statusCode?, 
   cause?): SonioxError;

Parameters

Returns

SonioxError

Overrides

Error.constructor

toJSON()

toJSON(): Record<string, unknown>;

Converts to a plain object for logging/serialization

Returns

Record<string, unknown>

toString()

toString(): string;

Creates a human-readable string representation

Returns

string

Properties

SonioxHttpError

HTTP error class for all HTTP-related failures (REST API).

Thrown when HTTP requests fail due to network issues, timeouts, server errors, or response parsing failures.

Extends

• SonioxError

Constructor

new SonioxHttpError(details): SonioxHttpError;

Parameters

Returns

SonioxHttpError

Overrides

SonioxError.constructor

toJSON()

toJSON(): Record<string, unknown>;

Converts to a plain object for logging/serialization

Returns

Record<string, unknown>

Overrides

SonioxError.toJSON

toString()

toString(): string;

Creates a human-readable string representation

Returns

string

Overrides

SonioxError.toString

Properties

TtsRestClient

Browser-safe REST client for TTS generation.

Provides generate() (buffered) and generateStream() (streaming) using only globalThis.fetch. HTTP failures are surfaced as SonioxHttpError, matching the rest of the Soniox SDK.

Authentication uses the Authorization: Bearer <api_key> header.

Example

const client = new TtsRestClient(apiKey, 'https://tts-rt.soniox.com');
const audio = await client.generate({ text: 'Hello', voice: 'Adrian' });

Constructor

new TtsRestClient(apiKey, ttsApiUrl): TtsRestClient;

Parameters

Returns

TtsRestClient

generate()

generate(options): Promise<Uint8Array<ArrayBufferLike>>;

Generate speech audio from text. Returns the full audio as a Uint8Array.

Parameters

Returns

Promise<Uint8Array<ArrayBufferLike>>

Throws

SonioxHttpError on non-2xx responses, network failures, or aborted requests.

generateStream()

generateStream(options): AsyncIterable<Uint8Array<ArrayBufferLike>>;

Generate speech audio from text as a streaming async iterable.

Yields Uint8Array chunks as they arrive from the server response body. Lower time-to-first-audio than generate.

Known limitation: Mid-stream server errors (reported via HTTP trailers) cannot be detected through the fetch API. The iterator may end early without an explicit error. Use WebSocket TTS for reliable error detection.

Parameters

Returns

AsyncIterable<Uint8Array<ArrayBufferLike>>

Throws

SonioxHttpError on non-2xx responses, network failures, or aborted requests (before the stream starts).