livekit-plugins-gnani 0.1.0__tar.gz

livekit_plugins_gnani-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+.venv/
+venv/
+env/
+
+.env
+.env.*
+*.ini
+*.cfg
+!pyproject.toml
+
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.coverage
+htmlcov/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

livekit_plugins_gnani-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   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.
+
+   Copyright 2025-2026 Gnani.ai

livekit_plugins_gnani-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: livekit-plugins-gnani
+Version: 0.1.0
+Summary: LiveKit Agents plugin for Gnani Vachana speech AI — STT & TTS for Indian languages
+Project-URL: Homepage, https://gnani.ai
+Project-URL: Documentation, https://docs.inya.ai/vachana
+Project-URL: Repository, https://github.com/Gnani-AI-Mintlify/livekit-plugins-gnani
+Project-URL: Issues, https://github.com/Gnani-AI-Mintlify/livekit-plugins-gnani/issues
+Author-email: Genvoice <speechstack@gnani.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: audio,gnani,indian-languages,indic,livekit,livekit-agents,multilingual,realtime,speech-to-text,streaming,stt,text-to-speech,tts,vachana,webrtc,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: gnani-vachana<1.0,>=0.2.2
+Requires-Dist: livekit-agents[codecs]>=1.5.8
+Requires-Dist: websockets<16.0,>=13.1
+Description-Content-Type: text/markdown
+
+# livekit-plugins-gnani
+
+[![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.
+
+> **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.
+
+## Installation
+
+```bash
+pip install livekit-plugins-gnani
+```
+
+This will also install the [`gnani-vachana`](https://pypi.org/project/gnani-vachana/) core SDK as a dependency.
+
+## Prerequisites
+
+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:
+
+```bash
+export GNANI_API_KEY="your-api-key"
+
+# For REST STT only (optional):
+export GNANI_ORGANIZATION_ID="your-org-id"
+export GNANI_USER_ID="your-user-id"
+```
+
+## Quick Start
+
+### Speech-to-Text
+
+```python
+from livekit.plugins.gnani import STT
+
+stt = STT(language="hi-IN")
+
+# Use with a LiveKit voice agent pipeline
+```
+
+### Text-to-Speech
+
+```python
+from livekit.plugins.gnani import TTS
+
+tts = TTS(voice="sia")
+
+# Use with a LiveKit voice agent pipeline
+```
+
+## Features
+
+### STT
+
+- **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
+- **Sample rates** — 8 kHz and 16 kHz
+
+### TTS
+
+- **Chunked synthesis** — REST API for single-request audio generation
+- **Real-time streaming** — WebSocket API for low-latency streaming synthesis
+- **8 voices** — sia, raju, kanika, nikita, ravan, simran, karan, neha
+- **Configurable output** — sample rate (8000–44100), encoding (linear_pcm, oggopus), container (raw, mp3, wav, mulaw, ogg)
+
+## 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` |
+
+## Available Voices
+
+| Voice   | ID        |
+|---------|-----------|
+| Sia     | `sia`     |
+| Raju    | `raju`    |
+| Kanika  | `kanika`  |
+| Nikita  | `nikita`  |
+| Ravan   | `ravan`   |
+| Simran  | `simran`  |
+| Karan   | `karan`   |
+| Neha    | `neha`    |
+
+## Architecture
+
+```
+gnani-vachana           ← Core SDK (REST, WebSocket, SSE clients)
+    ↑
+livekit-plugins-gnani   ← This package (LiveKit Agents adapter)
+```
+
+This plugin is a thin adapter that wraps the `gnani-vachana` SDK into LiveKit's `stt.STT` and `tts.TTS` base classes. All connection logic, authentication, and audio format handling lives in the core SDK.
+
+## Documentation
+
+- [Vachana API Docs](https://docs.inya.ai/vachana/introduction/introduction)
+- [LiveKit Agents Docs](https://docs.livekit.io/agents/)
+- [gnani-vachana SDK](https://pypi.org/project/gnani-vachana/)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

livekit_plugins_gnani-0.1.0/README.md

@@ -0,0 +1,117 @@
+# livekit-plugins-gnani
+
+[![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.
+
+> **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.
+
+## Installation
+
+```bash
+pip install livekit-plugins-gnani
+```
+
+This will also install the [`gnani-vachana`](https://pypi.org/project/gnani-vachana/) core SDK as a dependency.
+
+## Prerequisites
+
+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:
+
+```bash
+export GNANI_API_KEY="your-api-key"
+
+# For REST STT only (optional):
+export GNANI_ORGANIZATION_ID="your-org-id"
+export GNANI_USER_ID="your-user-id"
+```
+
+## Quick Start
+
+### Speech-to-Text
+
+```python
+from livekit.plugins.gnani import STT
+
+stt = STT(language="hi-IN")
+
+# Use with a LiveKit voice agent pipeline
+```
+
+### Text-to-Speech
+
+```python
+from livekit.plugins.gnani import TTS
+
+tts = TTS(voice="sia")
+
+# Use with a LiveKit voice agent pipeline
+```
+
+## Features
+
+### STT
+
+- **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
+- **Sample rates** — 8 kHz and 16 kHz
+
+### TTS
+
+- **Chunked synthesis** — REST API for single-request audio generation
+- **Real-time streaming** — WebSocket API for low-latency streaming synthesis
+- **8 voices** — sia, raju, kanika, nikita, ravan, simran, karan, neha
+- **Configurable output** — sample rate (8000–44100), encoding (linear_pcm, oggopus), container (raw, mp3, wav, mulaw, ogg)
+
+## 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` |
+
+## Available Voices
+
+| Voice   | ID        |
+|---------|-----------|
+| Sia     | `sia`     |
+| Raju    | `raju`    |
+| Kanika  | `kanika`  |
+| Nikita  | `nikita`  |
+| Ravan   | `ravan`   |
+| Simran  | `simran`  |
+| Karan   | `karan`   |
+| Neha    | `neha`    |
+
+## Architecture
+
+```
+gnani-vachana           ← Core SDK (REST, WebSocket, SSE clients)
+    ↑
+livekit-plugins-gnani   ← This package (LiveKit Agents adapter)
+```
+
+This plugin is a thin adapter that wraps the `gnani-vachana` SDK into LiveKit's `stt.STT` and `tts.TTS` base classes. All connection logic, authentication, and audio format handling lives in the core SDK.
+
+## Documentation
+
+- [Vachana API Docs](https://docs.inya.ai/vachana/introduction/introduction)
+- [LiveKit Agents Docs](https://docs.livekit.io/agents/)
+- [gnani-vachana SDK](https://pypi.org/project/gnani-vachana/)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

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

@@ -0,0 +1,36 @@
+"""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
+"""
+
+from .stt import STT
+from .tts import TTS
+from .version import __version__
+
+__all__ = ["STT", "TTS", "__version__"]
+
+
+from livekit.agents import Plugin
+
+from .log import logger
+
+
+class GnaniPlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+
+Plugin.register_plugin(GnaniPlugin())
+
+_module = dir()
+NOT_IN_ALL = [m for m in _module if m not in __all__]
+
+__pdoc__ = {}
+
+for n in NOT_IN_ALL:
+    __pdoc__[n] = False

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

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger(__name__)

livekit_plugins_gnani-0.1.0/livekit/plugins/gnani/stt.py

@@ -0,0 +1,410 @@
+"""Speech-to-Text implementation for Gnani Vachana
+
+This module provides an STT implementation that uses the Gnani Vachana API,
+supporting both batch recognition (REST) and real-time streaming (WebSocket).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from livekit import rtc
+from livekit.agents import (
+    DEFAULT_API_CONNECT_OPTIONS,
+    APIConnectionError,
+    APIConnectOptions,
+    APIStatusError,
+    APITimeoutError,
+    stt,
+    utils,
+)
+from livekit.agents.types import NOT_GIVEN, NotGivenOr
+from livekit.agents.utils import AudioBuffer
+from livekit.agents.utils.misc import is_given
+
+from .log import logger
+
+GNANI_STT_BASE_URL = "https://api.vachana.ai"
+
+GnaniSTTLanguages = Literal[
+    "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN",
+    "ml-IN", "mr-IN", "pa-IN", "ta-IN", "te-IN",
+]
+
+SUPPORTED_LANGUAGES: set[str] = {
+    "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN",
+    "ml-IN", "mr-IN", "pa-IN", "ta-IN", "te-IN",
+}
+
+STREAM_SUPPORTED_LANGUAGES: set[str] = SUPPORTED_LANGUAGES | {
+    "en-hi-IN-latn", "en-hi-in-cm",
+}
+
+SAMPLE_RATE_16K = 16000
+SAMPLE_RATE_8K = 8000
+STREAM_CHUNK_BYTES = 1024
+
+
+@dataclass
+class GnaniSTTOptions:
+    api_key: str
+    language: str
+    sample_rate: int = SAMPLE_RATE_16K
+    base_url: str = GNANI_STT_BASE_URL
+    organization_id: str | None = None
+    user_id: str | None = None
+
+
+class STT(stt.STT):
+    """Gnani Vachana Speech-to-Text implementation.
+
+    Provides speech-to-text functionality using Gnani's Vachana platform.
+    Supports batch recognition via REST API and real-time streaming via WebSocket.
+
+    Args:
+        language: BCP-47 language code (e.g. "hi-IN", "en-IN").
+        api_key: Gnani API key (falls back to GNANI_API_KEY env var).
+        sample_rate: Audio sample rate for streaming (8000 or 16000).
+        base_url: Vachana API base URL.
+        organization_id: Organization ID for REST API (falls back to GNANI_ORGANIZATION_ID).
+        user_id: User ID for REST API (falls back to GNANI_USER_ID).
+    """
+
+    def __init__(
+        self,
+        *,
+        language: str = "en-IN",
+        api_key: str | None = None,
+        sample_rate: int = SAMPLE_RATE_16K,
+        base_url: str = GNANI_STT_BASE_URL,
+        organization_id: str | None = None,
+        user_id: str | None = None,
+        http_session: None = None,
+    ) -> None:
+        super().__init__(
+            capabilities=stt.STTCapabilities(
+                streaming=True,
+                interim_results=False,
+                aligned_transcript=False,
+            )
+        )
+
+        self._api_key = api_key or os.environ.get("GNANI_API_KEY")
+        if not self._api_key:
+            raise ValueError(
+                "Gnani API key is required. "
+                "Provide it directly or set GNANI_API_KEY environment variable."
+            )
+
+        if sample_rate not in (SAMPLE_RATE_8K, SAMPLE_RATE_16K):
+            raise ValueError("sample_rate must be 8000 or 16000")
+
+        self._opts = GnaniSTTOptions(
+            api_key=self._api_key,
+            language=language,
+            sample_rate=sample_rate,
+            base_url=base_url,
+            organization_id=organization_id or os.environ.get("GNANI_ORGANIZATION_ID"),
+            user_id=user_id or os.environ.get("GNANI_USER_ID"),
+        )
+        self._session: utils.aiohttp.ClientSession | None = None
+
+    @property
+    def model(self) -> str:
+        return "vachana-stt-v3"
+
+    @property
+    def provider(self) -> str:
+        return "Gnani"
+
+    def _ensure_session(self) -> utils.aiohttp.ClientSession:
+        if not self._session:
+            self._session = utils.http_context.http_session()
+        return self._session
+
+    @staticmethod
+    def _single_attempt(conn_options: APIConnectOptions) -> APIConnectOptions:
+        return APIConnectOptions(
+            max_retry=0,
+            retry_interval=conn_options.retry_interval,
+            timeout=conn_options.timeout,
+        )
+
+    async def recognize(
+        self,
+        buffer: AudioBuffer,
+        *,
+        language: NotGivenOr[str] = NOT_GIVEN,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+    ) -> stt.SpeechEvent:
+        return await super().recognize(
+            buffer,
+            language=language,
+            conn_options=self._single_attempt(conn_options),
+        )
+
+    async def _recognize_impl(
+        self,
+        buffer: AudioBuffer,
+        *,
+        language: NotGivenOr[str] = NOT_GIVEN,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+    ) -> stt.SpeechEvent:
+        import aiohttp
+
+        lang = language if is_given(language) else self._opts.language
+
+        wav_bytes = rtc.combine_audio_frames(buffer).to_wav_bytes()
+
+        form_data = aiohttp.FormData()
+        form_data.add_field(
+            "audio_file", wav_bytes, filename="audio.wav", content_type="audio/wav"
+        )
+        form_data.add_field("language_code", lang)
+
+        headers: dict[str, str] = {
+            "X-API-Key-ID": self._opts.api_key,
+        }
+        if self._opts.organization_id:
+            headers["X-Organization-ID"] = self._opts.organization_id
+        if self._opts.user_id:
+            headers["X-API-User-ID"] = self._opts.user_id
+
+        try:
+            async with self._ensure_session().post(
+                url=f"{self._opts.base_url}/stt/v3",
+                data=form_data,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(
+                    total=conn_options.timeout,
+                    sock_connect=conn_options.timeout,
+                ),
+            ) as res:
+                if res.status != 200:
+                    error_text = await res.text()
+                    logger.error(f"Gnani STT API error: {res.status} - {error_text}")
+                    raise APIStatusError(
+                        message=f"Gnani STT API Error ({res.status}): {error_text}",
+                        status_code=res.status,
+                        body=error_text,
+                    )
+
+                response_json = await res.json()
+                transcript = response_json.get("transcript", "")
+                request_id = response_json.get("request_id", "")
+
+                return stt.SpeechEvent(
+                    type=stt.SpeechEventType.FINAL_TRANSCRIPT,
+                    request_id=request_id,
+                    alternatives=[
+                        stt.SpeechData(
+                            language=lang,
+                            text=transcript,
+                            confidence=1.0,
+                        )
+                    ],
+                )
+
+        except asyncio.TimeoutError as e:
+            raise APITimeoutError("Gnani STT API request timed out") from e
+        except (APIStatusError, APIConnectionError, APITimeoutError):
+            raise
+        except Exception as e:
+            raise APIConnectionError(f"Gnani STT error: {e}") from e
+
+    def stream(
+        self,
+        *,
+        language: NotGivenOr[str] = NOT_GIVEN,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+    ) -> SpeechStream:
+        lang = language if is_given(language) else self._opts.language
+        return SpeechStream(
+            stt=self,
+            opts=GnaniSTTOptions(
+                api_key=self._opts.api_key,
+                language=lang,
+                sample_rate=self._opts.sample_rate,
+                base_url=self._opts.base_url,
+                organization_id=self._opts.organization_id,
+                user_id=self._opts.user_id,
+            ),
+            conn_options=self._single_attempt(conn_options),
+        )
+
+    async def aclose(self) -> None:
+        pass
+
+
+class SpeechStream(stt.RecognizeStream):
+    """WebSocket-based streaming STT for Gnani Vachana.
+
+    Connects to wss://api.vachana.ai/stt/v3/stream and sends raw PCM audio
+    in 1024-byte chunks (512 samples, 16-bit mono).
+    """
+
+    def __init__(
+        self,
+        *,
+        stt: STT,
+        opts: GnaniSTTOptions,
+        conn_options: APIConnectOptions,
+    ) -> None:
+        super().__init__(
+            stt=stt,
+            conn_options=conn_options,
+            sample_rate=opts.sample_rate,
+        )
+        self._opts = opts
+
+    def _build_ws_url(self) -> str:
+        base = self._opts.base_url
+        if base.startswith("https://"):
+            ws_base = "wss://" + base[len("https://"):]
+        elif base.startswith("http://"):
+            ws_base = "ws://" + base[len("http://"):]
+        else:
+            ws_base = "wss://" + base
+        return f"{ws_base}/stt/v3/stream"
+
+    async def _run(self) -> None:
+        import websockets
+
+        ws_url = self._build_ws_url()
+        headers = {
+            "x-api-key-id": self._opts.api_key,
+            "lang_code": self._opts.language,
+        }
+
+        try:
+            async with websockets.connect(
+                ws_url,
+                additional_headers=headers,
+                ping_interval=20,
+                ping_timeout=20,
+                close_timeout=10,
+            ) as ws:
+                connected_msg = await asyncio.wait_for(ws.recv(), timeout=10)
+                connected_data = json.loads(connected_msg)
+                if connected_data.get("type") != "connected":
+                    logger.warning(
+                        f"Unexpected first message from Gnani STT: {connected_data}"
+                    )
+
+                send_task = asyncio.create_task(
+                    self._send_audio(ws), name="gnani-stt-send"
+                )
+                recv_task = asyncio.create_task(
+                    self._recv_messages(ws), name="gnani-stt-recv"
+                )
+
+                try:
+                    await asyncio.gather(send_task, recv_task)
+                finally:
+                    send_task.cancel()
+                    recv_task.cancel()
+                    with utils.aio.suppress(asyncio.CancelledError):
+                        await send_task
+                    with utils.aio.suppress(asyncio.CancelledError):
+                        await recv_task
+
+        except websockets.exceptions.ConnectionClosed as e:
+            raise APIConnectionError(
+                f"Gnani STT WebSocket closed unexpectedly: {e}"
+            ) from e
+        except asyncio.TimeoutError as e:
+            raise APITimeoutError("Gnani STT WebSocket connection timed out") from e
+        except (APIConnectionError, APIStatusError, APITimeoutError):
+            raise
+        except Exception as e:
+            raise APIConnectionError(f"Gnani STT WebSocket error: {e}") from e
+
+    async def _send_audio(self, ws) -> None:
+        audio_buffer = bytearray()
+
+        async for data in self._input_ch:
+            if isinstance(data, self._FlushSentinel):
+                if audio_buffer:
+                    await ws.send(bytes(audio_buffer))
+                    audio_buffer.clear()
+                continue
+
+            frame: rtc.AudioFrame = data
+            raw_pcm = frame.data.tobytes()
+            audio_buffer.extend(raw_pcm)
+
+            while len(audio_buffer) >= STREAM_CHUNK_BYTES:
+                chunk = bytes(audio_buffer[:STREAM_CHUNK_BYTES])
+                audio_buffer = audio_buffer[STREAM_CHUNK_BYTES:]
+                await ws.send(chunk)
+
+        if audio_buffer:
+            await ws.send(bytes(audio_buffer))
+
+        await ws.close()
+
+    async def _recv_messages(self, ws) -> None:
+        try:
+            async for msg in ws:
+                if isinstance(msg, bytes):
+                    continue
+
+                data = json.loads(msg)
+                msg_type = data.get("type", "")
+
+                if msg_type == "transcript":
+                    text = data.get("text", "")
+                    if not text:
+                        continue
+
+                    self._event_ch.send_nowait(
+                        stt.SpeechEvent(
+                            type=stt.SpeechEventType.FINAL_TRANSCRIPT,
+                            alternatives=[
+                                stt.SpeechData(
+                                    language=self._opts.language,
+                                    text=text,
+                                    confidence=1.0,
+                                )
+                            ],
+                        )
+                    )
+
+                elif msg_type in ("speech_start", "vad_start"):
+                    self._event_ch.send_nowait(
+                        stt.SpeechEvent(
+                            type=stt.SpeechEventType.START_OF_SPEECH,
+                        )
+                    )
+
+                elif msg_type in ("speech_end", "vad_end"):
+                    self._event_ch.send_nowait(
+                        stt.SpeechEvent(
+                            type=stt.SpeechEventType.END_OF_SPEECH,
+                        )
+                    )
+
+                elif msg_type == "processing":
+                    pass
+
+                elif msg_type == "error":
+                    error_msg = data.get("message", "Unknown error")
+                    logger.error(f"Gnani STT stream error: {error_msg}")
+                    raise APIStatusError(
+                        message=f"Gnani STT stream error: {error_msg}",
+                        status_code=500,
+                        body=error_msg,
+                    )
+
+        except asyncio.CancelledError:
+            raise
+        except (APIStatusError, APIConnectionError):
+            raise
+        except Exception as e:
+            raise APIConnectionError(
+                f"Error receiving Gnani STT messages: {e}"
+            ) from e

livekit_plugins_gnani-0.1.0/livekit/plugins/gnani/tts.py

@@ -0,0 +1,376 @@
+"""Text-to-Speech implementation for Gnani Vachana
+
+This module provides a TTS implementation that uses the Gnani Vachana API,
+supporting both chunked synthesis (REST) and real-time streaming (WebSocket).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import os
+from dataclasses import dataclass, replace
+from typing import Literal
+
+from livekit.agents import (
+    DEFAULT_API_CONNECT_OPTIONS,
+    APIConnectionError,
+    APIConnectOptions,
+    APIStatusError,
+    APITimeoutError,
+    tokenize,
+    tts,
+    utils,
+)
+
+from .log import logger
+
+GNANI_TTS_BASE_URL = "https://api.vachana.ai"
+
+GnaniTTSVoices = Literal[
+    "sia", "raju", "kanika", "nikita", "ravan", "simran", "karan", "neha",
+]
+
+SUPPORTED_VOICES: set[str] = {
+    "sia", "raju", "kanika", "nikita", "ravan", "simran", "karan", "neha",
+}
+
+GnaniTTSEncodings = Literal["linear_pcm", "oggopus"]
+GnaniTTSContainers = Literal["raw", "mp3", "wav", "mulaw", "ogg"]
+
+
+@dataclass
+class GnaniTTSOptions:
+    api_key: str
+    voice: str = "sia"
+    model: str = "vachana-voice-v2"
+    sample_rate: int = 24000
+    encoding: str = "linear_pcm"
+    container: str = "wav"
+    num_channels: int = 1
+    sample_width: int = 2
+    base_url: str = GNANI_TTS_BASE_URL
+    language: str = "IND-IN"
+
+
+class TTS(tts.TTS):
+    """Gnani Vachana Text-to-Speech implementation.
+
+    Provides text-to-speech functionality using Gnani's Vachana platform.
+    Supports batch synthesis via REST API and real-time streaming via WebSocket.
+
+    Args:
+        voice: Voice to use for synthesis (sia, raju, kanika, etc.).
+        model: TTS model name (default: vachana-voice-v2).
+        sample_rate: Audio output sample rate (8000-44100).
+        encoding: Audio encoding (linear_pcm or oggopus).
+        container: Audio container format (raw, mp3, wav, mulaw, ogg).
+        api_key: Gnani API key (falls back to GNANI_API_KEY env var).
+        base_url: Vachana API base URL.
+        language: Language code for WebSocket TTS (default: IND-IN).
+    """
+
+    def __init__(
+        self,
+        *,
+        voice: GnaniTTSVoices | str = "sia",
+        model: str = "vachana-voice-v2",
+        sample_rate: int = 24000,
+        num_channels: int = 1,
+        encoding: GnaniTTSEncodings | str = "linear_pcm",
+        container: GnaniTTSContainers | str = "wav",
+        api_key: str | None = None,
+        base_url: str = GNANI_TTS_BASE_URL,
+        language: str = "IND-IN",
+    ) -> None:
+        super().__init__(
+            capabilities=tts.TTSCapabilities(streaming=True),
+            sample_rate=sample_rate,
+            num_channels=num_channels,
+        )
+
+        self._api_key = api_key or os.environ.get("GNANI_API_KEY")
+        if not self._api_key:
+            raise ValueError(
+                "Gnani API key is required. "
+                "Provide it directly or set GNANI_API_KEY environment variable."
+            )
+
+        if voice not in SUPPORTED_VOICES:
+            raise ValueError(
+                f"Voice '{voice}' not supported. Choose from: {sorted(SUPPORTED_VOICES)}"
+            )
+
+        self._opts = GnaniTTSOptions(
+            api_key=self._api_key,
+            voice=voice,
+            model=model,
+            sample_rate=sample_rate,
+            encoding=encoding,
+            container=container,
+            num_channels=num_channels,
+            base_url=base_url,
+            language=language,
+        )
+        self._session = None
+
+    @property
+    def model(self) -> str:
+        return self._opts.model
+
+    @property
+    def provider(self) -> str:
+        return "Gnani"
+
+    def _ensure_session(self):
+        if not self._session:
+            self._session = utils.http_context.http_session()
+        return self._session
+
+    def synthesize(
+        self, text: str, *, conn_options: APIConnectOptions | None = None
+    ) -> ChunkedStream:
+        if conn_options is None:
+            conn_options = DEFAULT_API_CONNECT_OPTIONS
+        return ChunkedStream(tts=self, input_text=text, conn_options=conn_options)
+
+    def stream(
+        self, *, conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS
+    ) -> SynthesizeStream:
+        return SynthesizeStream(tts=self, conn_options=conn_options)
+
+    def update_options(
+        self,
+        *,
+        voice: str | None = None,
+        model: str | None = None,
+        language: str | None = None,
+    ) -> None:
+        if voice is not None:
+            if voice not in SUPPORTED_VOICES:
+                raise ValueError(
+                    f"Voice '{voice}' not supported. Choose from: {sorted(SUPPORTED_VOICES)}"
+                )
+            self._opts.voice = voice
+        if model is not None:
+            self._opts.model = model
+        if language is not None:
+            self._opts.language = language
+
+    async def aclose(self) -> None:
+        pass
+
+
+class ChunkedStream(tts.ChunkedStream):
+    """REST-based chunked TTS for Gnani Vachana.
+
+    Uses POST /api/v1/tts/inference to synthesize text in a single request.
+    """
+
+    def __init__(
+        self, *, tts: TTS, input_text: str, conn_options: APIConnectOptions
+    ) -> None:
+        super().__init__(tts=tts, input_text=input_text, conn_options=conn_options)
+        self._tts: TTS = tts
+        self._opts = replace(tts._opts)
+
+    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
+        import aiohttp
+
+        payload = {
+            "text": self._input_text,
+            "voice": self._opts.voice,
+            "model": self._opts.model,
+            "audio_config": {
+                "sample_rate": self._opts.sample_rate,
+                "encoding": self._opts.encoding,
+                "num_channels": self._opts.num_channels,
+                "sample_width": self._opts.sample_width,
+                "container": self._opts.container,
+            },
+        }
+
+        headers = {
+            "X-API-Key-ID": self._opts.api_key,
+            "Content-Type": "application/json",
+        }
+
+        mime_type = f"audio/{self._opts.container}"
+        if self._opts.container == "raw":
+            mime_type = "audio/pcm"
+
+        try:
+            async with self._tts._ensure_session().post(
+                url=f"{self._opts.base_url}/api/v1/tts/inference",
+                json=payload,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(
+                    total=self._conn_options.timeout,
+                    sock_connect=self._conn_options.timeout,
+                ),
+            ) as res:
+                if res.status != 200:
+                    error_text = await res.text()
+                    logger.error(f"Gnani TTS API error: {res.status} - {error_text}")
+                    raise APIStatusError(
+                        message=f"Gnani TTS API Error ({res.status}): {error_text}",
+                        status_code=res.status,
+                        body=error_text,
+                    )
+
+                audio_bytes = await res.read()
+
+                output_emitter.initialize(
+                    request_id="gnani-tts",
+                    sample_rate=self._tts.sample_rate,
+                    num_channels=self._tts.num_channels,
+                    mime_type=mime_type,
+                )
+                output_emitter.push(audio_bytes)
+
+        except asyncio.TimeoutError as e:
+            raise APITimeoutError("Gnani TTS API request timed out") from e
+        except (APIStatusError, APIConnectionError, APITimeoutError):
+            raise
+        except Exception as e:
+            raise APIConnectionError(f"Gnani TTS error: {e}") from e
+
+
+class SynthesizeStream(tts.SynthesizeStream):
+    """WebSocket-based streaming TTS for Gnani Vachana.
+
+    Opens a WebSocket to wss://api.vachana.ai/api/v1/tts and streams
+    audio chunks back as they are synthesized.
+    """
+
+    def __init__(self, *, tts: TTS, conn_options: APIConnectOptions):
+        super().__init__(tts=tts, conn_options=conn_options)
+        self._tts: TTS = tts
+        self._opts = replace(tts._opts)
+
+    def _build_ws_url(self) -> str:
+        base = self._opts.base_url
+        if base.startswith("https://"):
+            ws_base = "wss://" + base[len("https://"):]
+        elif base.startswith("http://"):
+            ws_base = "ws://" + base[len("http://"):]
+        else:
+            ws_base = "wss://" + base
+        return f"{ws_base}/api/v1/tts"
+
+    async def _run(self, output_emitter: tts.AudioEmitter) -> None:
+        import websockets
+
+        token_buf = ""
+        word_stream = tokenize.basic.SentenceTokenizer().stream()
+        _flushing = False
+
+        async def _input_task():
+            nonlocal _flushing
+            async for data in self._input:
+                if isinstance(data, str):
+                    word_stream.push_text(data)
+                elif isinstance(data, self._FlushSentinel):
+                    word_stream.flush()
+                    _flushing = True
+            word_stream.end_input()
+
+        input_task = asyncio.create_task(_input_task(), name="gnani-tts-input")
+
+        try:
+            async for ev in word_stream:
+                text = ev.token
+                if not text.strip():
+                    continue
+                await self._synthesize_segment(text, output_emitter)
+        finally:
+            input_task.cancel()
+            with utils.aio.suppress(asyncio.CancelledError):
+                await input_task
+
+    async def _synthesize_segment(
+        self, text: str, output_emitter: tts.AudioEmitter
+    ) -> None:
+        import websockets
+
+        ws_url = self._build_ws_url()
+        headers = {
+            "Content-Type": "application/json",
+            "X-API-Key-ID": self._opts.api_key,
+        }
+
+        mime_type = f"audio/{self._opts.container}"
+        if self._opts.container == "raw":
+            mime_type = "audio/pcm"
+
+        output_emitter.initialize(
+            request_id="gnani-tts-stream",
+            sample_rate=self._tts.sample_rate,
+            num_channels=self._tts.num_channels,
+            mime_type=mime_type,
+        )
+
+        try:
+            async with websockets.connect(
+                ws_url,
+                additional_headers=headers,
+                ping_interval=20,
+                ping_timeout=20,
+                close_timeout=10,
+            ) as ws:
+                request_body = {
+                    "text": text,
+                    "voice": self._opts.voice,
+                    "model": self._opts.model,
+                    "language": self._opts.language,
+                    "audio_config": {
+                        "sample_rate": self._opts.sample_rate,
+                        "encoding": self._opts.encoding,
+                        "num_channels": self._opts.num_channels,
+                        "sample_width": self._opts.sample_width,
+                        "container": self._opts.container,
+                    },
+                }
+                await ws.send(json.dumps(request_body))
+
+                async for msg in ws:
+                    if isinstance(msg, bytes):
+                        output_emitter.push(msg)
+                        continue
+
+                    data = json.loads(msg)
+                    msg_type = data.get("type", "")
+
+                    if msg_type == "audio":
+                        audio_b64 = data.get("audio", "")
+                        if audio_b64:
+                            output_emitter.push(base64.b64decode(audio_b64))
+
+                    elif msg_type == "complete":
+                        audio_b64 = data.get("audio", "")
+                        if audio_b64:
+                            output_emitter.push(base64.b64decode(audio_b64))
+                        break
+
+                    elif msg_type == "error":
+                        error_msg = data.get("message", "Unknown error")
+                        logger.error(f"Gnani TTS stream error: {error_msg}")
+                        raise APIStatusError(
+                            message=f"Gnani TTS stream error: {error_msg}",
+                            status_code=500,
+                            body=error_msg,
+                        )
+
+        except websockets.exceptions.ConnectionClosed as e:
+            raise APIConnectionError(
+                f"Gnani TTS WebSocket closed: {e}"
+            ) from e
+        except asyncio.TimeoutError as e:
+            raise APITimeoutError(
+                "Gnani TTS WebSocket timed out"
+            ) from e
+        except (APIStatusError, APIConnectionError, APITimeoutError):
+            raise
+        except Exception as e:
+            raise APIConnectionError(f"Gnani TTS WebSocket error: {e}") from e

livekit_plugins_gnani-0.1.0/livekit/plugins/gnani/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

livekit_plugins_gnani-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "livekit-plugins-gnani"
+version = "0.1.0"
+description = "LiveKit Agents plugin for Gnani Vachana speech AI — STT & TTS for Indian languages"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Genvoice", email = "speechstack@gnani.ai" },
+]
+keywords = [
+    "webrtc", "realtime", "audio", "livekit", "livekit-agents",
+    "gnani", "vachana", "indian-languages", "indic",
+    "stt", "tts", "speech-to-text", "text-to-speech",
+    "multilingual", "streaming", "websocket",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "livekit-agents[codecs]>=1.5.8",
+    "gnani-vachana>=0.2.2,<1.0",
+    "websockets>=13.1,<16.0",
+]
+
+[project.urls]
+Homepage = "https://gnani.ai"
+Documentation = "https://docs.inya.ai/vachana"
+Repository = "https://github.com/Gnani-AI-Mintlify/livekit-plugins-gnani"
+Issues = "https://github.com/Gnani-AI-Mintlify/livekit-plugins-gnani/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["livekit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/livekit"]
+
+# ---------------------------------------------------------------------------
+# Ruff
+# ---------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "TCH", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["livekit"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# ---------------------------------------------------------------------------
+# Mypy
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true