pipecat-gnani 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,36 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.so
5
+
6
+ *.egg-info/
7
+ dist/
8
+ build/
9
+ .eggs/
10
+ *.egg
11
+
12
+ .venv/
13
+ venv/
14
+ env/
15
+
16
+ .env
17
+ .env.*
18
+ *.ini
19
+ *.cfg
20
+ !pyproject.toml
21
+
22
+ *.log
23
+ .mypy_cache/
24
+ .pytest_cache/
25
+ .ruff_cache/
26
+ .tox/
27
+ .coverage
28
+ htmlcov/
29
+
30
+ .idea/
31
+ .vscode/
32
+ *.swp
33
+ *.swo
34
+ *~
35
+ .DS_Store
36
+ Thumbs.db
@@ -0,0 +1,24 @@
1
+ BSD 2-Clause License
2
+
3
+ Copyright (c) 2025-2026 Gnani.ai
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
19
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
21
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
22
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,176 @@
1
+ Metadata-Version: 2.4
2
+ Name: pipecat-gnani
3
+ Version: 0.1.0
4
+ Summary: Pipecat service integration for Gnani Vachana speech AI — STT & TTS for Indian languages
5
+ Project-URL: Homepage, https://gnani.ai
6
+ Project-URL: Documentation, https://docs.inya.ai/vachana
7
+ Project-URL: Repository, https://github.com/Gnani-AI-Mintlify/pipecat-gnani
8
+ Project-URL: Issues, https://github.com/Gnani-AI-Mintlify/pipecat-gnani/issues
9
+ Author-email: Genvoice <speechstack@gnani.ai>
10
+ License-Expression: BSD-2-Clause
11
+ License-File: LICENSE
12
+ Keywords: conversational-ai,gnani,indian-languages,indic,multilingual,pipecat,pipecat-ai,speech-to-text,streaming,stt,text-to-speech,tts,vachana,voice-agent,websocket
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: BSD License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Multimedia :: Sound/Audio
24
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
25
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: aiohttp>=3.9.0
28
+ Requires-Dist: gnani-vachana<1.0,>=0.2.2
29
+ Requires-Dist: pipecat-ai>=0.0.50
30
+ Requires-Dist: websockets<16.0,>=13.1
31
+ Description-Content-Type: text/markdown
32
+
33
+ # pipecat-gnani
34
+
35
+ [![PyPI](https://img.shields.io/pypi/v/pipecat-gnani)](https://pypi.org/project/pipecat-gnani/)
36
+ [![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](LICENSE)
37
+
38
+ [Pipecat](https://github.com/pipecat-ai/pipecat) service integration for **[Gnani Vachana](https://gnani.ai/)** — high-accuracy Speech-to-Text and low-latency Text-to-Speech for Indian languages.
39
+
40
+ > **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.
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ pip install pipecat-gnani
46
+ ```
47
+
48
+ This will also install the [`gnani-vachana`](https://pypi.org/project/gnani-vachana/) core SDK as a dependency.
49
+
50
+ ## Prerequisites
51
+
52
+ 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.
53
+
54
+ ```bash
55
+ export GNANI_API_KEY="your-api-key"
56
+ ```
57
+
58
+ ## Quick Start
59
+
60
+ ### Speech-to-Text (Streaming)
61
+
62
+ ```python
63
+ from pipecat_gnani import GnaniSTTService
64
+
65
+ stt = GnaniSTTService(
66
+ api_key="your-api-key",
67
+ settings=GnaniSTTService.Settings(
68
+ language=Language.HI_IN,
69
+ ),
70
+ )
71
+ ```
72
+
73
+ ### Text-to-Speech (REST)
74
+
75
+ ```python
76
+ from pipecat_gnani import GnaniHttpTTSService
77
+
78
+ tts = GnaniHttpTTSService(
79
+ api_key="your-api-key",
80
+ aiohttp_session=session,
81
+ settings=GnaniHttpTTSService.Settings(
82
+ voice="sia",
83
+ language="hi-IN",
84
+ ),
85
+ )
86
+ ```
87
+
88
+ ### Text-to-Speech (Streaming WebSocket)
89
+
90
+ ```python
91
+ from pipecat_gnani import GnaniTTSService
92
+
93
+ tts = GnaniTTSService(
94
+ api_key="your-api-key",
95
+ settings=GnaniTTSService.Settings(
96
+ voice="sia",
97
+ language="IND-IN",
98
+ ),
99
+ )
100
+ ```
101
+
102
+ ## Services
103
+
104
+ ### GnaniSTTService
105
+
106
+ Real-time streaming speech-to-text via WebSocket with VAD (Voice Activity Detection) support.
107
+
108
+ - Connects to `wss://api.vachana.ai/stt/v3/stream`
109
+ - Sends raw PCM audio in 1024-byte chunks
110
+ - Receives transcription events with segment metadata
111
+ - Supports 8 kHz and 16 kHz sample rates
112
+
113
+ ### GnaniHttpTTSService
114
+
115
+ REST-based text-to-speech for non-streaming use cases.
116
+
117
+ - Uses `POST /api/v1/tts/inference`
118
+ - Returns complete audio in a single response
119
+ - Suitable for batch synthesis
120
+
121
+ ### GnaniTTSService
122
+
123
+ WebSocket-based streaming text-to-speech with interruption handling.
124
+
125
+ - Connects to `wss://api.vachana.ai/api/v1/tts`
126
+ - Streams audio chunks in real-time
127
+ - Extends `InterruptibleTTSService` for proper interruption support
128
+ - Ideal for conversational voice agents
129
+
130
+ ## Supported Languages
131
+
132
+ | Language | Code |
133
+ |-----------------|---------|
134
+ | Bengali | `bn-IN` |
135
+ | English (India) | `en-IN` |
136
+ | Gujarati | `gu-IN` |
137
+ | Hindi | `hi-IN` |
138
+ | Kannada | `kn-IN` |
139
+ | Malayalam | `ml-IN` |
140
+ | Marathi | `mr-IN` |
141
+ | Punjabi | `pa-IN` |
142
+ | Tamil | `ta-IN` |
143
+ | Telugu | `te-IN` |
144
+
145
+ ## Available Voices
146
+
147
+ | Voice | ID |
148
+ |---------|-----------|
149
+ | Sia | `sia` |
150
+ | Raju | `raju` |
151
+ | Kanika | `kanika` |
152
+ | Nikita | `nikita` |
153
+ | Ravan | `ravan` |
154
+ | Simran | `simran` |
155
+ | Karan | `karan` |
156
+ | Neha | `neha` |
157
+
158
+ ## Architecture
159
+
160
+ ```
161
+ gnani-vachana ← Core SDK (REST, WebSocket, SSE clients)
162
+ ↑
163
+ pipecat-gnani ← This package (Pipecat service adapter)
164
+ ```
165
+
166
+ This package is a thin adapter that wraps the `gnani-vachana` SDK into Pipecat's `STTService`, `TTSService`, and `InterruptibleTTSService` base classes. All connection logic, authentication, and audio format handling lives in the core SDK.
167
+
168
+ ## Documentation
169
+
170
+ - [Vachana API Docs](https://docs.inya.ai/vachana/introduction/introduction)
171
+ - [Pipecat Docs](https://docs.pipecat.ai/)
172
+ - [gnani-vachana SDK](https://pypi.org/project/gnani-vachana/)
173
+
174
+ ## License
175
+
176
+ BSD 2-Clause — see [LICENSE](LICENSE).
@@ -0,0 +1,144 @@
1
+ # pipecat-gnani
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/pipecat-gnani)](https://pypi.org/project/pipecat-gnani/)
4
+ [![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](LICENSE)
5
+
6
+ [Pipecat](https://github.com/pipecat-ai/pipecat) service integration for **[Gnani Vachana](https://gnani.ai/)** — high-accuracy Speech-to-Text and low-latency Text-to-Speech for Indian languages.
7
+
8
+ > **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.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pip install pipecat-gnani
14
+ ```
15
+
16
+ This will also install the [`gnani-vachana`](https://pypi.org/project/gnani-vachana/) core SDK as a dependency.
17
+
18
+ ## Prerequisites
19
+
20
+ 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.
21
+
22
+ ```bash
23
+ export GNANI_API_KEY="your-api-key"
24
+ ```
25
+
26
+ ## Quick Start
27
+
28
+ ### Speech-to-Text (Streaming)
29
+
30
+ ```python
31
+ from pipecat_gnani import GnaniSTTService
32
+
33
+ stt = GnaniSTTService(
34
+ api_key="your-api-key",
35
+ settings=GnaniSTTService.Settings(
36
+ language=Language.HI_IN,
37
+ ),
38
+ )
39
+ ```
40
+
41
+ ### Text-to-Speech (REST)
42
+
43
+ ```python
44
+ from pipecat_gnani import GnaniHttpTTSService
45
+
46
+ tts = GnaniHttpTTSService(
47
+ api_key="your-api-key",
48
+ aiohttp_session=session,
49
+ settings=GnaniHttpTTSService.Settings(
50
+ voice="sia",
51
+ language="hi-IN",
52
+ ),
53
+ )
54
+ ```
55
+
56
+ ### Text-to-Speech (Streaming WebSocket)
57
+
58
+ ```python
59
+ from pipecat_gnani import GnaniTTSService
60
+
61
+ tts = GnaniTTSService(
62
+ api_key="your-api-key",
63
+ settings=GnaniTTSService.Settings(
64
+ voice="sia",
65
+ language="IND-IN",
66
+ ),
67
+ )
68
+ ```
69
+
70
+ ## Services
71
+
72
+ ### GnaniSTTService
73
+
74
+ Real-time streaming speech-to-text via WebSocket with VAD (Voice Activity Detection) support.
75
+
76
+ - Connects to `wss://api.vachana.ai/stt/v3/stream`
77
+ - Sends raw PCM audio in 1024-byte chunks
78
+ - Receives transcription events with segment metadata
79
+ - Supports 8 kHz and 16 kHz sample rates
80
+
81
+ ### GnaniHttpTTSService
82
+
83
+ REST-based text-to-speech for non-streaming use cases.
84
+
85
+ - Uses `POST /api/v1/tts/inference`
86
+ - Returns complete audio in a single response
87
+ - Suitable for batch synthesis
88
+
89
+ ### GnaniTTSService
90
+
91
+ WebSocket-based streaming text-to-speech with interruption handling.
92
+
93
+ - Connects to `wss://api.vachana.ai/api/v1/tts`
94
+ - Streams audio chunks in real-time
95
+ - Extends `InterruptibleTTSService` for proper interruption support
96
+ - Ideal for conversational voice agents
97
+
98
+ ## Supported Languages
99
+
100
+ | Language | Code |
101
+ |-----------------|---------|
102
+ | Bengali | `bn-IN` |
103
+ | English (India) | `en-IN` |
104
+ | Gujarati | `gu-IN` |
105
+ | Hindi | `hi-IN` |
106
+ | Kannada | `kn-IN` |
107
+ | Malayalam | `ml-IN` |
108
+ | Marathi | `mr-IN` |
109
+ | Punjabi | `pa-IN` |
110
+ | Tamil | `ta-IN` |
111
+ | Telugu | `te-IN` |
112
+
113
+ ## Available Voices
114
+
115
+ | Voice | ID |
116
+ |---------|-----------|
117
+ | Sia | `sia` |
118
+ | Raju | `raju` |
119
+ | Kanika | `kanika` |
120
+ | Nikita | `nikita` |
121
+ | Ravan | `ravan` |
122
+ | Simran | `simran` |
123
+ | Karan | `karan` |
124
+ | Neha | `neha` |
125
+
126
+ ## Architecture
127
+
128
+ ```
129
+ gnani-vachana ← Core SDK (REST, WebSocket, SSE clients)
130
+ ↑
131
+ pipecat-gnani ← This package (Pipecat service adapter)
132
+ ```
133
+
134
+ This package is a thin adapter that wraps the `gnani-vachana` SDK into Pipecat's `STTService`, `TTSService`, and `InterruptibleTTSService` base classes. All connection logic, authentication, and audio format handling lives in the core SDK.
135
+
136
+ ## Documentation
137
+
138
+ - [Vachana API Docs](https://docs.inya.ai/vachana/introduction/introduction)
139
+ - [Pipecat Docs](https://docs.pipecat.ai/)
140
+ - [gnani-vachana SDK](https://pypi.org/project/gnani-vachana/)
141
+
142
+ ## License
143
+
144
+ BSD 2-Clause — see [LICENSE](LICENSE).
@@ -0,0 +1,32 @@
1
+ """Gnani Vachana speech AI service integration for Pipecat.
2
+
3
+ This package provides STT and TTS services using Gnani's Vachana platform,
4
+ with support for Indian languages and real-time streaming.
5
+
6
+ Services:
7
+ - GnaniSTTService: WebSocket streaming speech-to-text with VAD
8
+ - GnaniHttpTTSService: REST-based text-to-speech
9
+ - GnaniTTSService: WebSocket streaming text-to-speech with interruption handling
10
+ """
11
+
12
+ from pipecat_gnani.stt import GnaniSTTService, GnaniSTTSettings
13
+ from pipecat_gnani.tts import (
14
+ GnaniHttpTTSService,
15
+ GnaniHttpTTSSettings,
16
+ GnaniTTSService,
17
+ GnaniTTSSettings,
18
+ SUPPORTED_VOICES,
19
+ )
20
+
21
+ __version__ = "0.1.0"
22
+
23
+ __all__ = [
24
+ "GnaniSTTService",
25
+ "GnaniSTTSettings",
26
+ "GnaniHttpTTSService",
27
+ "GnaniHttpTTSSettings",
28
+ "GnaniTTSService",
29
+ "GnaniTTSSettings",
30
+ "SUPPORTED_VOICES",
31
+ "__version__",
32
+ ]
@@ -0,0 +1,10 @@
1
+ import platform
2
+
3
+ import pipecat_gnani
4
+
5
+
6
+ def sdk_headers() -> dict[str, str]:
7
+ """SDK identification headers for Gnani Vachana API."""
8
+ return {
9
+ "User-Agent": f"PipecatGnani/{pipecat_gnani.__version__} Python/{platform.python_version()}",
10
+ }
@@ -0,0 +1,271 @@
1
+ """Gnani Vachana Speech-to-Text service implementation.
2
+
3
+ This module provides a streaming STT service using Gnani Vachana's WebSocket API.
4
+ It supports real-time transcription with VAD for Indian language speech recognition.
5
+ """
6
+
7
+ import asyncio
8
+ import json
9
+ from collections.abc import AsyncGenerator
10
+ from dataclasses import dataclass, field
11
+
12
+ from loguru import logger
13
+
14
+ from pipecat.frames.frames import (
15
+ CancelFrame,
16
+ EndFrame,
17
+ ErrorFrame,
18
+ Frame,
19
+ StartFrame,
20
+ TranscriptionFrame,
21
+ )
22
+ from pipecat.services.settings import NOT_GIVEN, STTSettings, _NotGiven, is_given
23
+ from pipecat.services.stt_service import STTService
24
+ from pipecat.transcriptions.language import Language, resolve_language
25
+ from pipecat.utils.time import time_now_iso8601
26
+ from pipecat.utils.tracing.service_decorators import traced_stt
27
+
28
+ from pipecat_gnani._sdk import sdk_headers
29
+
30
+ try:
31
+ import websockets
32
+ from websockets.asyncio.client import connect as websocket_connect
33
+ except ModuleNotFoundError as e:
34
+ logger.error(f"Exception: {e}")
35
+ logger.error(
36
+ "In order to use Gnani Vachana STT, you need to "
37
+ "`pip install pipecat-gnani` or `pip install websockets gnani-vachana`."
38
+ )
39
+ raise Exception(f"Missing module: {e}")
40
+
41
+
42
+ GNANI_STT_WS_URL = "wss://api.vachana.ai/stt/v3/stream"
43
+
44
+ SUPPORTED_SAMPLE_RATES = (8000, 16000)
45
+ STREAM_CHUNK_BYTES = 1024
46
+
47
+
48
+ def language_to_gnani_language(language: Language) -> str:
49
+ """Convert a Language enum to Gnani's language code format."""
50
+ LANGUAGE_MAP = {
51
+ Language.BN_IN: "bn-IN",
52
+ Language.EN_IN: "en-IN",
53
+ Language.GU_IN: "gu-IN",
54
+ Language.HI_IN: "hi-IN",
55
+ Language.KN_IN: "kn-IN",
56
+ Language.ML_IN: "ml-IN",
57
+ Language.MR_IN: "mr-IN",
58
+ Language.PA_IN: "pa-IN",
59
+ Language.TA_IN: "ta-IN",
60
+ Language.TE_IN: "te-IN",
61
+ }
62
+ return resolve_language(language, LANGUAGE_MAP, use_base_code=False)
63
+
64
+
65
+ @dataclass
66
+ class GnaniSTTSettings(STTSettings):
67
+ """Settings for GnaniSTTService.
68
+
69
+ Parameters:
70
+ sample_rate: Audio sample rate (8000 or 16000 Hz).
71
+ """
72
+
73
+ sample_rate: int | None | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
74
+
75
+
76
+ class GnaniSTTService(STTService):
77
+ """Gnani Vachana speech-to-text service.
78
+
79
+ Provides real-time speech recognition using Gnani Vachana's WebSocket API
80
+ for Indian languages.
81
+
82
+ Event handlers available (in addition to STTService events):
83
+
84
+ - on_connected(service): Connected to Gnani WebSocket
85
+ - on_disconnected(service): Disconnected from Gnani WebSocket
86
+ - on_connection_error(service, error): Connection error occurred
87
+
88
+ Example::
89
+
90
+ stt = GnaniSTTService(
91
+ api_key="your-api-key",
92
+ settings=GnaniSTTService.Settings(
93
+ language=Language.HI_IN,
94
+ ),
95
+ )
96
+ """
97
+
98
+ Settings = GnaniSTTSettings
99
+ _settings: Settings
100
+
101
+ def __init__(
102
+ self,
103
+ *,
104
+ api_key: str,
105
+ sample_rate: int | None = None,
106
+ settings: Settings | None = None,
107
+ keepalive_timeout: float | None = None,
108
+ keepalive_interval: float = 5.0,
109
+ **kwargs,
110
+ ):
111
+ """Initialize the Gnani Vachana STT service.
112
+
113
+ Args:
114
+ api_key: Gnani API key for authentication.
115
+ sample_rate: Audio sample rate (8000 or 16000). Defaults to 16000.
116
+ settings: Runtime-updatable settings.
117
+ keepalive_timeout: Seconds of no audio before sending silence.
118
+ keepalive_interval: Seconds between idle checks when keepalive is enabled.
119
+ **kwargs: Additional arguments passed to the parent STTService.
120
+ """
121
+ default_settings = self.Settings(
122
+ language=Language.EN_IN,
123
+ )
124
+
125
+ if settings is not None:
126
+ default_settings.apply_update(settings)
127
+
128
+ super().__init__(
129
+ sample_rate=sample_rate or 16000,
130
+ keepalive_timeout=keepalive_timeout,
131
+ keepalive_interval=keepalive_interval,
132
+ settings=default_settings,
133
+ **kwargs,
134
+ )
135
+
136
+ self._api_key = api_key
137
+ self._ws = None
138
+ self._receive_task = None
139
+
140
+ def language_to_service_language(self, language: Language) -> str:
141
+ return language_to_gnani_language(language)
142
+
143
+ def can_generate_metrics(self) -> bool:
144
+ return True
145
+
146
+ async def start(self, frame: StartFrame):
147
+ await super().start(frame)
148
+ await self._connect()
149
+
150
+ async def stop(self, frame: EndFrame):
151
+ await super().stop(frame)
152
+ await self._disconnect()
153
+
154
+ async def cancel(self, frame: CancelFrame):
155
+ await super().cancel(frame)
156
+ await self._disconnect()
157
+
158
+ @traced_stt
159
+ async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
160
+ if not self._ws:
161
+ yield None
162
+ return
163
+
164
+ try:
165
+ await self._ws.send(audio)
166
+ except Exception as e:
167
+ yield ErrorFrame(error=f"Error sending audio to Gnani: {e}", exception=e)
168
+
169
+ yield None
170
+
171
+ async def _connect(self):
172
+ logger.debug("Connecting to Gnani Vachana STT")
173
+
174
+ try:
175
+ lang = self._get_language_string()
176
+ headers = {
177
+ "x-api-key-id": self._api_key,
178
+ "lang_code": lang or "en-IN",
179
+ **sdk_headers(),
180
+ }
181
+
182
+ self._ws = await websocket_connect(
183
+ GNANI_STT_WS_URL,
184
+ additional_headers=headers,
185
+ ping_interval=20,
186
+ ping_timeout=20,
187
+ close_timeout=10,
188
+ )
189
+
190
+ connected_msg = await asyncio.wait_for(self._ws.recv(), timeout=10)
191
+ connected_data = json.loads(connected_msg)
192
+ if connected_data.get("type") == "connected":
193
+ logger.info(
194
+ f"Gnani STT connected: {connected_data.get('message', '')}"
195
+ )
196
+ else:
197
+ logger.warning(f"Unexpected first message from Gnani STT: {connected_data}")
198
+
199
+ self._receive_task = asyncio.create_task(
200
+ self._receive_messages(), name="gnani-stt-recv"
201
+ )
202
+
203
+ await self._call_event_handler("on_connected")
204
+
205
+ except Exception as e:
206
+ logger.error(f"Failed to connect to Gnani STT: {e}")
207
+ self._ws = None
208
+ await self._call_event_handler("on_connection_error", str(e))
209
+
210
+ async def _disconnect(self):
211
+ if self._receive_task:
212
+ self._receive_task.cancel()
213
+ try:
214
+ await self._receive_task
215
+ except asyncio.CancelledError:
216
+ pass
217
+ self._receive_task = None
218
+
219
+ if self._ws:
220
+ try:
221
+ await self._ws.close()
222
+ except Exception:
223
+ pass
224
+ self._ws = None
225
+
226
+ await self._call_event_handler("on_disconnected")
227
+
228
+ async def _receive_messages(self):
229
+ try:
230
+ async for msg in self._ws:
231
+ if isinstance(msg, bytes):
232
+ continue
233
+
234
+ data = json.loads(msg)
235
+ msg_type = data.get("type", "")
236
+
237
+ if msg_type == "transcript":
238
+ text = data.get("text", "")
239
+ if text:
240
+ await self.push_frame(
241
+ TranscriptionFrame(
242
+ text=text,
243
+ user_id=self._user_id if hasattr(self, "_user_id") else "",
244
+ timestamp=time_now_iso8601(),
245
+ language=self._get_language_string(),
246
+ )
247
+ )
248
+
249
+ elif msg_type in ("speech_start", "vad_start"):
250
+ await self._start_metrics()
251
+
252
+ elif msg_type in ("speech_end", "vad_end"):
253
+ pass
254
+
255
+ elif msg_type == "error":
256
+ error_msg = data.get("message", "Unknown error")
257
+ logger.error(f"Gnani STT stream error: {error_msg}")
258
+ await self.push_frame(ErrorFrame(error=f"Gnani STT: {error_msg}"))
259
+
260
+ except asyncio.CancelledError:
261
+ raise
262
+ except Exception as e:
263
+ logger.error(f"Gnani STT receive error: {e}")
264
+ await self._call_event_handler("on_connection_error", str(e))
265
+
266
+ def _get_language_string(self) -> str | None:
267
+ if self._settings.language:
268
+ if isinstance(self._settings.language, Language):
269
+ return language_to_gnani_language(self._settings.language)
270
+ return str(self._settings.language)
271
+ return "en-IN"
@@ -0,0 +1,462 @@
1
+ """Gnani Vachana text-to-speech service implementation.
2
+
3
+ This module provides TTS services using Gnani Vachana's API with support for
4
+ Indian languages and multiple voices.
5
+
6
+ **Voices:** sia (default), raju, kanika, nikita, ravan, simran, karan, neha
7
+
8
+ **Transport options:**
9
+ - GnaniHttpTTSService: REST-based single-request synthesis
10
+ - GnaniTTSService: WebSocket-based streaming synthesis with interruption handling
11
+ """
12
+
13
+ import asyncio
14
+ import base64
15
+ import json
16
+ from collections.abc import AsyncGenerator
17
+ from dataclasses import dataclass, field
18
+
19
+ import aiohttp
20
+ from loguru import logger
21
+
22
+ from pipecat.frames.frames import (
23
+ CancelFrame,
24
+ EndFrame,
25
+ ErrorFrame,
26
+ Frame,
27
+ StartFrame,
28
+ TTSAudioRawFrame,
29
+ TTSStoppedFrame,
30
+ )
31
+ from pipecat.services.settings import NOT_GIVEN, TTSSettings, _NotGiven, is_given
32
+ from pipecat.services.tts_service import InterruptibleTTSService, TTSService
33
+ from pipecat.transcriptions.language import Language, resolve_language
34
+ from pipecat.utils.tracing.service_decorators import traced_tts
35
+
36
+ from pipecat_gnani._sdk import sdk_headers
37
+
38
+ try:
39
+ from websockets.asyncio.client import connect as websocket_connect
40
+ from websockets.protocol import State
41
+ except ModuleNotFoundError as e:
42
+ logger.error(f"Exception: {e}")
43
+ logger.error(
44
+ "In order to use Gnani Vachana TTS, you need to "
45
+ "`pip install pipecat-gnani` or `pip install websockets gnani-vachana`."
46
+ )
47
+ raise Exception(f"Missing module: {e}")
48
+
49
+
50
+ GNANI_TTS_REST_URL = "https://api.vachana.ai/api/v1/tts/inference"
51
+ GNANI_TTS_WS_URL = "wss://api.vachana.ai/api/v1/tts"
52
+
53
+ SUPPORTED_VOICES = frozenset({
54
+ "sia", "raju", "kanika", "nikita", "ravan", "simran", "karan", "neha",
55
+ })
56
+
57
+
58
+ def language_to_gnani_language(language: Language) -> str | None:
59
+ """Convert Pipecat Language enum to Gnani Vachana language codes."""
60
+ LANGUAGE_MAP = {
61
+ Language.BN: "bn-IN",
62
+ Language.BN_IN: "bn-IN",
63
+ Language.EN: "en-IN",
64
+ Language.EN_IN: "en-IN",
65
+ Language.GU: "gu-IN",
66
+ Language.GU_IN: "gu-IN",
67
+ Language.HI: "hi-IN",
68
+ Language.HI_IN: "hi-IN",
69
+ Language.KN: "kn-IN",
70
+ Language.KN_IN: "kn-IN",
71
+ Language.ML: "ml-IN",
72
+ Language.ML_IN: "ml-IN",
73
+ Language.MR: "mr-IN",
74
+ Language.MR_IN: "mr-IN",
75
+ Language.PA: "pa-IN",
76
+ Language.PA_IN: "pa-IN",
77
+ Language.TA: "ta-IN",
78
+ Language.TA_IN: "ta-IN",
79
+ Language.TE: "te-IN",
80
+ Language.TE_IN: "te-IN",
81
+ }
82
+ return resolve_language(language, LANGUAGE_MAP, use_base_code=False)
83
+
84
+
85
+ @dataclass
86
+ class GnaniHttpTTSSettings(TTSSettings):
87
+ """Settings for GnaniHttpTTSService.
88
+
89
+ Parameters:
90
+ encoding: Audio encoding (linear_pcm or oggopus).
91
+ container: Audio container (raw, mp3, wav, mulaw, ogg).
92
+ sample_width: Sample width in bytes (1-4). Defaults to 2.
93
+ """
94
+
95
+ encoding: str | None | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
96
+ container: str | None | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
97
+ sample_width: int | None | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
98
+
99
+
100
+ @dataclass
101
+ class GnaniTTSSettings(GnaniHttpTTSSettings):
102
+ """Settings for GnaniTTSService (WebSocket).
103
+
104
+ Extends GnaniHttpTTSSettings for WebSocket streaming.
105
+ """
106
+
107
+ pass
108
+
109
+
110
+ class GnaniHttpTTSService(TTSService):
111
+ """REST-based text-to-speech service using Gnani Vachana API.
112
+
113
+ Converts text to speech using Gnani Vachana's REST endpoint. Suitable for
114
+ non-streaming use cases where latency is less critical.
115
+
116
+ Example::
117
+
118
+ tts = GnaniHttpTTSService(
119
+ api_key="your-api-key",
120
+ aiohttp_session=session,
121
+ settings=GnaniHttpTTSService.Settings(
122
+ voice="sia",
123
+ language=Language.HI,
124
+ ),
125
+ )
126
+ """
127
+
128
+ Settings = GnaniHttpTTSSettings
129
+ _settings: Settings
130
+
131
+ def __init__(
132
+ self,
133
+ *,
134
+ api_key: str,
135
+ aiohttp_session: aiohttp.ClientSession,
136
+ voice_id: str | None = None,
137
+ model: str = "vachana-voice-v2",
138
+ sample_rate: int | None = None,
139
+ settings: Settings | None = None,
140
+ **kwargs,
141
+ ):
142
+ """Initialize the Gnani Vachana HTTP TTS service.
143
+
144
+ Args:
145
+ api_key: Gnani API key for authentication.
146
+ aiohttp_session: Shared aiohttp session for making requests.
147
+ voice_id: Speaker voice ID. Defaults to "sia".
148
+ model: TTS model to use. Defaults to "vachana-voice-v2".
149
+ sample_rate: Audio sample rate in Hz. Defaults to 24000.
150
+ settings: Runtime-updatable settings.
151
+ **kwargs: Additional arguments passed to parent TTSService.
152
+ """
153
+ default_settings = self.Settings(
154
+ model=model,
155
+ voice=voice_id or "sia",
156
+ language="en-IN",
157
+ encoding="linear_pcm",
158
+ container="wav",
159
+ sample_width=2,
160
+ )
161
+
162
+ if settings is not None:
163
+ default_settings.apply_update(settings)
164
+
165
+ if default_settings.voice and default_settings.voice not in SUPPORTED_VOICES:
166
+ raise ValueError(
167
+ f"Voice '{default_settings.voice}' not supported. "
168
+ f"Choose from: {sorted(SUPPORTED_VOICES)}"
169
+ )
170
+
171
+ super().__init__(
172
+ sample_rate=sample_rate or 24000,
173
+ push_stop_frames=True,
174
+ push_start_frame=True,
175
+ settings=default_settings,
176
+ **kwargs,
177
+ )
178
+
179
+ self._api_key = api_key
180
+ self._session = aiohttp_session
181
+
182
+ def can_generate_metrics(self) -> bool:
183
+ return True
184
+
185
+ def language_to_service_language(self, language: Language) -> str | None:
186
+ return language_to_gnani_language(language)
187
+
188
+ @traced_tts
189
+ async def run_tts(self, text: str, context_id: str) -> AsyncGenerator[Frame, None]:
190
+ logger.debug(f"{self}: Generating TTS [{text}]")
191
+
192
+ try:
193
+ payload = {
194
+ "text": text,
195
+ "voice": self._settings.voice or "sia",
196
+ "model": self._settings.model or "vachana-voice-v2",
197
+ "audio_config": {
198
+ "sample_rate": self.sample_rate,
199
+ "encoding": self._settings.encoding or "linear_pcm",
200
+ "num_channels": 1,
201
+ "sample_width": self._settings.sample_width or 2,
202
+ "container": self._settings.container or "wav",
203
+ },
204
+ }
205
+
206
+ headers = {
207
+ "X-API-Key-ID": self._api_key,
208
+ "Content-Type": "application/json",
209
+ **sdk_headers(),
210
+ }
211
+
212
+ async with self._session.post(
213
+ GNANI_TTS_REST_URL, json=payload, headers=headers
214
+ ) as response:
215
+ if response.status != 200:
216
+ error_text = await response.text()
217
+ yield ErrorFrame(error=f"Gnani TTS API error: {error_text}")
218
+ return
219
+
220
+ audio_data = await response.read()
221
+
222
+ await self.start_tts_usage_metrics(text)
223
+
224
+ if len(audio_data) > 44 and audio_data.startswith(b"RIFF"):
225
+ audio_data = audio_data[44:]
226
+
227
+ yield TTSAudioRawFrame(
228
+ audio=audio_data,
229
+ sample_rate=self.sample_rate,
230
+ num_channels=1,
231
+ context_id=context_id,
232
+ )
233
+
234
+ except Exception as e:
235
+ yield ErrorFrame(error=f"Error generating TTS: {e}", exception=e)
236
+ finally:
237
+ await self.stop_ttfb_metrics()
238
+
239
+
240
+ class GnaniTTSService(InterruptibleTTSService):
241
+ """WebSocket-based text-to-speech service using Gnani Vachana.
242
+
243
+ Provides streaming TTS with real-time audio generation and interruption
244
+ handling via WebSocket.
245
+
246
+ Example::
247
+
248
+ tts = GnaniTTSService(
249
+ api_key="your-api-key",
250
+ settings=GnaniTTSService.Settings(
251
+ voice="sia",
252
+ language=Language.HI,
253
+ ),
254
+ )
255
+ """
256
+
257
+ Settings = GnaniTTSSettings
258
+ _settings: Settings
259
+
260
+ def __init__(
261
+ self,
262
+ *,
263
+ api_key: str,
264
+ voice_id: str | None = None,
265
+ model: str = "vachana-voice-v2",
266
+ sample_rate: int | None = None,
267
+ settings: Settings | None = None,
268
+ **kwargs,
269
+ ):
270
+ """Initialize the Gnani Vachana WebSocket TTS service.
271
+
272
+ Args:
273
+ api_key: Gnani API key for authentication.
274
+ voice_id: Speaker voice ID. Defaults to "sia".
275
+ model: TTS model to use. Defaults to "vachana-voice-v2".
276
+ sample_rate: Audio sample rate in Hz. Defaults to 24000.
277
+ settings: Runtime-updatable settings.
278
+ **kwargs: Additional arguments passed to parent.
279
+ """
280
+ default_settings = self.Settings(
281
+ model=model,
282
+ voice=voice_id or "sia",
283
+ language="IND-IN",
284
+ encoding="linear_pcm",
285
+ container="wav",
286
+ sample_width=2,
287
+ )
288
+
289
+ if settings is not None:
290
+ default_settings.apply_update(settings)
291
+
292
+ if default_settings.voice and default_settings.voice not in SUPPORTED_VOICES:
293
+ raise ValueError(
294
+ f"Voice '{default_settings.voice}' not supported. "
295
+ f"Choose from: {sorted(SUPPORTED_VOICES)}"
296
+ )
297
+
298
+ super().__init__(
299
+ sample_rate=sample_rate or 24000,
300
+ push_stop_frames=True,
301
+ push_start_frame=True,
302
+ settings=default_settings,
303
+ **kwargs,
304
+ )
305
+
306
+ self._api_key = api_key
307
+ self._ws = None
308
+ self._receive_task = None
309
+ self._bot_speaking = False
310
+
311
+ def can_generate_metrics(self) -> bool:
312
+ return True
313
+
314
+ def language_to_service_language(self, language: Language) -> str | None:
315
+ return language_to_gnani_language(language)
316
+
317
+ async def start(self, frame: StartFrame):
318
+ await super().start(frame)
319
+ await self._connect()
320
+
321
+ async def stop(self, frame: EndFrame):
322
+ await super().stop(frame)
323
+ await self._disconnect()
324
+
325
+ async def cancel(self, frame: CancelFrame):
326
+ await super().cancel(frame)
327
+ await self._disconnect()
328
+
329
+ @traced_tts
330
+ async def run_tts(self, text: str, context_id: str) -> AsyncGenerator[Frame, None]:
331
+ logger.debug(f"{self}: Streaming TTS [{text}]")
332
+
333
+ if not self._ws:
334
+ await self._connect()
335
+
336
+ if not self._ws:
337
+ yield ErrorFrame(error="Gnani TTS WebSocket not connected")
338
+ return
339
+
340
+ try:
341
+ request_body = {
342
+ "text": text,
343
+ "voice": self._settings.voice or "sia",
344
+ "model": self._settings.model or "vachana-voice-v2",
345
+ "language": self._settings.language or "IND-IN",
346
+ "audio_config": {
347
+ "sample_rate": self.sample_rate,
348
+ "encoding": self._settings.encoding or "linear_pcm",
349
+ "num_channels": 1,
350
+ "sample_width": self._settings.sample_width or 2,
351
+ "container": self._settings.container or "wav",
352
+ },
353
+ }
354
+
355
+ self._bot_speaking = True
356
+ await self._ws.send(json.dumps(request_body))
357
+
358
+ await self.start_tts_usage_metrics(text)
359
+
360
+ except Exception as e:
361
+ yield ErrorFrame(error=f"Error sending TTS request: {e}", exception=e)
362
+ finally:
363
+ await self.stop_ttfb_metrics()
364
+
365
+ yield None
366
+
367
+ async def _connect(self):
368
+ logger.debug("Connecting to Gnani Vachana TTS WebSocket")
369
+
370
+ try:
371
+ headers = {
372
+ "Content-Type": "application/json",
373
+ "X-API-Key-ID": self._api_key,
374
+ **sdk_headers(),
375
+ }
376
+
377
+ self._ws = await websocket_connect(
378
+ GNANI_TTS_WS_URL,
379
+ additional_headers=headers,
380
+ ping_interval=20,
381
+ ping_timeout=20,
382
+ close_timeout=10,
383
+ )
384
+
385
+ self._receive_task = asyncio.create_task(
386
+ self._receive_messages(), name="gnani-tts-recv"
387
+ )
388
+
389
+ await self._call_event_handler("on_connected")
390
+
391
+ except Exception as e:
392
+ logger.error(f"Failed to connect to Gnani TTS: {e}")
393
+ self._ws = None
394
+ await self._call_event_handler("on_connection_error", str(e))
395
+
396
+ async def _disconnect(self):
397
+ if self._receive_task:
398
+ self._receive_task.cancel()
399
+ try:
400
+ await self._receive_task
401
+ except asyncio.CancelledError:
402
+ pass
403
+ self._receive_task = None
404
+
405
+ if self._ws:
406
+ try:
407
+ await self._ws.close()
408
+ except Exception:
409
+ pass
410
+ self._ws = None
411
+
412
+ await self._call_event_handler("on_disconnected")
413
+
414
+ async def _receive_messages(self):
415
+ try:
416
+ async for msg in self._ws:
417
+ if isinstance(msg, bytes):
418
+ await self._handle_audio_chunk(msg)
419
+ continue
420
+
421
+ data = json.loads(msg)
422
+ msg_type = data.get("type", "")
423
+
424
+ if msg_type == "audio":
425
+ audio_b64 = data.get("audio", "")
426
+ if audio_b64:
427
+ audio_bytes = base64.b64decode(audio_b64)
428
+ await self._handle_audio_chunk(audio_bytes)
429
+
430
+ elif msg_type == "complete":
431
+ audio_b64 = data.get("audio", "")
432
+ if audio_b64:
433
+ audio_bytes = base64.b64decode(audio_b64)
434
+ await self._handle_audio_chunk(audio_bytes)
435
+ self._bot_speaking = False
436
+ await self.push_frame(TTSStoppedFrame())
437
+
438
+ elif msg_type == "error":
439
+ error_msg = data.get("message", "Unknown error")
440
+ logger.error(f"Gnani TTS stream error: {error_msg}")
441
+ self._bot_speaking = False
442
+ await self.push_frame(ErrorFrame(error=f"Gnani TTS: {error_msg}"))
443
+
444
+ except asyncio.CancelledError:
445
+ raise
446
+ except Exception as e:
447
+ logger.error(f"Gnani TTS receive error: {e}")
448
+ self._bot_speaking = False
449
+ await self._call_event_handler("on_connection_error", str(e))
450
+
451
+ async def _handle_audio_chunk(self, audio_bytes: bytes):
452
+ if len(audio_bytes) > 44 and audio_bytes.startswith(b"RIFF"):
453
+ audio_bytes = audio_bytes[44:]
454
+
455
+ if audio_bytes:
456
+ await self.push_frame(
457
+ TTSAudioRawFrame(
458
+ audio=audio_bytes,
459
+ sample_rate=self.sample_rate,
460
+ num_channels=1,
461
+ )
462
+ )
@@ -0,0 +1,79 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "pipecat-gnani"
7
+ version = "0.1.0"
8
+ description = "Pipecat service integration for Gnani Vachana speech AI — STT & TTS for Indian languages"
9
+ readme = "README.md"
10
+ license = "BSD-2-Clause"
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ { name = "Genvoice", email = "speechstack@gnani.ai" },
14
+ ]
15
+ keywords = [
16
+ "pipecat", "pipecat-ai", "voice-agent", "conversational-ai",
17
+ "gnani", "vachana", "indian-languages", "indic",
18
+ "stt", "tts", "speech-to-text", "text-to-speech",
19
+ "multilingual", "streaming", "websocket",
20
+ ]
21
+ classifiers = [
22
+ "Development Status :: 4 - Beta",
23
+ "Intended Audience :: Developers",
24
+ "License :: OSI Approved :: BSD License",
25
+ "Operating System :: OS Independent",
26
+ "Programming Language :: Python :: 3",
27
+ "Programming Language :: Python :: 3.10",
28
+ "Programming Language :: Python :: 3.11",
29
+ "Programming Language :: Python :: 3.12",
30
+ "Programming Language :: Python :: 3.13",
31
+ "Programming Language :: Python :: 3 :: Only",
32
+ "Topic :: Multimedia :: Sound/Audio",
33
+ "Topic :: Multimedia :: Sound/Audio :: Speech",
34
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
35
+ ]
36
+ dependencies = [
37
+ "pipecat-ai>=0.0.50",
38
+ "gnani-vachana>=0.2.2,<1.0",
39
+ "websockets>=13.1,<16.0",
40
+ "aiohttp>=3.9.0",
41
+ ]
42
+
43
+ [project.urls]
44
+ Homepage = "https://gnani.ai"
45
+ Documentation = "https://docs.inya.ai/vachana"
46
+ Repository = "https://github.com/Gnani-AI-Mintlify/pipecat-gnani"
47
+ Issues = "https://github.com/Gnani-AI-Mintlify/pipecat-gnani/issues"
48
+
49
+ [tool.hatch.build.targets.wheel]
50
+ packages = ["pipecat_gnani"]
51
+
52
+ [tool.hatch.build.targets.sdist]
53
+ include = ["/pipecat_gnani"]
54
+
55
+ # ---------------------------------------------------------------------------
56
+ # Ruff
57
+ # ---------------------------------------------------------------------------
58
+ [tool.ruff]
59
+ target-version = "py310"
60
+ line-length = 100
61
+
62
+ [tool.ruff.lint]
63
+ select = ["E", "W", "F", "I", "N", "UP", "B", "SIM", "TCH", "RUF"]
64
+ ignore = ["E501"]
65
+
66
+ [tool.ruff.lint.isort]
67
+ known-first-party = ["pipecat_gnani"]
68
+
69
+ [tool.ruff.format]
70
+ quote-style = "double"
71
+ indent-style = "space"
72
+
73
+ # ---------------------------------------------------------------------------
74
+ # Mypy
75
+ # ---------------------------------------------------------------------------
76
+ [tool.mypy]
77
+ python_version = "3.10"
78
+ warn_return_any = true
79
+ warn_unused_configs = true