pipecat-chariot 0.1.0__tar.gz

pipecat_chariot-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Chariot: get a key at platform.chariot.in
+CHARIOT_API_KEY=your-api-key-here
+
+# Optional. Without it the service uses a Chariot stock voice.
+# List voices: GET https://api.chariot.in/v1/voices
+CHARIOT_VOICE_ID=your-voice-uuid
+
+# The example uses OpenAI for speech-to-text and the LLM.
+OPENAI_API_KEY=your-openai-key-here

pipecat_chariot-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+venv/
+.env
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.wav
+uv.lock

pipecat_chariot-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `pipecat-chariot` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- `ChariotTTSService`, a streaming Pipecat `TTSService` over Chariot's
+  text-to-speech WebSocket API.
+- Optional `model` and `speed`, both omitted from the request when unset so
+  the account default applies and a newly released model needs no upgrade.
+- Persistent connection reused across turns, with a keepalive that holds the
+  session open through quiet stretches.
+- Interruption handling through `InterruptibleTTSService`: closing the socket
+  stops server side generation immediately.
+- Runtime voice switching through `TTSUpdateSettingsFrame`.
+- Segmentation of over long utterances at word boundaries, so a long reply is
+  spoken as contiguous audio.
+- A Chariot stock voice as the default, so the service runs with just an API key.
+- Foundational voice example and unit tests.
+
+Tested with Pipecat v1.10.0.

pipecat_chariot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chariot AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pipecat_chariot-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: pipecat-chariot
+Version: 0.1.0
+Summary: Chariot text-to-speech for Pipecat
+Project-URL: Homepage, https://chariot.in
+Project-URL: Documentation, https://docs.chariot.in/api-reference/introduction
+Project-URL: Repository, https://github.com/Chariot-AI/pipecat-chariot
+Project-URL: Changelog, https://github.com/Chariot-AI/pipecat-chariot/blob/main/CHANGELOG.md
+Author: Chariot AI
+License: MIT License
+        
+        Copyright (c) 2026 Chariot AI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: chariot,indian-languages,pipecat,text-to-speech,tts,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Requires-Dist: pipecat-ai<2,>=1.7
+Requires-Dist: websockets>=13.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pipecat-chariot
+
+Chariot text-to-speech for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+`ChariotTTSService` is a drop-in Pipecat `TTSService` backed by [Chariot](https://chariot.in), which serves lifelike voices for Indian languages and English. Audio streams back as 16-bit mono PCM while the server is still generating, so playback starts before synthesis finishes.
+
+This integration is built and maintained by Chariot, the company providing the service.
+
+## Pipecat compatibility
+
+Tested with Pipecat v1.10.0. The package requires `pipecat-ai>=1.7,<2` and Python 3.11 or newer, which is Pipecat's own floor.
+
+## Installation
+
+```bash
+uv add pipecat-chariot
+```
+
+or
+
+```bash
+pip install pipecat-chariot
+```
+
+## Prerequisites
+
+1. Create an account at [platform.chariot.in](https://platform.chariot.in). New accounts include free credits.
+2. Copy an API key from the console.
+3. Optionally pick a voice from `GET https://api.chariot.in/v1/voices`. Without one the service uses a Chariot stock voice, so the example below runs on the API key alone.
+
+```bash
+export CHARIOT_API_KEY="your-api-key"
+export CHARIOT_VOICE_ID="your-voice-uuid"   # optional
+```
+
+## Usage
+
+```python
+import os
+
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat_chariot import ChariotTTSService
+
+tts = ChariotTTSService(
+    api_key=os.getenv("CHARIOT_API_KEY"),
+    settings=ChariotTTSService.Settings(
+        voice=os.getenv("CHARIOT_VOICE_ID"),
+    ),
+)
+
+pipeline = Pipeline(
+    [
+        transport.input(),
+        stt,
+        user_aggregator,
+        llm,
+        tts,
+        transport.output(),
+        assistant_aggregator,
+    ]
+)
+```
+
+## Configuration
+
+### Constructor parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Chariot API key. Falls back to `CHARIOT_API_KEY`. |
+| `voice_id` | `str \| None` | stock voice | Voice UUID from `GET /v1/voices`. `settings.voice` takes precedence. |
+| `base_url` | `str` | `wss://api.chariot.in` | Override for a non-production endpoint. |
+| `sample_rate` | `int \| None` | `44100` | Output rate in Hz. Chariot streams 44.1 kHz; a mismatch logs a warning. |
+| `model` | `str \| None` | account default | Chariot TTS model. `settings.model` takes precedence. |
+| `speed` | `float \| None` | voice as recorded | Speaking rate, 0.5 to 2.0. `settings.speed` takes precedence. |
+| `optimize_streaming_latency` | `int` | `0` | Latency optimization level, 0 to 4. Higher trades quality passes for speed. |
+
+### Settings
+
+Pass through `ChariotTTSService.Settings(...)`. Updatable at runtime with `TTSUpdateSettingsFrame`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `voice` | `str` | stock voice | Voice UUID. |
+| `model` | `str \| None` | account default | Chariot TTS model. |
+| `speed` | `float \| None` | voice as recorded | Speaking rate, 0.5 to 2.0. |
+
+Voice, model and speed are fixed for the life of a session, because the voice
+codes they select are sent once at connect. Changing any of them reconnects,
+which the service handles for you. Leaving model or speed unset uses your
+account default, so a newly released model works without upgrading this
+package.
+
+There is no language parameter. Any voice speaks any supported language, so the audio follows the text.
+
+## Run the example
+
+The example is a full voice agent: Chariot speaks, and you can interrupt it mid-sentence.
+
+```bash
+git clone https://github.com/Chariot-AI/pipecat-chariot.git
+cd pipecat-chariot
+uv venv && uv pip install -e ".[dev]"
+uv pip install "pipecat-ai[openai,silero,webrtc,runner]"
+cp .env.example .env    # add CHARIOT_API_KEY and OPENAI_API_KEY
+uv run python examples/voice_chariot.py
+```
+
+The example runs in the browser over WebRTC, so it needs no third party
+transport account. Open the URL it prints, allow the microphone, and talk.
+Speech to text and the LLM use OpenAI; swap in any Pipecat services you prefer.
+
+`ChariotTTSService` itself is transport agnostic. It sits between the LLM and
+`transport.output()` and never sees the transport, so it works with any of
+them: Daily, LiveKit, telephony, WebSocket. The example demos WebRTC because
+that needs no account; to try another, add its key to `transport_params` and
+install its extra.
+
+## How it behaves
+
+- **Streaming**: audio frames are yielded while the server is still generating. Output is 16-bit mono PCM at 44.1 kHz, and every frame carries the rate the server declares in its `audio.start` event.
+- **Interruptions**: built on `InterruptibleTTSService`, the base class for websocket TTS services that support neither context IDs nor a cancel message. On interruption the socket is closed, which stops server side generation immediately.
+- **Long text**: the server caps its un-flushed buffer, so an over long utterance is sent as several word boundary segments, each flushed on its own. One generation segment per flush, contiguous audio.
+- **Keepalive**: a flush with nothing buffered is a server side no-op that still resets the idle timeout, so a quiet stretch does not drop the connection.
+- **Turn boundaries**: `audio.done` marks the end of one flushed segment, not the end of the turn. The turn closes when the LLM turn has completed and every segment sent has come back, so a multi sentence reply is never cut short and `BotStoppedSpeakingFrame` still tracks the real end of audio.
+- **Errors**: failures surface as Pipecat `ErrorFrame`s rather than hanging the pipeline. An exhausted credit balance is reported as exactly that.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

pipecat_chariot-0.1.0/README.md

@@ -0,0 +1,140 @@
+# pipecat-chariot
+
+Chariot text-to-speech for [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+`ChariotTTSService` is a drop-in Pipecat `TTSService` backed by [Chariot](https://chariot.in), which serves lifelike voices for Indian languages and English. Audio streams back as 16-bit mono PCM while the server is still generating, so playback starts before synthesis finishes.
+
+This integration is built and maintained by Chariot, the company providing the service.
+
+## Pipecat compatibility
+
+Tested with Pipecat v1.10.0. The package requires `pipecat-ai>=1.7,<2` and Python 3.11 or newer, which is Pipecat's own floor.
+
+## Installation
+
+```bash
+uv add pipecat-chariot
+```
+
+or
+
+```bash
+pip install pipecat-chariot
+```
+
+## Prerequisites
+
+1. Create an account at [platform.chariot.in](https://platform.chariot.in). New accounts include free credits.
+2. Copy an API key from the console.
+3. Optionally pick a voice from `GET https://api.chariot.in/v1/voices`. Without one the service uses a Chariot stock voice, so the example below runs on the API key alone.
+
+```bash
+export CHARIOT_API_KEY="your-api-key"
+export CHARIOT_VOICE_ID="your-voice-uuid"   # optional
+```
+
+## Usage
+
+```python
+import os
+
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat_chariot import ChariotTTSService
+
+tts = ChariotTTSService(
+    api_key=os.getenv("CHARIOT_API_KEY"),
+    settings=ChariotTTSService.Settings(
+        voice=os.getenv("CHARIOT_VOICE_ID"),
+    ),
+)
+
+pipeline = Pipeline(
+    [
+        transport.input(),
+        stt,
+        user_aggregator,
+        llm,
+        tts,
+        transport.output(),
+        assistant_aggregator,
+    ]
+)
+```
+
+## Configuration
+
+### Constructor parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Chariot API key. Falls back to `CHARIOT_API_KEY`. |
+| `voice_id` | `str \| None` | stock voice | Voice UUID from `GET /v1/voices`. `settings.voice` takes precedence. |
+| `base_url` | `str` | `wss://api.chariot.in` | Override for a non-production endpoint. |
+| `sample_rate` | `int \| None` | `44100` | Output rate in Hz. Chariot streams 44.1 kHz; a mismatch logs a warning. |
+| `model` | `str \| None` | account default | Chariot TTS model. `settings.model` takes precedence. |
+| `speed` | `float \| None` | voice as recorded | Speaking rate, 0.5 to 2.0. `settings.speed` takes precedence. |
+| `optimize_streaming_latency` | `int` | `0` | Latency optimization level, 0 to 4. Higher trades quality passes for speed. |
+
+### Settings
+
+Pass through `ChariotTTSService.Settings(...)`. Updatable at runtime with `TTSUpdateSettingsFrame`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `voice` | `str` | stock voice | Voice UUID. |
+| `model` | `str \| None` | account default | Chariot TTS model. |
+| `speed` | `float \| None` | voice as recorded | Speaking rate, 0.5 to 2.0. |
+
+Voice, model and speed are fixed for the life of a session, because the voice
+codes they select are sent once at connect. Changing any of them reconnects,
+which the service handles for you. Leaving model or speed unset uses your
+account default, so a newly released model works without upgrading this
+package.
+
+There is no language parameter. Any voice speaks any supported language, so the audio follows the text.
+
+## Run the example
+
+The example is a full voice agent: Chariot speaks, and you can interrupt it mid-sentence.
+
+```bash
+git clone https://github.com/Chariot-AI/pipecat-chariot.git
+cd pipecat-chariot
+uv venv && uv pip install -e ".[dev]"
+uv pip install "pipecat-ai[openai,silero,webrtc,runner]"
+cp .env.example .env    # add CHARIOT_API_KEY and OPENAI_API_KEY
+uv run python examples/voice_chariot.py
+```
+
+The example runs in the browser over WebRTC, so it needs no third party
+transport account. Open the URL it prints, allow the microphone, and talk.
+Speech to text and the LLM use OpenAI; swap in any Pipecat services you prefer.
+
+`ChariotTTSService` itself is transport agnostic. It sits between the LLM and
+`transport.output()` and never sees the transport, so it works with any of
+them: Daily, LiveKit, telephony, WebSocket. The example demos WebRTC because
+that needs no account; to try another, add its key to `transport_params` and
+install its extra.
+
+## How it behaves
+
+- **Streaming**: audio frames are yielded while the server is still generating. Output is 16-bit mono PCM at 44.1 kHz, and every frame carries the rate the server declares in its `audio.start` event.
+- **Interruptions**: built on `InterruptibleTTSService`, the base class for websocket TTS services that support neither context IDs nor a cancel message. On interruption the socket is closed, which stops server side generation immediately.
+- **Long text**: the server caps its un-flushed buffer, so an over long utterance is sent as several word boundary segments, each flushed on its own. One generation segment per flush, contiguous audio.
+- **Keepalive**: a flush with nothing buffered is a server side no-op that still resets the idle timeout, so a quiet stretch does not drop the connection.
+- **Turn boundaries**: `audio.done` marks the end of one flushed segment, not the end of the turn. The turn closes when the LLM turn has completed and every segment sent has come back, so a multi sentence reply is never cut short and `BotStoppedSpeakingFrame` still tracks the real end of audio.
+- **Errors**: failures surface as Pipecat `ErrorFrame`s rather than hanging the pipeline. An exhausted credit balance is reported as exactly that.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

pipecat_chariot-0.1.0/docs/chariot.mdx

@@ -0,0 +1,177 @@
+---
+title: "Chariot Text-to-Speech"
+sidebarTitle: "Chariot"
+description: "ChariotTTSService streams Indian-language and English speech from Chariot's WebSocket API."
+---
+
+import { CommunityMaintained } from "/snippets/community-maintained.mdx";
+
+<CommunityMaintained
+  maintainer="Chariot-AI"
+  maintainerUrl="https://github.com/Chariot-AI"
+  repo="https://github.com/Chariot-AI/pipecat-chariot"
+/>
+
+## Overview
+
+`ChariotTTSService` synthesizes speech using [Chariot](https://chariot.in), which
+serves lifelike voices for Indian languages and English.
+
+The service keeps one WebSocket open across turns and streams audio as it
+arrives. Any voice speaks any supported language, so the audio follows the text
+rather than the voice, and there is no language parameter to set.
+
+<CardGroup cols={2}>
+  <Card
+    title="Source Repository"
+    icon="github"
+    href="https://github.com/Chariot-AI/pipecat-chariot"
+  >
+    Package source, the voice example, and issue tracker
+  </Card>
+  <Card
+    title="PyPI Package"
+    icon="cube"
+    href="https://pypi.org/project/pipecat-chariot/"
+  >
+    The `pipecat-chariot` package on PyPI
+  </Card>
+  <Card title="Chariot" icon="book" href="https://docs.chariot.in/api-reference/introduction">
+    API reference, voices, and supported languages
+  </Card>
+  <Card title="API Keys" icon="key" href="https://platform.chariot.in">
+    Create an account and manage your Chariot API keys
+  </Card>
+</CardGroup>
+
+## Installation
+
+Install the community package. It is published separately from `pipecat-ai`:
+
+```bash
+uv add pipecat-chariot
+```
+
+## Prerequisites
+
+### Account and API key
+
+1. Create an account at [platform.chariot.in](https://platform.chariot.in). New accounts include free credits.
+2. Copy an API key from the console.
+
+Set it in the environment:
+
+```bash
+export CHARIOT_API_KEY="your-api-key"
+```
+
+### Voices
+
+List available voices with `GET https://api.chariot.in/v1/voices`. A voice id is
+optional: without one the service uses a Chariot stock voice, so the example
+runs on the API key alone.
+
+```bash
+export CHARIOT_VOICE_ID="your-voice-uuid"
+```
+
+## Configuration
+
+<ParamField path="api_key" type="str" default="None">
+  Chariot API key. If omitted, the service reads `CHARIOT_API_KEY`.
+</ParamField>
+
+<ParamField path="voice_id" type="str" default="None">
+  Voice UUID from `GET /v1/voices`. `settings.voice` takes precedence. Defaults
+  to a Chariot stock voice when neither is given.
+</ParamField>
+
+<ParamField path="base_url" type="str" default="wss://api.chariot.in">
+  Override this only for a non-production Chariot endpoint.
+</ParamField>
+
+<ParamField path="sample_rate" type="int" default="44100">
+  Output rate in Hz. Chariot streams 44.1 kHz; the rate declared by the server
+  is applied to every audio frame, and a mismatch logs a warning.
+</ParamField>
+
+<ParamField path="model" type="str" default="None">
+  Chariot TTS model. Leave unset to use your account default, so a newly
+  released model works without upgrading the package. `settings.model` takes
+  precedence.
+</ParamField>
+
+<ParamField path="speed" type="float" default="None">
+  Speaking rate from `0.5` to `2.0`, where `1.0` is the voice as recorded.
+  Availability is per voice. `settings.speed` takes precedence.
+</ParamField>
+
+<ParamField path="optimize_streaming_latency" type="int" default="0">
+  Latency optimization level from `0` to `4`. `0` applies all quality passes;
+  higher values trade quality passes for lower latency.
+</ParamField>
+
+### Settings
+
+Pass these through `ChariotTTSService.Settings(...)`. They can also be updated
+while the pipeline is running with `TTSUpdateSettingsFrame`.
+
+| Parameter | Type    | Default             | Description                                  |
+| --------- | ------- | ------------------- | -------------------------------------------- |
+| `voice`   | `str`   | stock voice         | Voice UUID.                                  |
+| `model`   | `str`   | account default     | Chariot TTS model.                           |
+| `speed`   | `float` | voice as recorded   | Speaking rate from 0.5 to 2.0.               |
+
+<Note>
+  Voice, model and speed are fixed for the life of a session, because the voice
+  codes they select are sent once at connect. Changing any of them reconnects,
+  which the service handles for you.
+</Note>
+
+<Note>
+  There is no language setting. Any Chariot voice speaks any supported language,
+  so the language of the audio follows the text you send.
+</Note>
+
+## Usage
+
+```python
+import os
+
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.worker import PipelineParams, PipelineWorker
+from pipecat_chariot import ChariotTTSService
+
+tts = ChariotTTSService(
+    api_key=os.getenv("CHARIOT_API_KEY"),
+    settings=ChariotTTSService.Settings(
+        voice=os.getenv("CHARIOT_VOICE_ID"),
+    ),
+)
+
+pipeline = Pipeline(
+    [
+        transport.input(),
+        stt,
+        context_aggregator.user(),
+        llm,
+        tts,
+        transport.output(),
+        context_aggregator.assistant(),
+    ]
+)
+worker = PipelineWorker(pipeline, params=PipelineParams(allow_interruptions=True))
+```
+
+## Interruptions
+
+Chariot's WebSocket API supports neither context IDs nor a cancel message, so the
+service is built on `InterruptibleTTSService`. When the user barges in, the
+socket is closed, which stops server side generation immediately, and the next
+turn reconnects. Nothing needs configuring.
+
+## Compatibility
+
+Last tested with Pipecat v1.10.0 (`pipecat-ai>=1.7,<2`). See the
+[changelog](https://github.com/Chariot-AI/pipecat-chariot/blob/main/CHANGELOG.md)
+for updates.