🎤Micdrop

Gradium Speech to Text in Node.js

GradiumSTT streams the voice of the user to Gradium’s WebSocket API and emits the transcript of each utterance. It connects to the EU endpoint by default.

Installation

Terminal window
npm install @micdrop/gradium

The same package also provides a text to speech. The providers page shows what every provider covers.

Usage with MicdropServer

import { GradiumSTT } from '@micdrop/gradium'
import { MicdropServer } from '@micdrop/server'
const stt = new GradiumSTT({
apiKey: process.env.GRADIUM_API_KEY || '',
modelName: 'default', // Optional: model name
inputFormat: 'pcm_16000', // Optional: audio format
language: 'en', // Optional: language hint
region: 'eu', // Optional: 'eu' or 'us'
})
// Use with MicdropServer
new MicdropServer(socket, {
stt,
// ... other options
})

Usage without MicdropServer

import { GradiumSTT } from '@micdrop/gradium'
import { createReadStream } from 'fs'
const stt = new GradiumSTT({
apiKey: process.env.GRADIUM_API_KEY || '',
language: 'en',
})
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, emitted once per utterance even when the next one starts before it returns. The text is empty when nothing was recognized.
FailedBuffer[]Every reconnection attempt failed, with the audio of the utterances still waiting for their transcript. The next utterance connects again.

See the STT interface for the full contract.

Options

OptionTypeDefaultDescription
apiKeystringRequiredYour Gradium API key
modelNamestring'default'Model name to use for transcription
inputFormatGradiumInputFormat'pcm_16000'Audio input format of the incoming stream
languagestring'any'Language of the speech, among en, fr, de, es and pt, or any to detect it (shortcut for jsonConfig.language)
region'eu' | 'us''eu'API region (EU or US endpoint)
jsonConfigGradiumASRJsonConfigOptionalAdvanced transcription configuration
connectionTimeoutnumber5000Timeout in milliseconds for WebSocket connection
transcriptionTimeoutnumber4000Timeout in milliseconds to wait for the transcript of each utterance
retryDelaynumber1000Delay in milliseconds between reconnection attempts
maxRetrynumber3Number of failed connection attempts in a row before emitting Failed

Utterances and reconnection

Each utterance keeps its own transcript and its own transcriptionTimeout, so a turn that ends before the previous one comes back from Gradium keeps its words apart. The connection counts as open once Gradium accepts the setup. When it drops, a graceful close included, GradiumSTT opens it again and sends the audio of the utterances still waiting for their transcript.

Advanced Transcription Configuration

The jsonConfig option allows you to fine-tune the transcription:

const stt = new GradiumSTT({
apiKey: 'your-api-key',
jsonConfig: {
language: 'en', // Language hint
target_language: 'fr', // Optional: translation target language
delay_in_frames: 16, // 0 to 80, each frame = 80ms
},
})

The model writes each word delay_in_frames frames after hearing it, 10 frames of 80 ms unless you set another value. GradiumSTT reads that delay when the session starts and sends as much silence at the end of each utterance, so the transcript of each turn ends with its last word. Lower delay_in_frames to get the transcript sooner, at the cost of some context for the model.