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
npm install @micdrop/gradiumThe 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 MicdropServernew 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, monostt.transcribe(createReadStream('speech.pcm'))Events
| Event | Payload | Description |
|---|---|---|
Transcript | string | Transcription of one utterance, emitted once per utterance even when the next one starts before it returns. The text is empty when nothing was recognized. |
Failed | Buffer[] | 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
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | Required | Your Gradium API key |
modelName | string | 'default' | Model name to use for transcription |
inputFormat | GradiumInputFormat | 'pcm_16000' | Audio input format of the incoming stream |
language | string | '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) |
jsonConfig | GradiumASRJsonConfig | Optional | Advanced transcription configuration |
connectionTimeout | number | 5000 | Timeout in milliseconds for WebSocket connection |
transcriptionTimeout | number | 4000 | Timeout in milliseconds to wait for the transcript of each utterance |
retryDelay | number | 1000 | Delay in milliseconds between reconnection attempts |
maxRetry | number | 3 | Number 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.