Kalpa Text-to-Speech

Community-maintained integration. This service is built and maintained by Kalpa Labs. Pipecat does not test or officially support it. Please report issues and request changes on the source repository. Learn more about community integrations.

Overview

KalpaTTSService converts text to speech through Kalpa’s streaming WebSocket API. KalpaHttpTTSService uses the HTTP streaming API. Kalpa Labs maintains both services in pipecat-kalpa. For a walkthrough of TTS in a pipeline, see Text-to-Speech.

Source Repository

Source code, runnable examples, changelog, and issues

Kalpa API Documentation

Current models, voices, and HTTP and WebSocket API behavior

The package README is the source of truth for the integration’s examples and release compatibility.

Installation

Install the community package from its versioned Git release:

uv add "pipecat-kalpa @ git+https://github.com/kalpalabs/pipecat-kalpa.git@v0.1.0"

Prerequisites

Create an API key in the Kalpa dashboard.

Required Environment Variables

KALPA_API_KEY: Your Kalpa API key.

Import the service classes from the community package:

from pipecat_kalpa import KalpaHttpTTSService, KalpaTTSService

Configuration

KalpaTTSService

str

required

Kalpa API key. Raises ValueError when empty.

str

default:"wss://api.kalpalabs.ai"

WebSocket base URL for the Kalpa API.

TextAggregationMode

default:"TextAggregationMode.TOKEN"

How incoming text is aggregated before synthesis. TOKEN forwards LLM text as it arrives; SENTENCE aggregates sentences first. Import from pipecat.services.tts_service.

KalpaTTSService.Settings | None

default:"None"

Runtime-configurable settings. See Settings.

KalpaHttpTTSService

str

required

Kalpa API key. Raises ValueError when empty.

str

default:"https://api.kalpalabs.ai"

HTTP base URL for the Kalpa API.

aiohttp.ClientSession | None

default:"None"

Shared HTTP session. When None, the service creates and closes its own session. You are responsible for closing a session you provide.

KalpaHttpTTSService.Settings | None

default:"None"

Runtime-configurable settings. See Settings.

Settings

Pass settings through KalpaTTSService.Settings(...) or KalpaHttpTTSService.Settings(...). Both expose the following settings:

Parameter	Type	Default	Description
`model`	`str \| None`	`"kalpa-tts-1"`	Public model ID. See Kalpa models.
`voice`	`str \| None`	`"18c26f49-9f9c-400c-bec9-7467f28e1db5"`	Named voice ID, defaulting to Arjun. Select a voice offered for your model from Kalpa’s voice catalog.
`language`	`Language \| str \| None`	`None`	Guides Pipecat’s sentence splitting. It is not sent to Kalpa.

Use a TTSUpdateSettingsFrame to change settings during a conversation. Updating model or voice reconnects the WebSocket service.

Usage

Add Kalpa to a Voice Pipeline

Place the service after your LLM and before the transport output. This example uses your existing transport, STT, LLM, and context aggregators:

import os

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

tts = KalpaTTSService(api_key=os.getenv("KALPA_API_KEY"))

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

For a complete runnable example, follow the voice agent example and its instructions in the package README.

Use HTTP Synthesis

Use the HTTP service in the same pipeline position:

import os

from pipecat_kalpa import KalpaHttpTTSService

tts = KalpaHttpTTSService(api_key=os.getenv("KALPA_API_KEY"))

Notes

Audio format: Both services produce 24 kHz mono PCM audio. The output transport resamples it to the pipeline’s output rate.
Interruptions: Use Pipecat’s interruption handling to stop playback when the user interrupts. KalpaTTSService cancels the interrupted response and reuses the connection for subsequent speech.

Event Handlers

KalpaTTSService supports the standard service connection events:

Event	Description
`on_connected`	The WebSocket connection is open.
`on_disconnected`	The WebSocket connection is closed.
`on_connection_error`	A WebSocket connection error occurs.

Compatibility

Tested with Pipecat 1.13.0 on Python 3.12. Requires Python 3.11 or later and Pipecat 1.13.x (>=1.13.0,<1.14.0).

Demo

Watch the Pipecat + Kalpa TTS 1 demo. The browser conversation includes English and Hindi speech, a spoken interruption, and timestamped Pipecat events.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Kalpa Text-to-Speech

Overview

Source Repository

Kalpa API Documentation

Installation

Prerequisites

Required Environment Variables

Configuration

KalpaTTSService

KalpaHttpTTSService

Settings

Usage

Add Kalpa to a Voice Pipeline

Use HTTP Synthesis

Notes

Event Handlers

Compatibility

Demo

​Overview

Source Repository

Kalpa API Documentation

​Installation

​Prerequisites

​Required Environment Variables

​Configuration

​KalpaTTSService

​KalpaHttpTTSService

​Settings

​Usage

​Add Kalpa to a Voice Pipeline

​Use HTTP Synthesis

​Notes

​Event Handlers

​Compatibility

​Demo

Overview

Installation

Prerequisites

Required Environment Variables

Configuration

KalpaTTSService

KalpaHttpTTSService

Settings

Usage

Add Kalpa to a Voice Pipeline

Use HTTP Synthesis

Notes

Event Handlers

Compatibility

Demo