gradium-node

Unofficial Node.js / TypeScript client for the Gradium streaming TTS & STT API.

Gradium ships official SDKs for Python and Rust. This one fills the JavaScript gap.

---

Note Community project. Not affiliated with or endorsed by Gradium. Built by a developer who wanted to use their API from Node.

Install

npm install gradium-node

# .env
GRADIUM_API_KEY=your_key_here

Text → Speech

import { Gradium } from 'gradium-node';
import fs from 'node:fs';

const gradium = new Gradium({ apiKey: process.env.GRADIUM_API_KEY! });

const wav = await gradium.tts.toWav({ text: 'Hello from Node.' });

fs.writeFileSync('output.wav', wav);

No WebSocket. No base64. No WAV header. No sample rate.

Streaming audio

Audio arrives chunk by chunk, as the model generates it.

const stream = gradium.tts.stream({ text: 'This arrives as it is generated.' });

stream.on('audio', (chunk) => speaker.write(chunk.data));
stream.on('text',  (seg)   => console.log(seg.text, seg.startS));
stream.on('end',   ()      => console.log('done'));

Streaming text in — for voice agents

Push tokens as your LLM produces them. Audio starts playing before the sentence finishes.

const stream = gradium.tts.stream({});

for await (const token of llm) {
  stream.sendText(token);
}

stream.end();

Text sent before the socket finishes opening is buffered and flushed automatically — so you can't silently lose the first half of a sentence.

Speech → Text

const stt = gradium.stt.stream({ inputFormat: 'pcm_24000', language: 'en' });

stt.on('transcript', (t) => console.log(t.text));

stt.sendAudio(pcmBuffer);   // any length — framing is handled for you
stt.end();

const transcript = await stt.text();

What this handles for you

WebSocket lifecycle	setup, ready, text, audio, end_of_stream, errors
Base64 decoding	audio arrives as base64 inside JSON, not binary frames
WAV headers	built from the sample rate the server actually reports
PCM framing	sliced into the exact frame size STT expects, with silence padding
Early writes	text or audio sent before the socket is ready is buffered, not dropped

⚠️ Gotcha worth knowing

TTS pcm defaults to 48000 Hz. STT pcm defaults to 24000 Hz.

Pipe one into the other using defaults and you get a garbage transcript — silently, with no error. Pin both explicitly:

gradium.tts.stream({ outputFormat: 'pcm_24000' });
gradium.stt.stream({ inputFormat:  'pcm_24000' });

Examples

npm run example:tts         # text → a playable wav file
npm run example:stream      # audio, chunk by chunk
npm run example:llm         # streaming text in, like an LLM
npm run example:roundtrip   # text → speech → text

Not yet supported

Voice cloning · pronunciation dictionaries · multiplexing · flush · VAD events

PRs welcome.

---

_{MIT · Built with the Gradium free tier}