GladiaSTT

Defined in: src/providers/stt/gladia/GladiaSTT.ts:319

Gladia real-time STT provider using the v2 live API.

Remarks

GladiaSTT extends LiveSTTProvider and implements Gladia’s two-step live flow:

1. Session init (HTTP): POST /v2/live with the session configuration. Authentication happens here via the x-gladia-key header (direct mode) or a proxy that injects it (proxy mode). Gladia responds with a WebSocket url containing a single-use session token.
2. Streaming (WebSocket): the provider connects to the returned URL — straight to Gladia in both modes, since the token is embedded in the URL — and streams raw audio as binary frames.

Gladia segments speech into utterances using server-side endpointing and sends transcript messages flagged is_final: false (partial) or is_final: true (final). Each final transcript closes an utterance, so the provider emits it with isFinal: true and utteranceComplete: true, triggering the next pipeline stage.

Key features:

• Interim (partial) and final transcription results
• Server-side endpointing for automatic turn-taking (configurable via GladiaSTTConfig.endpointing)
• Language detection, pinning, and per-utterance code switching
• Word-level timestamps and confidence on final results
• Automatic WebSocket reconnection with exponential backoff (via WebSocketManager) — the session URL stays valid, so reconnects resume the same session
• Proxy mode via GladiaSTTConfig.proxyUrl (recommended for production so the API key stays server-side)

Transport: HTTP session init + WebSocket streaming (via HttpClient and WebSocketManager)

Browser support: All modern browsers (Chrome, Firefox, Safari, Edge). No peer dependencies required — the provider uses native fetch and a raw WebSocket connection managed by the SDK’s built-in utilities.

Data flow:

POST /v2/live (x-gladia-key) -> { id, url }
                                    |
Microphone -> sendAudio(chunk) -> binary frames -> wss://api.gladia.io/v2/live?token=...
                                                                 |
CompositeVoice <- onTranscription(result) <- transcript messages +

Example

import { GladiaSTT } from 'composite-voice';

const stt = new GladiaSTT({
  proxyUrl: 'http://localhost:3001/api/proxy/gladia',
  languages: ['en'],
  endpointing: 0.3,
});

await stt.initialize();

stt.onTranscription((result) => {
  if (result.isFinal) {
    console.log('Final:', result.text);
  } else {
    console.log('Interim:', result.text);
  }
});

await stt.connect();
// ... send audio chunks via stt.sendAudio(chunk) ...
await stt.disconnect();

See

• LiveSTTProvider for the base WebSocket STT class
• GladiaSTTConfig for configuration options
• SonioxSTT for an alternative real-time STT provider

Extends

• LiveSTTProvider

Constructors

Constructor

new GladiaSTT(config, logger?): GladiaSTT;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:352

Create a new GladiaSTT provider.

Parameters

Returns

GladiaSTT

Example

const stt = new GladiaSTT({
  apiKey: 'YOUR_GLADIA_API_KEY',
  sampleRate: 16000,
});

Overrides

LiveSTTProvider.constructor

Properties

Accessors

isProxyMode

Get Signature

get protected isProxyMode(): boolean;

Defined in: src/providers/base/BaseProvider.ts:286

Whether the provider is in proxy mode.

Returns

boolean

true when proxyUrl is set.

Inherited from

LiveSTTProvider.isProxyMode

Methods

assertAuth()

protected assertAuth(): void;

Defined in: src/providers/base/BaseProvider.ts:272

Validate that auth is configured (either apiKey or proxyUrl).

Returns

void

Remarks

Call this in onInitialize() for any provider that requires external authentication. Native providers (NativeSTT, NativeTTS) and in-browser providers (WebLLM) should NOT call this method.

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Inherited from

LiveSTTProvider.assertAuth

assertReady()

protected assertReady(): void;

Defined in: src/providers/base/BaseProvider.ts:255

Guard that throws if the provider has not been initialized.

Returns

void

Remarks

Call at the start of any method that requires the provider to be ready.

Throws

Error Thrown with a descriptive message when initialized is false.

Inherited from

LiveSTTProvider.assertReady

connect()

connect(): Promise<void>;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:526

Initiate a Gladia live session and open the streaming WebSocket.

Returns

Promise<void>

Remarks

Performs the session-init POST (authenticated directly or through the proxy), then connects a WebSocketManager to the Gladia-returned URL with reconnection disabled. The session token is embedded in that URL, so the WebSocket needs no further authentication. The SDK drives reconnection through connect (and FallbackSTT owns failover).

Throws

ProviderConnectionError Thrown when the provider is not initialized, the session-init request fails, or the WebSocket connection fails.

Overrides

LiveSTTProvider.connect

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:771

Gracefully close the Gladia WebSocket connection.

Returns

Promise<void>

Remarks

Sends a stop_recording message so Gladia finalizes any pending audio, waits for the post_final_transcript message (up to 1 s), then disconnects the underlying WebSocketManager.

Throws

Re-throws any unexpected error during disconnection.

Overrides

LiveSTTProvider.disconnect

dispose()

dispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:154

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Delegates to the subclass hook onDispose and resets the initialized flag. If the provider is not initialized, the call is a no-op.

Throws

Re-throws any error raised by onDispose.

Inherited from

LiveSTTProvider.dispose

emitConnectionLost()

protected emitConnectionLost(message): void;

Defined in: src/providers/base/LiveSTTProvider.ts:175

Emit the standardized “connection lost” error result.

Parameters

Returns

void

Remarks

Every live STT provider MUST call this when its streaming connection dies unexpectedly mid-session (server-initiated close, reconnection give-up, fatal transport error) and will not recover on its own. This error-shaped result is the liveness signal the pipeline’s error handling (transcription.error) and FallbackSTT’s mid-session failover depend on — a provider that only logs and flips an internal flag leaves the session silently dead.

Do NOT call this for closes the application requested via disconnect().

Inherited from

LiveSTTProvider.emitConnectionLost

emitTranscription()

protected emitTranscription(result): void;

Defined in: src/providers/base/BaseSTTProvider.ts:206

Emit a transcription result to the registered callback.

Parameters

Returns

void

Remarks

Subclasses call this method whenever transcribed text is available. If no callback has been registered via onTranscription, the result is logged as a warning and dropped.

Inherited from

LiveSTTProvider.emitTranscription

getConfig()

getConfig(): STTProviderConfig;

Defined in: src/providers/base/BaseSTTProvider.ts:225

Get a shallow copy of the current STT configuration.

Returns

STTProviderConfig

A new STTProviderConfig object.

Inherited from

LiveSTTProvider.getConfig

getSessionId()

getSessionId(): string | null;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:848

Get the identifier of the current Gladia live session.

Returns

string | null

The session id, or null when not connected.

Remarks

Useful for fetching the full session result afterwards via GET /v2/live/{id}.

initialize()

initialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:127

Initialize the provider, making it ready for use.

Returns

Promise<void>

Remarks

Calls the subclass hook onInitialize. If the provider has already been initialized the call is a no-op.

Throws

ProviderInitializationError Thrown when onInitialize rejects. The original error is wrapped with the provider class name for diagnostics.

Inherited from

LiveSTTProvider.initialize

isFinal()

isFinal(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:174

Is this a final segment (but not necessarily utterance-complete)?

Parameters

Returns

boolean

true when this is a final segment.

Remarks

A final segment represents committed text, but multi-segment providers (e.g., Deepgram) may emit several final segments for a single utterance. Only the last one will have isUtteranceComplete return true.

Inherited from

LiveSTTProvider.isFinal

isInterim()

isInterim(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:159

Is this an interim (partial, non-final) result?

Parameters

Returns

boolean

true when this is an interim result.

Remarks

Interim results update as the user speaks and are replaced by subsequent results. Useful for display but not for triggering downstream processing.

Inherited from

LiveSTTProvider.isInterim

isPreflight()

isPreflight(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:144

Is this a preflight/eager end-of-turn signal?

Parameters

Returns

boolean

true when this is a preflight signal.

Remarks

Used by the eager LLM pipeline for speculative generation. Only providers with preflight support (e.g., Deepgram Flux) need to override this.

Inherited from

LiveSTTProvider.isPreflight

isReady()

isReady(): boolean;

Defined in: src/providers/base/BaseProvider.ts:178

Check whether the provider has been initialized and is ready.

Returns

boolean

true when initialize has completed successfully and dispose has not yet been called.

Inherited from

LiveSTTProvider.isReady

isUtteranceComplete()

isUtteranceComplete(result): boolean;

Defined in: src/providers/base/BaseSTTProvider.ts:129

Is this result a complete utterance ready for LLM processing?

Parameters

Returns

boolean

true when the utterance is complete.

Remarks

The orchestrator calls this to decide when to send transcribed text to the LLM. Concrete providers override this when they have domain- specific endpointing logic (e.g., DeepgramSTT checks speech_final).

Inherited from

LiveSTTProvider.isUtteranceComplete

isWebSocketConnected()

isWebSocketConnected(): boolean;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:835

Check whether the Gladia WebSocket connection is currently open.

Returns

boolean

true when connected and ready to receive audio.

onConfigUpdate()

protected onConfigUpdate(_config): void;

Defined in: src/providers/base/BaseProvider.ts:242

Hook called after updateConfig merges new values.

Parameters

Returns

void

Remarks

The default implementation is a no-op. Override in subclasses to react to runtime configuration changes (e.g. reconnect with a new API key).

Inherited from

LiveSTTProvider.onConfigUpdate

onDispose()

protected onDispose(): Promise<void>;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:402

Disconnect the WebSocket (if connected) and release the clients.

Returns

Promise<void>

Overrides

LiveSTTProvider.onDispose

onInitialize()

protected onInitialize(): Promise<void>;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:371

Validate auth and create the HTTP client for session initiation.

Returns

Promise<void>

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Overrides

LiveSTTProvider.onInitialize

onTranscription()

onTranscription(callback): void;

Defined in: src/providers/base/BaseSTTProvider.ts:191

Register a callback to receive transcription results.

Parameters

Returns

void

Remarks

All STT providers — regardless of transport — deliver text through this callback. CompositeVoice registers it during pipeline setup so that transcription results flow into the conversation manager and, ultimately, the LLM provider.

Inherited from

LiveSTTProvider.onTranscription

processAudio()

processAudio(chunk): void;

Defined in: src/providers/base/LiveSTTProvider.ts:140

Process a raw audio chunk by sending it over the WebSocket.

Parameters

Returns

void

Remarks

Legacy alias for sendAudio. Delegates to sendAudioToSocket.

Inherited from

LiveSTTProvider.processAudio

resolveApiKey()

protected resolveApiKey(): Promise<string>;

Defined in: src/providers/base/BaseProvider.ts:321

Resolve the API key, calling the factory if apiKey is a function.

Returns

Promise<string>

The resolved API key string, or 'proxy' in proxy mode.

Inherited from

LiveSTTProvider.resolveApiKey

resolveAuthHeader()

protected resolveAuthHeader(defaultAuthType?): Promise<string | undefined>;

Defined in: src/providers/base/BaseProvider.ts:366

Resolve Authorization header value for the configured auth type.

Parameters

Returns

Promise<string | undefined>

The Authorization header value, or undefined in proxy mode.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the header value for REST or server-side WebSocket connections:

• 'token' → 'Token <apiKey>'
• 'bearer' → 'Bearer <apiKey>'

Returns undefined in proxy mode.

Inherited from

LiveSTTProvider.resolveAuthHeader

resolveBaseUrl()

protected resolveBaseUrl(defaultUrl?): string | undefined;

Defined in: src/providers/base/BaseProvider.ts:307

Resolve the base URL for this provider.

Parameters

Returns

string | undefined

The resolved URL, or undefined when all sources are unset.

Remarks

Priority: proxyUrl > endpoint > defaultUrl.

For WebSocket providers (this.type === 'websocket'), the proxy URL’s http(s) scheme is automatically converted to ws(s).

When no URL is configured and defaultUrl is undefined, the return value is undefined — this lets SDK-based providers (Anthropic, OpenAI) fall back to their own built-in defaults.

Inherited from

LiveSTTProvider.resolveBaseUrl

resolveWsProtocols()

protected resolveWsProtocols(defaultAuthType?): Promise<string[] | undefined>;

Defined in: src/providers/base/BaseProvider.ts:342

Resolve WebSocket subprotocol for authentication.

Parameters

Returns

Promise<string[] | undefined>

Subprotocol array for new WebSocket(url, protocols), or undefined.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the subprotocol array for direct mode based on authType:

• 'token' → ['token', apiKey] (Deepgram default)
• 'bearer' → ['bearer', apiKey] (OAuth/Bearer tokens)

Returns undefined in proxy mode (no client-side auth needed).

Inherited from

LiveSTTProvider.resolveWsProtocols

sendAudio()

sendAudio(chunk): void;

Defined in: src/providers/base/LiveSTTProvider.ts:128

Send an audio chunk for real-time transcription.

Parameters

Returns

void

Remarks

This is the public method required by the ILiveSTTProvider interface. It delegates to sendAudioToSocket, which subclasses implement to forward audio data over the WebSocket connection. For providers that manage their own audio (e.g. NativeSTT), sendAudioToSocket is a no-op.

Inherited from

LiveSTTProvider.sendAudio

sendAudioToSocket()

protected sendAudioToSocket(chunk): void;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:726

Send a raw audio chunk to Gladia for real-time transcription.

Parameters

Returns

void

Remarks

The ArrayBuffer is forwarded as a binary WebSocket frame — the bytes must match the session’s encoding, sample_rate, bit_depth, and channels. If the connection is not open, the chunk is silently dropped and a warning is logged.

Overrides

LiveSTTProvider.sendAudioToSocket

stopRecording()

stopRecording(): void;

Defined in: src/providers/stt/gladia/GladiaSTT.ts:748

Signal Gladia that no more audio will be sent.

Returns

void

Remarks

Sends a { "type": "stop_recording" } control message. Gladia transcribes any buffered audio, runs post-processing, and closes the connection with code 1000. Called automatically by disconnect.

updateConfig()

updateConfig(config): void;

Defined in: src/providers/base/BaseProvider.ts:201

Merge partial configuration updates into the current config.

Parameters

Returns

void

Remarks

After merging, the subclass hook onConfigUpdate is called so providers can react to changed values at runtime.

Inherited from

LiveSTTProvider.updateConfig