Classes

SonioxClient

Main entry point for the Soniox client SDK.

Example

const client = new SonioxClient({
  api_key: async () => {
    const res = await fetch('/api/get-temporary-key', { method: 'POST' });
    return (await res.json()).api_key;
  },
});

// 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

High-level recording orchestrator

Manages the lifecycle of audio capture and real-time transcription:

1. Starts audio source immediately (buffers chunks)
2. Resolves the API key (from string or async function)
3. Connects to the Soniox WebSocket API
4. Drains buffered audio, then pipes live audio to the session

Example

const recording = client.realtime.record({ model: 'stt-rt-v4' });
recording.on('result', (r) => console.log(r.tokens));
recording.on('error', (e) => console.error(e));

// Later:
await recording.stop();

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

resume()

resume(): void;

Resume recording after pause.

Resumes the audio source and session. Audio capture and transmission continue from where they left off.

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

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