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

# Text-to-Speech (Realtime)

> Real-time text-to-speech with streaming audio via WebSocket.

<Info>
  **Currently in beta.** You're on the priority waitlist and among the first to get access.
</Info>

## Overview

Stream audio in real-time with the lowest latency. Perfect for interactive assistants and live applications. For simpler use cases, see [TTS REST](/vachana/TTS/tts-inference) or [TTS SSE](/vachana/TTS/tts-sse).

<Note>
  Passing numbers, IDs, dates, or currency as raw strings causes mispronunciations. See the [Input Formatting Guide](/vachana/TTS/tts-input-formating) for correct formatting of phone numbers, account numbers, PINs, Aadhaar, vehicle registration numbers, GSTIN, currency, and more.
</Note>

## Available Voices

| Voice   | Gender | Description              |
| :------ | :----- | :----------------------- |
| Pranav  | Male   | Bold, Trustworthy        |
| Kaveri  | Female | Confident, Bright        |
| Shubhra | Female | Gentle, Expressive       |
| Deepak  | Male   | Grounded, Conversational |

## Endpoint

```text theme={null}
wss://api.vachana.ai/api/v1/tts
```

## Authentication

All Realtime connections require the following headers:

| Header         | Required | Description                     | Example             |
| -------------- | -------- | ------------------------------- | ------------------- |
| `Content-Type` | Yes      | Must be `application/json`      | `application/json`  |
| `X-API-Key-ID` | Yes      | Your API key for authentication | `<your-api-key-id>` |

## Request Format

Send a JSON message with the following structure:

```json theme={null}
{
  "text": "नमस्ते, आप कैसे हैं?",
  "model": "vachana-voice-v3",
  "audio_config": {
    "sample_rate": 44100,
    "encoding": "linear_pcm"
  }
}
```

<ParamField body="num_channels" type="integer" required>
  Number of audio channels (e.g., `1` for mono, `2` for stereo)
</ParamField>

<ParamField body="sample_width" type="integer" required>
  Sample width in bytes (e.g., `2` for 16-bit audio)
</ParamField>

<ParamField body="encoding" type="string" required>
  Audio encoding format (e.g., `linear_pcm`)
</ParamField>

<ParamField body="container" type="string" required>
  Audio container format (e.g., `wav`)
</ParamField>

## Response

The server streams audio data in real-time as binary chunks. Each chunk contains PCM audio data according to the specified `audio_config`.

## Example Usage

<CodeGroup>
  ```javascript JavaScript theme={null}
  const ws = new WebSocket("wss://api.vachana.ai/api/v1/tts", {
    headers: {
      "Content-Type": "application/json",
      "X-API-Key-ID": "<your-api-key>",
    },
  });

  ws.on("open", () => {
    const request = {
      text: "नमस्ते, आप कैसे हैं?",
      model: "vachana-voice-v3",
      audio_config: {
        sample_rate: 44100,
        encoding: "linear_pcm",
      },
    };

    ws.send(JSON.stringify(request));
  });

  ws.on("message", (data) => {
    // Handle audio chunks
    console.log("Received audio chunk:", data);
  });

  ws.on("error", (error) => {
    console.error("WebSocket error:", error);
  });

  ws.on("close", () => {
    console.log("WebSocket connection closed");
  });
  ```

  ```python Python theme={null}
  import websocket
  import json

  def on_message(ws, message):
      # Handle audio chunks
      print(f"Received audio chunk: {len(message)} bytes")

  def on_error(ws, error):
      print(f"Error: {error}")

  def on_close(ws, close_status_code, close_msg):
      print("WebSocket connection closed")

  def on_open(ws):
      request = {
          "text": "नमस्ते, आप कैसे हैं?",
          "model": "vachana-voice-v3",
          "audio_config": {
              "sample_rate": 44100,
              "encoding": "linear_pcm"
          }
      }
      ws.send(json.dumps(request))

  ws = websocket.WebSocketApp(
      "wss://api.vachana.ai/api/v1/tts",
      header={
          "Content-Type": "application/json",
          "X-API-Key-ID": "<your-api-key>"
      },
      on_open=on_open,
      on_message=on_message,
      on_error=on_error,
      on_close=on_close
  )

  ws.run_forever()
  ```
</CodeGroup>

***

## Python SDK

The SDK's realtime client manages the WebSocket lifecycle, audio streaming, and async iteration so you can focus on your application logic.

### Installation

```bash theme={null}
pip install gnani-vachana
```

Requires **Python 3.9+**.

### Authentication

<CodeGroup>
  ```python Constructor argument theme={null}
  from gnani.tts import GnaniTTSRealtimeClient

  client = GnaniTTSRealtimeClient(api_key="your-api-key")
  ```

  ```bash Environment variable theme={null}
  export GNANI_API_KEY="your-api-key"
  ```

  ```python Environment variable (usage) theme={null}
  from gnani.tts import GnaniTTSRealtimeClient

  client = GnaniTTSRealtimeClient()
  ```
</CodeGroup>

### Stream Audio Chunks in Real-Time

Use the async context manager to open the connection and iterate over audio chunks as they arrive.

```python theme={null}
import asyncio
from gnani.tts import GnaniTTSRealtimeClient

async def main():
    async with GnaniTTSRealtimeClient(api_key="your-api-key") as client:
        with open("output.wav", "wb") as f:
            async for chunk in client.synthesize(
                "नमस्ते, आप कैसे हैं?",
                voice="sia",
            ):
                f.write(chunk)

asyncio.run(main())
```

### Collect All Audio at Once

If you don't need to process chunks as they arrive, use `synthesize_and_collect` to get the full audio as a single bytes object.

```python theme={null}
import asyncio
from gnani.tts import GnaniTTSRealtimeClient

async def main():
    async with GnaniTTSRealtimeClient(api_key="your-api-key") as client:
        audio = await client.synthesize_and_collect(
            "Realtime TTS response",
            voice="neha",
        )
        with open("output.wav", "wb") as f:
            f.write(audio)

asyncio.run(main())
```

## Supported Languages

The Gnani Timbre v2.0 API supports 2 languages.

| Language | Native Script       | Example                    |
| -------- | ------------------- | -------------------------- |
| English  | Latin               | "I am going to the market" |
| Hindi    | Devanagari (हिन्दी) | "मैं बाज़ार जा रहा हूँ"    |