Gladia Streaming Speech to Text in Node.js
Gladia implementation for @micdrop/server.
This package provides high-quality real-time speech-to-text implementation using Gladia’s streaming API.
With GladiaSTT as the only component, the server transcribes the call without answering and sends each sentence to the client as text.
Installation
npm install @micdrop/gladiaUsage with MicdropServer
import { GladiaSTT } from '@micdrop/gladia'import { MicdropServer } from '@micdrop/server'
const stt = new GladiaSTT({ apiKey: process.env.GLADIA_API_KEY || '',})
// Use with MicdropServernew MicdropServer(socket, { stt, // ... other options})Usage without MicdropServer
import { GladiaSTT } from '@micdrop/gladia'import { createReadStream } from 'fs'
const stt = new GladiaSTT({ apiKey: process.env.GLADIA_API_KEY || '',})
stt.on('Transcript', (text) => console.log('Transcript:', text))stt.on('Failed', (chunks) => console.error('Failed:', chunks.length, 'chunks'))
// Audio is raw PCM, 16 bits, 16 kHz, monostt.transcribe(createReadStream('speech.pcm'))Events
| Event | Payload | Description |
|---|---|---|
Transcript | string | Transcription of one utterance. The text is empty when nothing was recognized. |
Failed | Buffer[] | Transcription gave up after its retries, with the audio chunks left pending. |
See the STT interface for the full contract.
Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | Required | Your Gladia API key |
settings | DeepPartial<GladiaLiveSessionPayload> | Optional | Advanced configuration for Gladia live session |
connectionTimeout | number | 5000 | Timeout in milliseconds for the session request, then for the WebSocket connection |
transcriptionTimeout | number | 4000 | Timeout in milliseconds to wait for transcription |
retryDelay | number | 1000 | Delay in milliseconds between reconnection attempts |
maxRetry | number | 3 | Maximum number of failed attempts in a row before Failed |
Connection and Retries
GladiaSTT requests a session URL and opens its WebSocket on every connection attempt, so a failed session request and a failed connection share the same budget of maxRetry attempts in a row, retryDelay apart. A connection that drops, even a clean close by Gladia, is opened again, and the audio of every utterance still waiting for its transcript is sent again to the new session. Once the budget runs out, Failed hands that audio back, and the next utterance tries to connect again.
How an Utterance Ends
Each stream given to transcribe() is one utterance and gets exactly one Transcript event. Gladia cuts the speech into segments at each pause and finalizes them one by one, so a long sentence can span several of them. GladiaSTT joins the final text of every segment heard during the stream, and emits it once the stream ended and all of them stayed final for half a second, the time for a segment that starts after a pause to show up. Partial transcripts are turned on by default for that purpose: they reveal the segments still being heard. With nothing heard at all, the transcript is empty after transcriptionTimeout, and a segment Gladia never finalizes is emitted with its latest partial text at that point.
Configuration Settings
The settings option allows you to customize various aspects of the transcription:
Language Configuration
const stt = new GladiaSTT({ apiKey: 'your-api-key', settings: { language_config: { languages: ['en', 'fr', 'es'], // Specify target languages code_switching: true, // Enable automatic language switching }, },})To carry a detected language from Gladia into the agent’s reply and voice, use this multilingual voice-agent configuration pattern.
Pre-processing Options
const stt = new GladiaSTT({ apiKey: 'your-api-key', settings: { pre_processing: { audio_enhancer: true, // Enhance audio quality speech_threshold: 0.7, // Adjust speech detection sensitivity (0.0-1.0) }, },})Real-time Processing Features
const stt = new GladiaSTT({ apiKey: 'your-api-key', settings: { realtime_processing: { words_accurate_timestamps: true, // Get word-level timestamps translation: true, // Enable translation translation_config: { target_languages: ['fr', 'es'], // Translate to French and Spanish model: 'enhanced', // Use enhanced translation model }, named_entity_recognition: true, // Extract entities (names, places, etc.) sentiment_analysis: true, // Analyze sentiment custom_vocabulary: true, // Use custom vocabulary custom_vocabulary_config: { vocabulary: ['Micdrop', { value: 'API', pronunciations: ['A-P-I'] }], default_intensity: 1, }, }, },})Supported Languages
Gladia supports 90+ languages with automatic detection. Some of the most commonly used languages include:
| Code | Language | Code | Language | Code | Language |
|---|---|---|---|---|---|
en | English | es | Spanish | fr | French |
de | German | it | Italian | pt | Portuguese |
ru | Russian | ja | Japanese | ko | Korean |
zh | Chinese | ar | Arabic | hi | Hindi |
nl | Dutch | pl | Polish | tr | Turkish |
sv | Swedish | da | Danish | no | Norwegian |
fi | Finnish | cs | Czech | hu | Hungarian |
el | Greek | he | Hebrew | th | Thai |
vi | Vietnamese | id | Indonesian | ms | Malay |
See the types file for the complete list of supported language codes.
Advanced Features
Custom Vocabulary
Improve transcription accuracy for domain-specific terms:
const stt = new GladiaSTT({ apiKey: 'your-api-key', settings: { realtime_processing: { custom_vocabulary: true, custom_vocabulary_config: { vocabulary: [ 'Micdrop', 'WebSocket', { value: 'OAuth', pronunciations: ['O-Auth', 'oh-auth'], intensity: 2, language: 'en', }, ], default_intensity: 1, }, }, },})Translation
Real-time translation during transcription:
const stt = new GladiaSTT({ apiKey: 'your-api-key', settings: { realtime_processing: { translation: true, translation_config: { target_languages: ['fr', 'es', 'de'], model: 'enhanced', // 'base' or 'enhanced' match_original_utterances: true, context_adaptation: true, context: 'Technical software development discussion', }, }, },})