🎤Micdrop

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

Terminal window
npm install @micdrop/gladia

Usage with MicdropServer

import { GladiaSTT } from '@micdrop/gladia'
import { MicdropServer } from '@micdrop/server'
const stt = new GladiaSTT({
apiKey: process.env.GLADIA_API_KEY || '',
})
// Use with MicdropServer
new 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, mono
stt.transcribe(createReadStream('speech.pcm'))

Events

EventPayloadDescription
TranscriptstringTranscription of one utterance. The text is empty when nothing was recognized.
FailedBuffer[]Transcription gave up after its retries, with the audio chunks left pending.

See the STT interface for the full contract.

Options

OptionTypeDefaultDescription
apiKeystringRequiredYour Gladia API key
settingsDeepPartial<GladiaLiveSessionPayload>OptionalAdvanced configuration for Gladia live session
connectionTimeoutnumber5000Timeout in milliseconds for the session request, then for the WebSocket connection
transcriptionTimeoutnumber4000Timeout in milliseconds to wait for transcription
retryDelaynumber1000Delay in milliseconds between reconnection attempts
maxRetrynumber3Maximum 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:

CodeLanguageCodeLanguageCodeLanguage
enEnglishesSpanishfrFrench
deGermanitItalianptPortuguese
ruRussianjaJapanesekoKorean
zhChinesearArabichiHindi
nlDutchplPolishtrTurkish
svSwedishdaDanishnoNorwegian
fiFinnishcsCzechhuHungarian
elGreekheHebrewthThai
viVietnameseidIndonesianmsMalay

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',
},
},
},
})