GladiaSTT

Use GladiaSTT when you need real-time transcription with configurable server-side endpointing for turn-taking, language pinning or per-utterance code switching, and word-level timestamps from Gladia’s Solaria model family.

Prerequisites

• A Gladia API key

No peer dependencies are required. GladiaSTT initiates the session with native fetch and streams audio through a raw WebSocket managed by the SDK’s built-in WebSocketManager.

Gladia’s live flow has two steps: a POST /v2/live session-init request (this is where the API key goes, via the x-gladia-key header) that returns a WebSocket URL with an embedded single-use token, then a direct WebSocket connection to that URL. Because only the init request needs credentials, the proxy forwards just that one POST — audio always streams straight to Gladia.

For production, set up a proxy server so your API key stays server-side.

Basic setup

import { CompositeVoice, MicrophoneInput, GladiaSTT, AnthropicLLM, NativeTTS } from 'composite-voice';

const agent = new CompositeVoice({
  providers: [
    new MicrophoneInput(),
    new GladiaSTT({
      proxyUrl: '/api/proxy/gladia',
      languages: ['en'],
    }),
    new AnthropicLLM({
      proxyUrl: '/api/proxy/anthropic',
      model: 'claude-haiku-4-5',
      systemPrompt: 'You are a helpful voice assistant. Keep responses brief.',
    }),
    new NativeTTS(),
  ],
});

await agent.initialize();
await agent.startListening();

Configuration options

See the API reference for the full list.

Complete example

import { CompositeVoice, MicrophoneInput, GladiaSTT, AnthropicLLM, NativeTTS } from 'composite-voice';

const agent = new CompositeVoice({
  providers: [
    new MicrophoneInput(),
    new GladiaSTT({
      proxyUrl: '/api/proxy/gladia',
      languages: ['en', 'es'],
      codeSwitching: true,
      endpointing: 0.3,
    }),
    new AnthropicLLM({
      proxyUrl: '/api/proxy/anthropic',
      model: 'claude-haiku-4-5',
      maxTokens: 256,
      systemPrompt: 'You are a helpful voice assistant. Keep responses under two sentences.',
    }),
    new NativeTTS({ voiceLang: 'en-US' }),
  ],
  conversationHistory: { enabled: true, maxTurns: 10 },
  logging: { enabled: true, level: 'info' },
});

agent.on('transcription.final', (event) => {
  console.log('User said:', event.text);
});

agent.on('response.text', (event) => {
  console.log('Assistant:', event.text);
});

await agent.initialize();
await agent.startListening();

Utterance completion

Gladia segments speech into utterances server-side using its endpointing setting: after the configured silence, the current utterance is closed and a transcript message with is_final: true arrives. While the user speaks, partial transcripts stream in with is_final: false and are emitted as interim results. Because every final transcript closes an utterance, GladiaSTT emits each one with utteranceComplete: true — the flag CompositeVoice checks to trigger LLM processing.

Gladia’s default endpointing (0.05 s) is very aggressive and can split sentences at every short pause. For conversational agents, set endpointing to around 0.3-0.8 seconds for more natural turns. maximumDurationWithoutEndpointing (default 5 s) caps how long a single utterance can run before Gladia forces an endpoint.

Tips and gotchas

• Always keep keys server-side in production. Pass proxyUrl and the proxy injects the x-gladia-key header into the session-init request. Only that one POST goes through the proxy — the audio WebSocket connects directly to the tokenized URL Gladia returns, so proxy bandwidth stays negligible.
• No peer dependencies. GladiaSTT uses native fetch and the SDK’s built-in WebSocketManager — no extra packages to install.
• Audio is sent as raw binary frames. No base64 encoding overhead — the provider forwards ArrayBuffer chunks directly. The bytes must match the session’s encoding, sampleRate, bitDepth, and channels.
• Tune endpointing for your use case. Low values give snappy turn-taking but may split sentences; higher values wait longer before finalizing.
• Word detail in metadata. Final results include metadata.words (word-level timing and confidence) plus the utterance language, channel, start, and end.
• Pin the language when you can. With minimal audio context, live language detection is sensitive — set languages: ['en'] to pin it, or enable codeSwitching for multilingual conversations.
• Automatic reconnection resumes the session. The WebSocket URL embeds the session token, so the WebSocketManager’s reconnection (up to 5 attempts with exponential backoff) reattaches to the same Gladia session.
• Sessions are capped at 3 hours by Gladia. Reconnect with a fresh connect() for longer workloads.
• Graceful disconnect. disconnect() sends a stop_recording message so Gladia transcribes any buffered audio before the socket closes. You can also call stopRecording() manually. The session id is available via getSessionId() for fetching full results from GET /v2/live/{id} afterwards.
• No preflight signals. GladiaSTT does not emit preflight/eager end-of-turn events. If you need the eager LLM pipeline, use DeepgramFlux instead.

Related resources

• Proxy server example — secure your API key server-side
• API reference: GladiaSTT
• Providers reference