Gradium

Gradium STT and TTS implementation for @micdrop/server.

This package provides high-quality real-time speech-to-text and text-to-speech implementations using Gradium’s WebSocket streaming API.

Installation

npm install @micdrop/gradium

Gradium STT (Speech-to-Text)

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

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 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 transcription
`retryDelay`	`number`	`1000`	Delay in milliseconds between reconnection attempts
`maxRetry`	`number`	`3`	Maximum number of reconnection attempts before failing

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.

Gradium TTS (Text-to-Speech)

Usage with MicdropServer

import { GradiumTTS } from '@micdrop/gradium'
import { MicdropServer } from '@micdrop/server'

const tts = new GradiumTTS({
  apiKey: process.env.GRADIUM_API_KEY || '',
  voiceId: 'YTpq7expH9539ERJ', // Gradium voice ID
  modelName: 'default', // Optional: model name
  outputFormat: 'pcm_16000', // Optional: audio format
  region: 'eu', // Optional: 'eu' or 'us'
})

// Use with MicdropServer
new MicdropServer(socket, {
  tts,
  // ... other options
})

Usage without MicdropServer

import { GradiumTTS } from '@micdrop/gradium'
import { Readable } from 'stream'

const tts = new GradiumTTS({
  apiKey: process.env.GRADIUM_API_KEY || '',
  voiceId: 'YTpq7expH9539ERJ',
})

// Audio is raw PCM, 16 bits, 16 kHz, mono
tts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))
tts.on('Failed', (texts) => console.error('Failed:', texts))

tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))

Events

Event	Payload	Description
`Audio`	`Buffer`	A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played.
`Failed`	`string[]`	Synthesis gave up after its retries, with the text that stayed unspoken.

See the TTS interface for the full contract.

Options

Option	Type	Default	Description
`apiKey`	`string`	Required	Your Gradium API key
`voiceId`	`string`	Required	Gradium voice ID
`modelName`	`string`	`'default'`	Model name to use for speech synthesis
`outputFormat`	`GradiumOutputFormat`	`'pcm_16000'`	Audio output format
`region`	`'eu' \| 'us'`	`'eu'`	API region (EU or US endpoint)
`jsonConfig`	`GradiumJsonConfig`	Optional	Advanced voice configuration
`connectionTimeout`	`number`	`5000`	Timeout in milliseconds for WebSocket connection
`retryDelay`	`number`	`1000`	Delay in milliseconds between reconnection attempts
`maxRetry`	`number`	`3`	Maximum number of reconnection attempts before failing

Output Formats

Format	Description
`pcm`	PCM 48kHz, 16-bit signed integer mono
`pcm_16000`	PCM 16kHz, 16-bit signed integer mono
`pcm_24000`	PCM 24kHz, 16-bit signed integer mono
`pcm_8000`	PCM 8kHz, 16-bit signed integer mono
`wav`	WAV format
`opus`	Opus codec wrapped in an Ogg container
`ulaw_8000`	u-law 8kHz
`alaw_8000`	A-law 8kHz

Advanced Voice Configuration

The jsonConfig option allows you to fine-tune voice characteristics:

const tts = new GradiumTTS({
  apiKey: 'your-api-key',
  voiceId: 'your-voice-id',
  jsonConfig: {
    temp: 0.7, // Temperature: 0 to 1.4 (default: 0.7)
    cfg_coef: 2.0, // Voice similarity: 1.0 to 4.0 (default: 2.0)
    padding_bonus: 0, // Speed control: -4.0 to 4.0
  },
})

Parameter	Type	Range	Default	Description
`temp`	`number`	0 - 1.4	0.7	Controls randomness in speech generation
`cfg_coef`	`number`	1.0 - 4.0	2.0	Controls similarity to the original voice
`padding_bonus`	`number`	-4.0 - 4.0	0	Controls speech speed

Getting Started

Sign up for a Gradium account and get your API key
Choose a voice ID from the Gradium voice library
Install the package and configure with your credentials

import { GradiumTTS } from '@micdrop/gradium'

const tts = new GradiumTTS({
  apiKey: 'your-gradium-api-key',
  voiceId: 'your-voice-id',
  region: 'eu', // Use 'us' for US endpoint
  outputFormat: 'pcm_16000',
})

// Use with MicdropServer
new MicdropServer(socket, {
  tts,
  // ... other options
})