> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-ws-body-url-encode.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gnani Text-to-Speech

> TTS for 10+ Indian languages with GnaniTTSService (WebSocket), GnaniSSETTSService (SSE), and GnaniHttpTTSService (REST).

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](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 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 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 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 the pipeline configuration.
</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.