# Pipecat

> Speak Pipecat agent replies in Kalpa voices with the pipecat-kalpa services, over WebSocket or HTTP streaming.

[Pipecat](https://pipecat.ai) is an open-source Python framework for real-time voice and multimodal agents. The [`pipecat-kalpa`](https://github.com/kalpalabs/pipecat-kalpa) community package, maintained by Kalpa Labs, adds two Kalpa text-to-speech services to it, and Pipecat's docs list it as a [community integration](https://docs.pipecat.ai/api-reference/server/services/tts/kalpa) alongside its TTS services:

| Service | Transport | Use it for |
|---|---|---|
| `KalpaTTSService` | [WebSocket](/reference#wss-v1-tts-voice-id-stream) | Most voice agents. Streams the LLM's reply over one connection as it is written, so speech starts before the reply is finished. |
| `KalpaHttpTTSService` | [HTTP streaming](/text-to-speech#streaming-over-http) | One streaming HTTP request per sentence, with no connection held open. |

## Install

The package needs Python 3.11 or later and Pipecat 1.13.x. Install it from [PyPI](https://pypi.org/project/pipecat-kalpa/):

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

Create an API key at [kalpalabs.ai/dashboard/keys](https://kalpalabs.ai/dashboard/keys/) and export it where your agent runs:

```bash
export KALPA_API_KEY=...
```

## Add Kalpa to a pipeline

Place the service after the LLM and before the transport output:

```python
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat_kalpa import KalpaTTSService

tts = KalpaTTSService(api_key=os.environ["KALPA_API_KEY"])

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)
```

`transport`, `stt`, `llm` and the context aggregators are the rest of your application. For HTTP streaming, put `KalpaHttpTTSService(api_key=os.environ["KALPA_API_KEY"])` in the same position.

## Voice and model

Pass `settings` to pick a voice and model:

```python
tts = KalpaTTSService(
    api_key=os.environ["KALPA_API_KEY"],
    settings=KalpaTTSService.Settings(
        voice="dda5319f-3b81-4124-b69e-9241eb510b77",  # Wren
        model="kalpa-tts-1",
    ),
)
```

| Setting | Default | Notes |
|---|---|---|
| `voice` | `18c26f49-9f9c-400c-bec9-7467f28e1db5` (Arjun) | A voice id from `GET /v1/voices` — see [Named voices](/text-to-speech#named-voices). |
| `model` | `kalpa-tts-1` | A model id from `GET /v1/models` — see [Models](/models). |
| `language` | `None` | Guides Pipecat's sentence splitting; it is not sent to Kalpa. |

`KalpaHttpTTSService.Settings` takes the same settings. To change the voice or model mid-session, push a `TTSUpdateSettingsFrame`; the WebSocket service reconnects to apply it.

The constructors also take `base_url` (default `wss://api.kalpalabs.ai` for the WebSocket service, `https://api.kalpalabs.ai` for HTTP). `KalpaTTSService` takes `text_aggregation_mode` (`TextAggregationMode` is in `pipecat.services.tts_service`): the default `TextAggregationMode.TOKEN` forwards LLM text as it arrives, and `SENTENCE` collects whole sentences first. `KalpaHttpTTSService` takes an optional `aiohttp_session` to share.

## Audio and interruptions

Both services produce 24 kHz mono 16-bit PCM. Pipecat's output transport resamples it to your pipeline's output rate, so neither service takes a `sample_rate`.

When the user interrupts, Pipecat stops playback and `KalpaTTSService` cancels the reply still being generated, then keeps the same connection for the next one.

## Run the example agent

The package ships a voice agent that uses Deepgram for speech recognition, OpenAI for replies and Kalpa for speech, and talks to your browser over WebRTC:

```bash
git clone https://github.com/kalpalabs/pipecat-kalpa.git
cd pipecat-kalpa
uv sync --extra examples
cp .env.example .env   # set KALPA_API_KEY, DEEPGRAM_API_KEY and OPENAI_API_KEY
uv run --extra examples python examples/voice.py --transport webrtc
```

Open the address it prints, allow microphone access and connect. Talk over the assistant to interrupt it. Set `KALPA_TTS_TRANSPORT=http` to run the same agent with `KalpaHttpTTSService`, and `KALPA_VOICE_ID` to pick its voice.

## Resources

- [kalpalabs/pipecat-kalpa](https://github.com/kalpalabs/pipecat-kalpa): source, changelog, issues, and the README that tracks the current release and Pipecat compatibility.
- [pipecat-kalpa on PyPI](https://pypi.org/project/pipecat-kalpa/): released versions.
- [Kalpa on docs.pipecat.ai](https://docs.pipecat.ai/api-reference/server/services/tts/kalpa): Pipecat's reference page for both services.