Gradium STT plugin guide | LiveKit Documentation

Available inPython

Overview

This plugin allows you to use Gradium as an STT provider for your voice agents. Gradium streams transcription over a WebSocket connection and returns both interim and final transcripts.

Installation

Install the plugin from PyPI:

uv add "livekit-agents[gradium]~=1.5"

Authentication

The Gradium plugin requires a Gradium API key .

Set GRADIUM_API_KEY in your .env file:

GRADIUM_API_KEY=<your-gradium-api-key>

Usage

Use Gradium STT in an AgentSession or as a standalone transcription service. For example, you can use this STT in the Voice AI quickstart.

from livekit.agents import AgentSession
from livekit.plugins import gradium

session = AgentSession(
    stt=gradium.STT(
        model_name="default",
        language="en",
    ),
    # ... llm, tts, etc.
)

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

api_keystringEnv: GRADIUM_API_KEY

Gradium API key. Required if the environment variable isn't set.

model_namestringDefault: default

Gradium STT model to use.

languagestringDefault: en

Language code for the input audio. Override it per stream with stt.stream(language="..."), which applies to that stream only and leaves the instance default unchanged. It can't be changed with update_options(). The plugin sends the base language subtag, so en-US is sent as en.

sample_rateintegerDefault: 24000

Input audio sample rate in Hz. 24000 is the only supported value; any other value raises a ValueError.

encodingstringDefault: pcm_s16le

Input audio encoding. pcm_s16le is the only supported value.

temperaturefloatDefault: None

Temperature used for decoding. Leave it unset for greedy sampling. The plugin passes the value through to Gradium without validating its range.

vad_thresholdfloatDefault: 0.9

Inactivity probability, as reported by Gradium's voice activity detection, above which the selected bucket counts as silence for endpointing.

vad_bucketintegerDefault: 2

Index of the bucket to read from Gradium's voice activity detection predictions. Set it to None to disable endpointing.

vad_flushbooleanDefault: true

Flush the recognizer state the first time voice activity detection triggers, so text that's still being processed is returned as soon as possible.

buffer_size_secondsfloatDefault: 0.08

Audio buffer size in seconds. This is the only parameter that update_options() accepts, and changing it reconnects the WebSocket.

Additional resources

The following resources provide more information about using Gradium with LiveKit Agents.

Python package

The livekit-plugins-gradium package on PyPI.

Plugin reference

Reference for the Gradium STT plugin.

GitHub repo

View the source or contribute to the LiveKit Gradium STT plugin.

Gradium docs

Gradium API documentation.

Voice AI quickstart

Get started with LiveKit Agents and Gradium.

Gradium TTS

Guide to the Gradium TTS plugin with LiveKit Agents.