Gradium

OverviewCopy Anchor Link

• GradiumSTTService: streams audio over a WebSocket to Gradium and pushes interim and final transcriptions. By default the pipeline's VAD closes each utterance by flushing the server. With enableTurnDetection, Gradium's end-pointing signal decides when turns start and end instead.

InstallationCopy Anchor Link

bun add @pipedog/gradium

import { GradiumSTTService } from "@pipedog/gradium/stt";

PrerequisitesCopy Anchor Link

• A Gradium account and an API key from Gradium.
• Pass the key as apiKey. The examples read it from GRADIUM_API_KEY.

GradiumSTTServiceCopy Anchor Link

Connects to wss://api.gradium.ai/api/speech/asr, with the key in the x-api-key header.

ConfigurationCopy Anchor Link

SettingsCopy Anchor Link

Runtime-updatable settings, passed as settings: new GradiumSTTService.Settings({...}) (GradiumSTTSettings). The eot* and postFlushCooldownFrames fields tune turn detection and are null unless enableTurnDetection is true, which gives them the defaults below.

UsageCopy Anchor Link

import { Language } from "@pipedog/core/transcriptions/language";
import { GradiumSTTService } from "@pipedog/gradium/stt";

const stt = new GradiumSTTService({
  apiKey: process.env.GRADIUM_API_KEY ?? "",
  settings: new GradiumSTTService.Settings({ language: Language.EN }),
});

With the server's turn detection:

const withTurns = new GradiumSTTService({
  apiKey: process.env.GRADIUM_API_KEY ?? "",
  enableTurnDetection: true,
  settings: new GradiumSTTService.Settings({ eotHorizonS: 3.0, eotThreshold: 0.5 }),
});

Event handlersCopy Anchor Link

NotesCopy Anchor Link

• encoding is "pcm" (the sample rate is appended, for example pcm_16000), "wav" or "opus". Audio at a rate Gradium doesn't accept is resampled.
• With enableTurnDetection, local VAD frames are ignored and the service recommends ExternalUserTurnStrategies, which resolve its ProposedUserStartedSpeakingFrame and ProposedUserStoppedSpeakingFrame into user turns.

Generated from pipecat.runtimes and pipecat.compat in packages/gradium/package.json: ✅ means the compat smoke test passes on that runtime.

Runtime notesCopy Anchor Link

• The WebSocket goes through the core websocketConnect, with headers on the handshake.
• The deprecated InputParams, params and json_config options are not ported.
• Tested against local WebSocket servers, as upstream's tests do, not against Gradium itself.