Metadata-Version: 2.4
Name: pipecat-maya
Version: 0.1.0
Summary: Maya Research TTS integration for Pipecat
Author-email: Maya Research <charan@mayaresearch.ai>
Maintainer-email: Maya Research <charan@mayaresearch.ai>
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://www.mayaresearch.ai
Project-URL: Documentation, https://www.mayaresearch.ai/llm.txt
Keywords: pipecat,tts,voice,ai,maya,indian-languages
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Natural Language :: Hindi
Classifier: Natural Language :: Bengali
Classifier: Natural Language :: Tamil
Classifier: Natural Language :: Telugu
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pipecat-ai<2,>=1.6.0
Requires-Dist: aiohttp<4,>=3.11.12
Requires-Dist: loguru~=0.7.3
Provides-Extra: example
Requires-Dist: pipecat-ai[daily,deepgram,openai,runner,silero,webrtc]<2,>=1.6.0; extra == "example"
Requires-Dist: python-dotenv<2,>=1.0.0; extra == "example"
Provides-Extra: local-agent
Requires-Dist: pipecat-ai[local,openai,silero,soniox]<2,>=1.6.0; extra == "local-agent"
Requires-Dist: python-dotenv<2,>=1.0.0; extra == "local-agent"
Provides-Extra: dev
Requires-Dist: pytest<10,>=9.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1.0.0; extra == "dev"
Requires-Dist: ruff<1,>=0.12.11; extra == "dev"
Dynamic: license-file

# pipecat-maya

[Maya Research](https://www.mayaresearch.ai) TTS integration for [Pipecat](https://github.com/pipecat-ai/pipecat).

Maya 2 is a text-to-speech model built for Indian languages. It offers two voices — `Ananya` (female) and `Arjun` (male) — and both support all ten available languages: Hindi, Bengali, Gujarati, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil, and Telugu.

This package provides `MayaHttpTTSService`, a drop-in Pipecat TTS service that streams audio from Maya's HTTP API.

> Maintained by the Maya Research team. Tested with Pipecat v1.6.0, verified against the live Maya 2 API.

## Installation

```bash
uv add pipecat-maya
# or
pip install pipecat-maya
```

`pipecat-ai` is pulled in automatically. The service itself needs no extra dependencies beyond `aiohttp`.

## Prerequisites

You need a Maya API key. Contact charan@mayaresearch.ai, bharath@mayaresearch.ai, or dheemanth@mayaresearch.ai to get one.

```bash
export MAYA_API_KEY=...
```

## Usage

```python
import os

from pipecat.transcriptions.language import Language
from pipecat_maya import MayaHttpTTSService

tts = MayaHttpTTSService(
    api_key=os.environ["MAYA_API_KEY"],
    settings=MayaHttpTTSService.Settings(
        voice="Ananya",  # or "Arjun"
        language=Language.HI,
        region="IN",  # or "US"
    ),
)
```

Then drop it into a pipeline exactly like any built-in Pipecat TTS service:

```python
pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,  # <-- Maya
        transport.output(),
        assistant_aggregator,
    ]
)
```

### Configuration

Constructor parameters:

| Parameter | Required | Default | Description |
|---|---|---|---|
| `api_key` | Yes | — | Maya API key. |
| `aiohttp_session` | No | `None` | Reuse an existing `aiohttp.ClientSession`. If omitted, the service creates and closes its own. |
| `base_url` | No | `https://tts.mayaresearch.ai` | Override for self-hosted or staging endpoints. |
| `sample_rate` | No | pipeline default | Output rate in Hz. Maya synthesizes at 24 kHz; anything else is resampled. |
| `settings` | No | see below | Runtime-updatable settings. |

Runtime settings (`MayaHttpTTSService.Settings`), all changeable mid-pipeline via `TTSUpdateSettingsFrame`:

| Setting | Default | Values |
|---|---|---|
| `voice` | `"Ananya"` | `"Ananya"`, `"Arjun"` |
| `language` | `None` | Any `Language` enum; the ten Indian languages listed above are verified. |
| `region` | `"IN"` | `"IN"`, `"US"` |

`model` is unused — Maya 2 exposes a single model.

Maya validates `language` strictly: an unsupported code is rejected with `400 invalid 'language'`. So if you configure a language Maya doesn't support (English, for example), the service logs a warning and **omits** the field, letting Maya fall back to its own default — you still get audio instead of a failed turn.

Supported codes: `hi`, `bn`, `gu`, `kn`, `ml`, `mr`, `or`, `pa`, `ta`, `te`.

## Examples

**Verify your key** without setting up a full pipeline — synthesizes one Hindi sentence to `maya-out.wav`:

```bash
MAYA_API_KEY=... uv run --with pipecat-maya example/synthesize_to_wav.py
```

**Full voice agent** (Deepgram STT + OpenAI LLM + Maya TTS over WebRTC). Needs `DEEPGRAM_API_KEY` and `OPENAI_API_KEY` in addition to `MAYA_API_KEY`:

```bash
uv run --with "pipecat-maya[example]" example/maya_voice_agent.py
```

Then open the printed URL in your browser.

**Local mic/speaker agent with latency instrumentation** — talks through your laptop's mic and speakers, no browser or transport server. Prints per-service TTFB, an end-to-end latency breakdown, transcripts, and LLM activity. Needs `SONIOX_API_KEY` and `OPENAI_API_KEY` alongside `MAYA_API_KEY`:

```bash
uv run --with "pipecat-maya[local-agent]" example/local_voice_agent_metrics.py
```

Set `MAYA_VOICE` (`Ananya`/`Arjun`) and `MAYA_LANGUAGE` (`hi`, `ta`, ...) to switch voice and language.

## How it works

Maya's `POST /v1/tts` streams raw PCM — 16-bit signed little-endian, mono, 24 kHz, no file header. The service reads the response with `iter_chunked` and pushes `TTSAudioRawFrame`s as bytes arrive rather than buffering the full utterance, so time-to-first-byte stays low. Pipecat's `_stream_audio_frames_from_iterator` handles resampling to the pipeline rate and keeps chunks sample-aligned.

The HTTP session is reused across requests to avoid repeated TLS handshakes.

## Rate limits

Maya's defaults are 120 requests/minute and 16 concurrent requests. Exceeding either returns a 429, which surfaces as an `ErrorFrame` with the status and body.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff format . && uv run ruff check .
```

## License

BSD 2-Clause. See [LICENSE](LICENSE).
