---
title: "Gradium Speech to Text in Node.js | Micdrop"
description: "Transcribe the user in real time with Gradium's WebSocket API from your Node server, on the EU endpoint by default or on the US one."
url: "https://micdrop.dev/docs/speech-to-text/gradium"
---

# 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

```bash
npm install @micdrop/gradium
```

The same package also provides [a text to speech](/docs/text-to-speech/gradium). The [providers page](/docs/providers) shows what every provider covers.

## Usage with MicdropServer

```typescript
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

```typescript
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

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](/docs/speech-to-text/custom) 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:

```typescript
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.
