> ## Documentation Index
> Fetch the complete documentation index at: https://daily-hush-pcc-session-recordings-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gnani

> Text-to-speech services for Gnani Vachana — REST, SSE, and WebSocket streaming for Indian languages

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="Gnani-AI-Mintlify" maintainerUrl="https://github.com/Gnani-AI-Mintlify" repo="https://github.com/Gnani-AI-Mintlify/pipecat-gnani" />

## Overview

`GnaniHttpTTSService`, `GnaniSSETTSService`, and `GnaniTTSService` synthesize
speech using [Gnani Vachana](https://gnani.ai/), a production speech AI platform
for 10+ Indian languages with real-time streaming and low-latency synthesis.

Use the REST service for simple request/response synthesis, the SSE service for
streaming with lower latency than REST, or the WebSocket `GnaniTTSService` for
lowest latency with interruption support via `InterruptibleTTSService`.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/Gnani-AI-Mintlify/pipecat-gnani">
    Source code, examples, and issues for the Gnani integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-gnani/">
    The `pipecat-gnani` package on PyPI
  </Card>

  <Card title="Gnani Website" icon="globe" href="https://gnani.ai">
    Learn about Gnani's speech AI platform
  </Card>

  <Card title="Gnani API Docs" icon="book" href="https://docs.gnani.ai/">
    TTS REST, SSE, and WebSocket API reference
  </Card>

  <Card title="Demo Video" icon="play" href="https://go.screenpal.com/watch/cOi2nynUax5">
    Gnani × Pipecat integration — STT/TTS pipeline and interruption handling
  </Card>

  <Card title="gnani-vachana SDK" icon="cube" href="https://pypi.org/project/gnani-vachana/">
    Core Gnani Vachana Python SDK (>= 0.7.9) installed as a dependency
  </Card>
</CardGroup>

## Installation

Install the community package directly:

```bash theme={null}
uv add pipecat-gnani
```

This also installs the [`gnani-vachana`](https://pypi.org/project/gnani-vachana/)
(>= 0.7.9) core SDK. The Python import package name remains `gnani`.

## Prerequisites

### Gnani Account Setup

Before using the Gnani TTS services, you need:

1. **Gnani API key**: Get one from [Gnani APIs](https://app.gnani.ai/voice).
2. **Set credentials**: Export `GNANI_API_KEY` as an environment variable.

### Required Environment Variables

* `GNANI_API_KEY`: Your Gnani Vachana API key for authentication

## Configuration

All three services share the same audio-format settings via their `Settings`
dataclasses. The key difference is transport: REST for single-request synthesis,
SSE for chunked streaming, and WebSocket for interruptible real-time synthesis.

### Shared constructor parameters

<ParamField path="api_key" type="str" required>
  Gnani Vachana API key for authentication.
</ParamField>

<ParamField path="voice_id" type="str" default="Pranav">
  Voice name for synthesis. For `timbre-v2.0`: `Pranav`, `Kaveri`, `Shubhra`,
  `Deepak`. For `timbre-v2.5`: 42 voices across 11 language groups — see
  [Available voices](#available-voices) below.
</ParamField>

<ParamField path="model" type="str" default="timbre-v2.0">
  TTS model identifier. One of `timbre-v2.0` or `timbre-v2.5`.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output sample rate in Hz. One of `8000`, `16000`, `22050`, `24000`, `44100`,
  or `48000`. When omitted, negotiated from `StartFrame`.
</ParamField>

<ParamField path="settings" type="Settings" default="None">
  Runtime-updatable TTS settings. See [Settings](#settings) below.
</ParamField>

### `GnaniHttpTTSService` and `GnaniSSETTSService` (HTTP)

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  Shared aiohttp session for HTTP requests.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument
using `GnaniHttpTTSService.Settings(...)`, `GnaniSSETTSService.Settings(...)`,
or `GnaniTTSService.Settings(...)`.

| Parameter      | Type       | Default         | Description                                                                        |
| -------------- | ---------- | --------------- | ---------------------------------------------------------------------------------- |
| `voice`        | `str`      | `"Pranav"`      | Voice identifier. See [Available voices](#available-voices).                       |
| `model`        | `str`      | `"timbre-v2.0"` | TTS model (`timbre-v2.0` or `timbre-v2.5`).                                        |
| `language`     | `Language` | `None`          | Synthesis language (`timbre-v2.5` only). BCP-47 code, e.g. `Language.HI_IN`.       |
| `encoding`     | `str`      | `"linear_pcm"`  | Audio encoding (`linear_pcm`, `oggopus`, `pcm_mulaw`, `pcm_alaw`).                 |
| `container`    | `str`      | `"wav"`         | Audio container (`raw`, `mp3`, `wav`, `ogg`, `mulaw`, `alaw`).                     |
| `sample_width` | `int`      | `2`             | Sample width in bytes (1–4).                                                       |
| `bitrate`      | `str`      | `None`          | MP3 bitrate (`32k`, `64k`, `96k`, `128k`, `192k`). Only used when `container=mp3`. |

<Note>
  For `timbre-v2.0`, voice selection determines synthesis language — no
  `language` parameter is sent. For `timbre-v2.5`, set `language` explicitly to
  control the synthesis language (e.g. `Language.HI_IN` for Hindi).

  When using `encoding="oggopus"`, set `container="raw"` (the API rejects
  `oggopus` with `container="ogg"`). For telephony A-law output, use
  `container="alaw"` with `sample_rate=8000`.
</Note>

<Note>
  Voice, model, and audio-format settings take effect on the next synthesis
  request. See the [source
  repository](https://github.com/Gnani-AI-Mintlify/pipecat-gnani) and [Gnani TTS
  docs](https://docs.gnani.ai/api/TTS/tts-inference) for the authoritative,
  up-to-date voice and language lists.
</Note>

## Available voices

### `timbre-v2.0` (4 voices)

`Pranav`, `Kaveri`, `Shubhra`, `Deepak`

### `timbre-v2.5` (42 voices)

| Language  | Voices                                                                                                |
| --------- | ----------------------------------------------------------------------------------------------------- |
| Hindi     | Nalini, Bhavna, Yashvi, Urmila, Jwala, Chitra, Ambuja, Deepak, Roopesh, Vikrant, Hemraj, Jalaj, Omkar |
| English   | Kaveri, Trupti, Devika, Pranav, Shlok, Girish                                                         |
| Tamil     | Asmita, Trisha, Brinda, Vedika, Noopur                                                                |
| Telugu    | Suhana, Lehara, Lavanya, Yukti, Varuni                                                                |
| Kannada   | Saanvi, Kavin                                                                                         |
| Malayalam | Reshma, Riyaan                                                                                        |
| Marathi   | Zahira, Ishaan                                                                                        |
| Bengali   | Kirra, Dhruva                                                                                         |
| Gujarati  | Falak, Veera                                                                                          |
| Punjabi   | Mehuli, Zayan                                                                                         |
| Hinglish  | Poorvi                                                                                                |

<Note>
  `timbre-v2.5` requires a `language` parameter (BCP-47 code, e.g. `hi-IN`) when
  using multilingual voices. Some voices (like Pranav, Kaveri, Deepak) appear in
  both models — select the model to pick the voice variant.
</Note>

## Usage

### Streaming with interruption (WebSocket)

```python theme={null}
import os

from pipecat_gnani import GnaniTTSService

tts = GnaniTTSService(
    api_key=os.getenv("GNANI_API_KEY"),
    sample_rate=16000,
    settings=GnaniTTSService.Settings(
        voice="Pranav",
    ),
)

# ... add tts to your pipeline
```

### Using timbre-v2.5 with language

```python theme={null}
import os

from pipecat_gnani import GnaniTTSService

tts = GnaniTTSService(
    api_key=os.getenv("GNANI_API_KEY"),
    sample_rate=16000,
    settings=GnaniTTSService.Settings(
        model="timbre-v2.5",
        voice="Nalini",
        language=Language.HI_IN,
    ),
)

# ... add tts to your pipeline
```

### SSE streaming

```python theme={null}
import os

from pipecat_gnani import GnaniSSETTSService

tts = GnaniSSETTSService(
    api_key=os.getenv("GNANI_API_KEY"),
    aiohttp_session=session,
    settings=GnaniSSETTSService.Settings(
        voice="Pranav",
    ),
)

# ... add tts to your pipeline
```

### REST (non-streaming)

```python theme={null}
import os

from pipecat_gnani import GnaniHttpTTSService

tts = GnaniHttpTTSService(
    api_key=os.getenv("GNANI_API_KEY"),
    aiohttp_session=session,
    settings=GnaniHttpTTSService.Settings(
        voice="Pranav",
    ),
)

# ... add tts to your pipeline
```

### Minimal pipeline example

```python theme={null}
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.transcriptions.language import Language
from pipecat_gnani import GnaniSTTService, GnaniTTSService

stt = GnaniSTTService(
    api_key=os.getenv("GNANI_API_KEY"),
    settings=GnaniSTTService.Settings(language=Language.HI_IN),
)

tts = GnaniTTSService(
    api_key=os.getenv("GNANI_API_KEY"),
    settings=GnaniTTSService.Settings(voice="Pranav"),
)

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        # ... LLM and aggregators
        tts,
        transport.output(),
    ]
)
```

## Compatibility

Tested with the latest **Pipecat** main branch (**v1.5.0+**) using both
`pipecat-gnani`. Requires **`gnani-vachana` >= 0.7.9**. Check the [source
repository](https://github.com/Gnani-AI-Mintlify/pipecat-gnani) for the latest
tested version and changelog.