LiveKit Plugin

Overview

livekit-plugins-gnani is a LiveKit Agents plugin that wraps the Gnani STT and TTS APIs into LiveKit’s standard stt.STT and tts.TTS base classes. Drop it into any LiveKit voice agent pipeline and get high-accuracy Indian-language speech recognition and low-latency synthesis without managing WebSocket connections yourself.

livekit-plugins-gnani
  ├── STT (Prisma): REST + WebSocket
  └── TTS (Timbre): REST + SSE + WebSocket
        ↑
Your LiveKit voice agent

This plugin implements the Gnani REST and WebSocket APIs directly using aiohttp (REST STT/TTS) and websockets (streaming STT/TTS). No external SDK is required — connection logic, authentication, and audio format handling are self-contained. Authentication uses a single api_key passed via the X-API-Key-ID header. This integration is maintained by Gnani.ai.

Installation

pip install livekit-plugins-gnani

This also installs websockets and livekit-agents as dependencies. Requirements: Python 3.10+

Prerequisites

You need a Gnani API key. Gnani APIs All APIs require a single API key — no organization_id or user_id needed.

export GNANI_API_KEY="your-api-key"

Variable	Purpose
`GNANI_API_KEY`	API key for Gnani STT and TTS

Or pass the key in the constructor:

stt = STT(api_key="your-api-key", language="hi-IN")
tts = TTS(api_key="your-api-key")

If upgrading from an earlier version, remove any organization_id and user_id parameters — they are no longer accepted.

Services

This plugin provides STT and TTS classes with multiple transports. Choose based on your use case:

Class	Type	Transport	Best for
`STT`	STT	REST (`recognize()`)	File-based transcription via `POST /stt/v3`
`STT`	STT	WebSocket (`stream()`)	Live conversations, real-time agents
`TTS`	TTS	REST (`synthesize_method="rest"`)	Batch synthesis, non-streaming pipelines
`TTS`	TTS	SSE (`synthesize_method="sse"`)	Chunked synthesis with lower latency than REST
`TTS`	TTS	WebSocket (`synthesize_method="websocket"` or `stream()`)	Lowest-latency synthesis for live agents

Quick Start

Speech-to-Text (REST + Streaming)

from livekit.plugins.gnani import STT

stt = STT(language="hi-IN")

# REST STT (file-based transcription)
speech_event = await stt.recognize(audio_buffer)

# Streaming STT (real-time WebSocket)
speech_stream = stt.stream()

Text-to-Speech (REST)

from livekit.plugins.gnani import TTS

tts = TTS(voice="Pranav")

Text-to-Speech (SSE Streaming)

from livekit.plugins.gnani import TTS

tts = TTS(voice="Pranav", synthesize_method="sse")

Text-to-Speech (WebSocket Streaming)

from livekit.plugins.gnani import TTS

tts = TTS(voice="Pranav", synthesize_method="websocket")

All three TTS modes work with the standard LiveKit voice agent pipeline. The synthesize_method controls which transport synthesize() uses (REST, SSE, or WebSocket). The stream() method always uses WebSocket regardless of this setting.

STT — Speech-to-Text (REST)

File-based transcription via REST.

Calls POST /stt/v3
Suitable for pre-recorded audio and file-based pipelines
Invoked through stt.recognize(audio_buffer)

from livekit.plugins.gnani import STT

stt = STT(
    language="hi-IN",
    sample_rate=16000,
    format="verbatim",
)

speech_event = await stt.recognize(audio_buffer)

Settings

Parameter	Type	Default	Description
`language`	`string`	`"en-IN"`	BCP-47 language code. See Supported Languages.
`sample_rate`	`int`	`16000`	Audio sample rate in Hz. Accepted values: `8000`, `16000`.
`format`	`string`	`"verbatim"`	Output format. Use `"transcribe"` to enable ITN.
`itn_native_numerals`	`bool`	`False`	Keep native numerals when ITN is enabled.
`api_key`	`string`	`None`	API key. Defaults to `GNANI_API_KEY` env var.
`base_url`	`string`	`"https://api.vachana.ai"`	API base URL.

STT — Speech-to-Text (WebSocket)

Real-time streaming speech-to-text via WebSocket with VAD.

Connects to wss://api.vachana.ai/stt/v3/stream
Sends raw PCM audio in 1,024-byte frames
Supports 8 kHz and 16 kHz sample rates
Invoked through stt.stream()

from livekit.plugins.gnani import STT

stt = STT(
    language="hi-IN",
    sample_rate=16000,            # 8000 or 16000
)

speech_stream = stt.stream()

Streaming PCM Specification

All streaming audio must be sent as raw PCM binary frames — no container format (WAV, MP3) mid-stream.

Property	16 kHz	8 kHz
Encoding	PCM signed 16-bit little-endian	PCM signed 16-bit little-endian
Sample Rate	16,000 Hz	8,000 Hz
Channels	1 (mono)	1 (mono)
Samples per chunk	512	512
Bytes per frame	1,024 bytes (512 samples × 2 bytes)	1,024 bytes (512 samples × 2 bytes)
Frame duration	32 ms	64 ms

Frames must be sent at real-time cadence. See STT Realtime — PCM Specification for full details.

Settings

Parameter	Type	Default	Description
`language`	`string`	`"en-IN"`	BCP-47 language code. See Supported Languages.
`sample_rate`	`int`	`16000`	Audio sample rate in Hz. Accepted values: `8000`, `16000`.
`format`	`string`	`"verbatim"`	Output format. Use `"transcribe"` to enable ITN.
`api_key`	`string`	`None`	API key. Defaults to `GNANI_API_KEY` env var.
`base_url`	`string`	`"https://api.vachana.ai"`	API base URL.

TTS — Text-to-Speech (REST)

REST-based text-to-speech for non-streaming use cases. Returns the complete audio in a single response.

Single-request batch synthesis via synthesize_method="rest" (default)
Suitable for batch synthesis or pipelines where streaming is not needed

from livekit.plugins.gnani import TTS

tts = TTS(
    voice="Pranav",
    synthesize_method="rest",
)

Settings

Parameter	Type	Default	Description
`voice`	`string`	`"Pranav"`	Voice ID. See Available Voices.
`model`	`string`	`"timbre-v2.5"`	TTS model ID.
`sample_rate`	`int`	`16000`	Output sample rate in Hz (`8000`, `16000`, `22050`, `44100`).
`encoding`	`string`	`"linear_pcm"`	Audio encoding (`linear_pcm`, `oggopus`).
`container`	`string`	`"wav"`	Container format (`wav`, `raw`, `mp3`, `mulaw`, `ogg`).
`num_channels`	`int`	`1`	Number of audio channels.
`bitrate`	`string`	`None`	Optional bitrate (`96k`, `128k`, `192k`).
`synthesize_method`	`string`	`"rest"`	Transport for `synthesize()`.
`api_key`	`string`	`None`	API key. Defaults to `GNANI_API_KEY` env var.
`base_url`	`string`	`"https://api.vachana.ai"`	API base URL.

TTS — Text-to-Speech (SSE)

Streaming text-to-speech via Server-Sent Events. Lower latency than REST.

Chunked synthesis via synthesize_method="sse"
Streams audio chunks as synthesis progresses

from livekit.plugins.gnani import TTS

tts = TTS(
    voice="Pranav",
    synthesize_method="sse",
)

Settings

Parameter	Type	Default	Description
`voice`	`string`	`"Pranav"`	Voice ID. See Available Voices.
`model`	`string`	`"timbre-v2.5"`	TTS model ID.
`sample_rate`	`int`	`16000`	Output sample rate in Hz.
`encoding`	`string`	`"linear_pcm"`	Audio encoding (`linear_pcm`, `oggopus`).
`container`	`string`	`"wav"`	Container format (`wav`, `raw`, `mp3`, `mulaw`, `ogg`).
`synthesize_method`	`string`	`"sse"`	Set to `"sse"` for Server-Sent Events.
`api_key`	`string`	`None`	API key. Defaults to `GNANI_API_KEY` env var.

TTS — Text-to-Speech (WebSocket, recommended)

Streaming text-to-speech via WebSocket. Lowest latency for live conversational agents.

Use synthesize_method="websocket" for synthesize(), or call stream() (always WebSocket)
Ideal for live agents where latency matters
Change voice or model at runtime via update_options()

from livekit.plugins.gnani import TTS

tts = TTS(
    voice="Pranav",
    synthesize_method="websocket",
)

Settings

Parameter	Type	Default	Description
`voice`	`string`	`"Pranav"`	Voice ID. See Available Voices.
`model`	`string`	`"timbre-v2.5"`	TTS model ID.
`sample_rate`	`int`	`16000`	Output sample rate in Hz.
`encoding`	`string`	`"linear_pcm"`	Audio encoding (`linear_pcm`, `oggopus`).
`container`	`string`	`"wav"`	Container format (`wav`, `raw`, `mp3`, `mulaw`, `ogg`).
`synthesize_method`	`string`	`"websocket"`	Set to `"websocket"` for WS `synthesize()`.
`api_key`	`string`	`None`	API key. Defaults to `GNANI_API_KEY` env var.

Available Voices

To see the available voices, click here.

Supported Languages

STT Languages (Speech-to-Text)

STT uses BCP-47 locale codes (e.g. hi-IN, bn-IN). Note: STT uses the -IN suffix (unlike TTS). For the full list, see STT — Supported Languages and STT Realtime — Supported Languages.

TTS Languages (Text-to-Speech)

For the full list of supported languages, see TTS — Supported Languages.

Gnani APIs

APIs

Use Cases

Overview

Installation

Prerequisites

Services

Quick Start

Speech-to-Text (REST + Streaming)

Text-to-Speech (REST)

Text-to-Speech (SSE Streaming)

Text-to-Speech (WebSocket Streaming)

STT — Speech-to-Text (REST)

Settings

STT — Speech-to-Text (WebSocket)

Streaming PCM Specification

Settings

TTS — Text-to-Speech (REST)

Settings

TTS — Text-to-Speech (SSE)

Settings

TTS — Text-to-Speech (WebSocket, recommended)

Settings

Available Voices

Supported Languages

STT Languages (Speech-to-Text)

TTS Languages (Text-to-Speech)

Further Reading

​Overview

​Installation

​Prerequisites

​Services

​Quick Start

​Speech-to-Text (REST + Streaming)

​Text-to-Speech (REST)

​Text-to-Speech (SSE Streaming)

​Text-to-Speech (WebSocket Streaming)

​STT — Speech-to-Text (REST)

​Settings

​STT — Speech-to-Text (WebSocket)

​Streaming PCM Specification

​Settings

​TTS — Text-to-Speech (REST)

​Settings

​TTS — Text-to-Speech (SSE)

​Settings

​TTS — Text-to-Speech (WebSocket, recommended)

​Settings

​Available Voices

​Supported Languages

​STT Languages (Speech-to-Text)

​TTS Languages (Text-to-Speech)

​Further Reading

Overview

Installation

Prerequisites

Services

Quick Start

Speech-to-Text (REST + Streaming)

Text-to-Speech (REST)

Text-to-Speech (SSE Streaming)

Text-to-Speech (WebSocket Streaming)

STT — Speech-to-Text (REST)

Settings

STT — Speech-to-Text (WebSocket)

Streaming PCM Specification

Settings

TTS — Text-to-Speech (REST)

Settings

TTS — Text-to-Speech (SSE)

Settings

TTS — Text-to-Speech (WebSocket, recommended)

Settings

Available Voices

Supported Languages

STT Languages (Speech-to-Text)

TTS Languages (Text-to-Speech)

Further Reading