> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Plugin

> Use Gnani Prisma (STT) and Timbre (TTS) inside LiveKit Agents voice pipelines for Indian languages.

## 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.

```text theme={null}
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](https://gnani.ai/).

***

## Installation

```bash theme={null}
pip install livekit-plugins-gnani
```

This also installs [`websockets`](https://pypi.org/project/websockets/) and [`livekit-agents`](https://pypi.org/project/livekit-agents/) as dependencies.

**Requirements:** Python 3.10+

***

## Prerequisites

You need a Gnani API key. [Gnani APIs](https://app.gnani.ai/voice)

All APIs require a single API key — no `organization_id` or `user_id` needed.

```bash theme={null}
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:**

```python theme={null}
stt = STT(api_key="your-api-key", language="hi-IN")
tts = TTS(api_key="your-api-key")
```

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

***

## 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)

```python theme={null}
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)

```python theme={null}
from livekit.plugins.gnani import TTS

tts = TTS(voice="Pranav")
```

### Text-to-Speech (SSE Streaming)

```python theme={null}
from livekit.plugins.gnani import TTS

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

### Text-to-Speech (WebSocket Streaming)

```python theme={null}
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)`

```python theme={null}
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](#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()`

```python theme={null}
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](/vachana/STT/stt-websocket#pcm-specification) for full details.

### Settings

| Parameter     | Type     | Default                    | Description                                                            |
| ------------- | -------- | -------------------------- | ---------------------------------------------------------------------- |
| `language`    | `string` | `"en-IN"`                  | BCP-47 language code. See [Supported Languages](#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

```python theme={null}
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](/api/TTS/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

```python theme={null}
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](/api/TTS/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()`

```python theme={null}
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](/api/TTS/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](/api/TTS/available-voices).

***

## 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](/vachana/STT/speech-to-text#supported-languages) and [STT Realtime — Supported Languages](/vachana/STT/stt-websocket#supported-languages).

### TTS Languages (Text-to-Speech)

For the full list of supported languages, see [TTS — Supported Languages](/vachana/TTS/tts-inference#supported-languages).

***

## Further Reading

* [STT REST API](/vachana/STT/speech-to-text) — file-based transcription reference
* [STT Realtime API](/vachana/STT/stt-websocket) — WebSocket protocol reference
* [TTS REST API](/vachana/TTS/tts-inference) — synchronous synthesis reference
* [TTS Streaming (SSE)](/vachana/TTS/tts-sse) — SSE synthesis reference
* [TTS Realtime API](/vachana/TTS/tts-websocket) — WebSocket TTS reference
* [`livekit-plugins-gnani` on PyPI](https://pypi.org/project/livekit-plugins-gnani/) — this plugin
* [LiveKit Agents Docs](https://docs.livekit.io/agents/) — LiveKit framework reference
* [Gnani STT Plugin Guide](https://docs.livekit.io/agents/integrations/stt/gnani/) — LiveKit STT integration
* [Gnani TTS Plugin Guide](https://docs.livekit.io/agents/integrations/tts/gnani/) — LiveKit TTS integration