Feat/updating documentation for Gnani (#6004)

Co-authored-by: Tina Nguyen <72938484+tinalenguyen@users.noreply.github.com>

Author: Gnani-AI-Mintlify

livekit-plugins/livekit-plugins-gnani/README.md

@@ -3,9 +3,9 @@
 [![PyPI](https://img.shields.io/pypi/v/livekit-plugins-gnani)](https://pypi.org/project/livekit-plugins-gnani/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-[LiveKit Agents](https://github.com/livekit/agents) plugin for **[Gnani Vachana](https://gnani.ai/)** — high-accuracy Speech-to-Text and low-latency Text-to-Speech for Indian languages.
+[LiveKit Agents](https://github.com/livekit/agents) plugin for **[Gnani](https://gnani.ai/)** — high-accuracy Speech-to-Text (Prisma) and low-latency Text-to-Speech (Timbre) for Indian languages.
 
-> **Vachana** is a production-ready speech AI platform by [Gnani.ai](https://gnani.ai) supporting 10+ Indian languages with real-time streaming, multilingual transcription, and code-switching capabilities.
+>[Gnani.ai](https://gnani.ai) featuring **Prisma** (STT) and **Timbre** (TTS) models, supporting 10+ Indian languages with real-time streaming, multilingual transcription, and code-switching capabilities.
 
 ## Installation
 
@@ -19,80 +19,147 @@ This will also install the [`websockets`](https://pypi.org/project/websockets/)
 
 You need a Gnani API key. Email **[speechstack@gnani.ai](mailto:speechstack@gnani.ai)** to get started — all new accounts receive free credits, no credit card required.
 
-Set your credentials as environment variables:
+### Authentication
+
+All APIs require a single API key — no `organization_id` or `user_id` needed.
+
+**Option 1 — Environment variable (recommended):**
 
 ```bash
 export GNANI_API_KEY="your-api-key"
+```
+
+**Option 2 — Constructor argument:**
 
-# For REST STT only (optional):
-export GNANI_ORGANIZATION_ID="your-org-id"
-export GNANI_USER_ID="your-user-id"
+```python
+stt = STT(api_key="your-api-key", language="hi-IN")
+tts = TTS(api_key="your-api-key")
 ```
 
+> **Migration note:** If upgrading from an earlier version, remove any `organization_id` and `user_id` parameters — they are no longer accepted.
+
 ## Quick Start
 
-### Speech-to-Text
+### Speech-to-Text (REST + Streaming)
 
 ```python
 from livekit.plugins.gnani import STT
 
 stt = STT(language="hi-IN")
 
-# Use with a LiveKit voice agent pipeline
+# REST STT (file-based transcription)
+speech_event = await stt.recognize(audio_buffer)
+
+# Streaming STT (real-time WebSocket)
+speech_stream = stt.stream()
 ```
 
 ### Text-to-Speech
 
 ```python
 from livekit.plugins.gnani import TTS
 
-# REST (default) — single-request batch synthesis
-tts = TTS(voice="Karan")
+# REST (default) - single-request batch synthesis
+tts_rest = TTS(voice="Karan")
 
-# SSE — streaming via Server-Sent Events (lower latency)
-tts = TTS(voice="Karan", synthesize_method="sse")
+# SSE - chunked synthesis via Server-Sent Events (lower latency)
+tts_sse = TTS(voice="Karan", synthesize_method="sse")
 
-# WebSocket — real-time streaming via stream() (lowest latency)
-tts = TTS(voice="Karan", synthesize_method="websocket")
+# WebSocket - chunked synthesis over WS (lowest latency)
+tts_ws = TTS(voice="Karan", synthesize_method="websocket")
 ```
 
 All three 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.
 
+## Full Constructor Reference
+
+### STT — All parameters
+
+```python
+from livekit.plugins.gnani import STT
+
+stt = STT(
+    language="en-IN",           # Default: "en-IN"
+    sample_rate=16000,          # Default: 16000 (also: 8000)
+    format="verbatim",          # Default: "verbatim" (also: "transcribe")
+    preferred_language=None,    # Default: None
+    itn_native_numerals=False,  # Default: False
+    api_key=None,               # Default: None (reads GNANI_API_KEY env var)
+    base_url="https://api.vachana.ai",  # Default
+)
+```
+
+### TTS — All parameters
+
+```python
+from livekit.plugins.gnani import TTS
+
+tts = TTS(
+    voice="Karan",                    # Default: "Karan" (also: Simran, Nara, Riya, Viraj, Raju)
+    model="vachana-voice-v3",         # Default: "vachana-voice-v3"
+    sample_rate=16000,                # Default: 16000 (also: 8000, 22050, 44100)
+    encoding="linear_pcm",           # Default: "linear_pcm" (also: "oggopus")
+    container="wav",                  # Default: "wav" (also: "raw", "mp3", "mulaw", "ogg")
+    num_channels=1,                   # Default: 1
+    bitrate=None,                     # Default: None (also: "96k", "128k", "192k")
+    synthesize_method="rest",         # Default: "rest" (also: "sse", "websocket")
+    api_key=None,                     # Default: None (reads GNANI_API_KEY env var)
+    base_url="https://api.vachana.ai",  # Default
+)
+```
+
 ## Features
 
-### STT
+### STT (Prisma)
 
-- **Batch recognition** — REST API (`POST /stt/v3`) for file-based transcription
-- **Real-time streaming** — WebSocket API for live audio transcription with VAD
-- **10 Indian languages** — bn-IN, en-IN, gu-IN, hi-IN, kn-IN, ml-IN, mr-IN, pa-IN, ta-IN, te-IN
-- **Code-switching** — Hinglish (en-hi-IN-latn) and Hindi-English mixed (en-hi-in-cm) for streaming
+- **REST recognition** — REST API (`POST /stt/v3`) for file-based transcription
+- **Real-time streaming** — WebSocket API (`wss://api.vachana.ai/stt/v3/stream`) for live audio transcription with VAD
+- **10+ Indian languages** — see [supported language codes](https://docs.gnani.ai/api/STT/stt-websocket#supported-languages)
+- **Code-switching** — supports multilingual and code-mixed audio
 - **Sample rates** — 8 kHz and 16 kHz
+- **ITN support** — Inverse Text Normalization via `format="transcribe"`
+
+#### Streaming PCM Specification
+
+All streaming audio must be sent as **raw PCM binary frames** — no container format (WAV, MP3) mid-stream.
 
-### TTS
+| 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](https://docs.gnani.ai/api/STT/stt-websocket#pcm-specification)** for full details.
+
+### TTS (Timbre)
 
 - **REST synthesis** — single-request batch audio generation (`synthesize_method="rest"`)
 - **SSE streaming** — lower-latency chunked synthesis via Server-Sent Events (`synthesize_method="sse"`)
 - **WebSocket synthesis** — lowest-latency synthesis via `synthesize_method="websocket"` or the `stream()` method
 - **6 voices** — Karan, Simran, Nara, Riya, Viraj, Raju
 - **Configurable output** — sample rate (8000–44100), encoding (linear_pcm, oggopus), container (raw, mp3, wav, mulaw, ogg)
+- **Runtime updates** — change voice or model via `update_options()`
 
 ## Supported Languages
 
-| Language        | Code    |
-|-----------------|---------|
-| Bengali         | `bn-IN` |
-| English (India) | `en-IN` |
-| Gujarati        | `gu-IN` |
-| Hindi           | `hi-IN` |
-| Kannada         | `kn-IN` |
-| Malayalam       | `ml-IN` |
-| Marathi         | `mr-IN` |
-| Punjabi         | `pa-IN` |
-| Tamil           | `ta-IN` |
-| Telugu          | `te-IN` |
+### STT Languages (Prisma)
+
+Prisma uses BCP-47 locale codes (e.g. `hi-IN`). Supported:
+
+- **[STT REST — Supported Languages](https://docs.gnani.ai/api/STT/speech-to-text#supported-languages)**
+- **[STT Realtime — Supported Languages](https://docs.gnani.ai/api/STT/stt-websocket#supported-languages)**
+
+---
+
+### TTS Languages (Timbre)
+
+For the full list of supported languages, see **[TTS — Supported Languages](https://docs.gnani.ai/api/TTS/tts-inference#supported-languages)**.
 
 ## Available Voices
 
@@ -107,12 +174,14 @@ regardless of this setting.
 
 ## Architecture
 
-This plugin directly implements the Gnani Vachana REST and WebSocket APIs using `aiohttp` (for batch STT/TTS) and `websockets` (for streaming STT/TTS), adapting them into LiveKit's `stt.STT` and `tts.TTS` base classes. No external SDK is required — all connection logic, authentication, and audio format handling is self-contained.
+This plugin directly implements the Gnani REST and WebSocket APIs using `aiohttp` (for REST STT/TTS) and `websockets` (for streaming STT/TTS), adapting them into LiveKit's `stt.STT` and `tts.TTS` base classes. It uses the **Prisma** model for speech-to-text and the **Timbre** model for text-to-speech. No external SDK is required — all connection logic, authentication, and audio format handling is self-contained. Authentication uses a single `api_key` passed via the `X-API-Key-ID` header.
 
 ## Documentation
 
-- [Vachana API Docs](https://docs.inya.ai/vachana/introduction/introduction)
+- [Gnani API Docs](https://docs.gnani.ai/)
 - [LiveKit Agents Docs](https://docs.livekit.io/agents/)
+- [Gnani STT Plugin Guide](https://docs.livekit.io/agents/integrations/stt/gnani/)
+- [Gnani TTS Plugin Guide](https://docs.livekit.io/agents/integrations/tts/gnani/)
 
 ## License
 

livekit-plugins/livekit-plugins-gnani/livekit/plugins/gnani/__init__.py

@@ -1,18 +1,32 @@
+# Copyright 2025 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """Gnani Vachana plugin for LiveKit Agents
 
 Support for speech-to-text and text-to-speech with [Gnani's Vachana platform](https://gnani.ai/).
 
 Vachana provides high-accuracy STT and low-latency TTS for Indian languages,
 including multilingual and code-switching scenarios.
 
-For API access, email speechstack@gnani.ai
+See https://docs.livekit.io/agents/integrations/stt/gnani/ for more information.
 """
 
-from .stt import STT
-from .tts import TTS
+from .stt import STT, SpeechStream
+from .tts import TTS, SynthesizeStream
 from .version import __version__
 
-__all__ = ["STT", "TTS", "__version__"]
+__all__ = ["STT", "SpeechStream", "TTS", "SynthesizeStream", "__version__"]
 
 
 from livekit.agents import Plugin

livekit-plugins/livekit-plugins-gnani/livekit/plugins/gnani/log.py

@@ -1,3 +1,17 @@
+# Copyright 2025 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 import logging
 
 logger = logging.getLogger(__name__)