Skip to content

Pipecat SDK · pipecat-pyai v0.1.2

Natural speech inside your Pipecat pipeline.

Plug PyAI speech services into the transport and LLM pipeline you already use.

Use PyAISTTService and PyAITTSService as pipeline processors.
Receive TTSAudioRawFrame output for your audio transport.
Keep your existing LLM, context aggregators, and application logic.

From download to working audio

Python 3.10–3.13. Only a PyAI key for the included text-to-WAV pipeline. A conversational bot additionally needs a Pipecat transport and an LLM; follow the linked integration guide.

Terminal · macOS / Linux
curl -fSL https://pyai.com/starters/pyai-pipecat.tar.gz -o pyai-pipecat.tar.gz
tar -xzf pyai-pipecat.tar.gz
cd pyai-pipecat
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
# Fill in .env, then export its values in this shell:
set -a
. ./.env
set +a
python main.py

Edit the downloaded .env before running. Keep it out of Git. On Windows, use WSL for these shell commands.

What happens when you run it?

The downloadable starter is a complete text-to-audio pipeline. It does not open a microphone, room, or phone call.

Take it into your application

Choose a voice from the API catalog and check its language coverage. Reuse clients, consume streaming audio immediately, and cancel interrupted responses. PCM, WAV and G.711 stream; MP3 and Opus are buffered.

The complete entry point

This is the same file included in the download. Copy it here, or get the full project with its dependency and environment files.

main.py
"""A complete text-to-audio Pipecat pipeline; no transport or LLM account needed."""
import asyncio
import os
import time
import wave
from pipecat.frames.frames import EndFrame, Frame, TTSAudioRawFrame, TTSSpeakFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
from pipecat_pyai import PyAITTSService


class SaveAudio(FrameProcessor):
    def __init__(self, output):
        super().__init__()
        self.output = output
        self.received = 0
        self.started = time.perf_counter()

    async def process_frame(self, frame: Frame, direction: FrameDirection):
        await super().process_frame(frame, direction)
        if isinstance(frame, TTSAudioRawFrame):
            if not self.received:
                print(f"First audio frame: {(time.perf_counter() - self.started) * 1000:.0f} ms")
            self.output.writeframesraw(frame.audio)
            self.received += len(frame.audio)
        await self.push_frame(frame, direction)


async def main():
    with wave.open("speech.wav", "wb") as output:
        output.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
        sink = SaveAudio(output)
        tts = PyAITTSService(voice=os.getenv("PYAI_VOICE", "stock_emma_en_gb"))
        task = PipelineTask(Pipeline([tts, sink]), params=PipelineParams(audio_out_sample_rate=24000))
        await task.queue_frames([TTSSpeakFrame("Hello from PyAI and Pipecat."), EndFrame()])
        await PipelineRunner().run(task)
        if not sink.received:
            raise RuntimeError("No audio frames received")
        print("Saved speech.wav")


if __name__ == "__main__":
    asyncio.run(main())

Build with Pipecat in your coding agent

Install Node.js 22+ and your coding agent first. Connect PyAI’s MCP server, then ask it to call get_started. For a sandbox test, ask it to call create_sandbox_key once. Keep live credentials in your environment.

Codex · terminal
codex mcp add pyai -- npx -y @pyai/mcp@0.2.0
Claude Code · terminal
claude mcp add --transport stdio --scope project pyai -- npx -y @pyai/mcp@0.2.0
Cursor · .cursor/mcp.json
{
  "mcpServers": {
    "pyai": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@pyai/mcp@0.2.0"
      ]
    }
  }
}

Merge the pyai entry into your existing mcpServers configuration. Enable it in Cursor’s MCP settings.

Paste into your coding agent
Read https://pyai.com/skill.md and https://pyai.com/sdks/pipecat.md.
Use the matching starter to add PyAI voice to this project.
Keep credentials in environment variables. Run a short synthetic
audio test and report the result and any missing credentials.
Do not place a phone call or send a message unless I ask.

Want a reusable local skill? Copy the Codex and Claude Code skill install commands. Any tool that reads Markdown can use skill.md.

Pipecat SDK questions

What is included in the download?

The Pipecat starter includes its complete entry point, pinned PyAI package version, dependency manifest, environment template, and run instructions.

What do I need before running it?

Only a PyAI key for the included text-to-WAV pipeline. A conversational bot additionally needs a Pipecat transport and an LLM; follow the linked integration guide.

Can I use this with Cursor, Codex or Claude Code?

Yes. Connect the PyAI MCP server and give your agent the Pipecat Markdown guide. It includes the complete starter source and setup commands.

How do I test streaming performance?

Measure first received audio and playback readiness separately in your application. Network location, load, text, and voice affect timing. Playing the saved file does not measure streaming latency.

← Explore all SDKs