KugelAudio provides an official TTS service for PipeCat , enabling high-quality voice synthesis in your voice AI pipelines.
Why Use KugelAudio with PipeCat?
Native service: Drop-in TTSService for PipeCat pipelinesWebSocket streaming: Real-time audio generation via WebSocketBuilt-in metrics: Automatic TTFB and usage metrics trackingUltra-low latency: ~39ms time-to-first-audio with kugel-1-turbo
Installation pip install kugelaudio[pipecat]
This installs the KugelAudio SDK along with the required PipeCat dependency (pipecat-ai>=0.0.60).
The PipeCat integration requires Python 3.10 or higher.
Quick Start Basic Pipeline from pipecat.pipeline.pipeline import Pipeline from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineTask from kugelaudio.pipecat import KugelAudioTTSService # Create the TTS service tts = KugelAudioTTSService( api_key = "your-api-key" , model = "kugel-1-turbo" , voice_id = 280 , sample_rate = 24000 , ) # Use in a PipeCat pipeline pipeline = Pipeline([ transport.input(), # Audio/text input stt, # Speech-to-text llm, # Language model tts, # KugelAudio TTS transport.output(), # Audio output ]) task = PipelineTask(pipeline) await runner.run(task)
Set the KUGELAUDIO_API_KEY environment variable or pass api_key directly to the constructor.
Configuration Service Parameters Parameter Type Default Description api_keystrKUGELAUDIO_API_KEY envYour KugelAudio API key modelstrkugel-1-turboTTS model (kugel-1-turbo or kugel-1) voice_idint | NoneNoneVoice ID to use (server default if None) sample_rateint24000Output sample rate in Hz cfg_scalefloat2.0CFG scale for generation quality max_new_tokensint2048Maximum tokens to generate base_urlstrhttps://api.kugelaudio.comAPI base URL aiohttp_sessionClientSession | NoneNoneOptional aiohttp session to reuse
Supported Sample Rates Rate Notes 24000Native rate (recommended) 22050CD quality 16000Wideband telephony 8000Narrowband telephony
Use the native 24000 Hz sample rate for best quality and lowest latency. Lower rates use server-side resampling with minimal impact (~0.1ms per chunk).
Models Model Parameters Latency Quality Use Case kugel-1-turbo1.5B ~39ms TTFA High Real-time conversations kugel-17B ~77ms TTFA Exceptional Premium quality applications
Usage Patterns Updating Voice and Model at Runtime You can change the voice or model dynamically during a pipeline session:
tts = KugelAudioTTSService( model = "kugel-1-turbo" , voice_id = 280 , ) # Switch voice mid-conversation tts.set_voice( "300" ) # Switch to higher quality model await tts.set_model( "kugel-1" )
Pipeline Frame Flow The KugelAudioTTSService emits standard PipeCat frames:
TTSStartedFrame - Audio generation has begunTTSAudioRawFrame - Raw PCM audio chunks (16-bit, mono)TTSStoppedFrame - Audio generation is completeErrorFrame - If an error occurs during synthesis
from pipecat.frames.frames import ( TTSStartedFrame, TTSAudioRawFrame, TTSStoppedFrame, ) # The TTS service yields frames in this order: # TTSStartedFrame -> TTSAudioRawFrame* -> TTSStoppedFrame
Metrics Support KugelAudio’s PipeCat service automatically tracks performance metrics:
tts = KugelAudioTTSService( model = "kugel-1-turbo" , voice_id = 280 , ) # Metrics are tracked automatically: # - TTFB (Time to First Byte): measured from request to first audio chunk # - TTS Usage: character count per request print (tts.can_generate_metrics()) # True
Custom aiohttp Session For advanced connection management, pass a custom aiohttp session:
import aiohttp # Create a session with custom settings session = aiohttp.ClientSession( timeout = aiohttp.ClientTimeout( total = 120 ), connector = aiohttp.TCPConnector( limit = 10 ), ) tts = KugelAudioTTSService( model = "kugel-1-turbo" , aiohttp_session = session, )
Complete Voice Bot Example Here’s a complete voice bot using PipeCat with Daily as the transport:
import asyncio import os from pipecat.pipeline.pipeline import Pipeline from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineTask from pipecat.transports.services.daily import DailyTransport, DailyParams from pipecat.services.openai import OpenAILLMService from pipecat.services.deepgram import DeepgramSTTService from kugelaudio.pipecat import KugelAudioTTSService async def main (): # Transport (Daily WebRTC) transport = DailyTransport( room_url = os.environ[ "DAILY_ROOM_URL" ], token = os.environ[ "DAILY_TOKEN" ], bot_name = "KugelAudio Bot" , params = DailyParams( audio_out_sample_rate = 24000 ), ) # STT stt = DeepgramSTTService( api_key = os.environ[ "DEEPGRAM_API_KEY" ]) # LLM llm = OpenAILLMService( api_key = os.environ[ "OPENAI_API_KEY" ], model = "gpt-4o-mini" , ) # TTS - KugelAudio tts = KugelAudioTTSService( model = "kugel-1-turbo" , voice_id = 280 , sample_rate = 24000 , ) # Build pipeline pipeline = Pipeline([ transport.input(), stt, llm, tts, transport.output(), ]) runner = PipelineRunner() task = PipelineTask(pipeline) await runner.run(task) if __name__ == "__main__" : asyncio.run(main())
Running the Bot # Set environment variables export KUGELAUDIO_API_KEY = "your-api-key" export DAILY_ROOM_URL = "https://your-domain.daily.co/room" export DAILY_TOKEN = "your-daily-token" export DEEPGRAM_API_KEY = "your-deepgram-key" export OPENAI_API_KEY = "your-openai-key" # Run the bot python voice_bot.py
Environment Variables Variable Required Description KUGELAUDIO_API_KEYYes Your KugelAudio API key DAILY_ROOM_URLYes* Daily room URL (if using Daily transport) DAILY_TOKENYes* Daily room token DEEPGRAM_API_KEYYes* Required if using Deepgram STT OPENAI_API_KEYYes* Required if using OpenAI LLM
Troubleshooting
Make sure KUGELAUDIO_API_KEY is set in your environment or pass api_key directly: tts = KugelAudioTTSService( api_key = "your-api-key" )
Unsupported sample rate error
KugelAudio supports these sample rates: 24000, 22050, 16000, 8000. Make sure your transport output sample rate matches: # Both must match tts = KugelAudioTTSService( sample_rate = 24000 ) transport = DailyTransport( params = DailyParams( audio_out_sample_rate = 24000 ), )
WebSocket connection fails
Verify your base_url is correct and the KugelAudio API is reachable. The service connects via WebSocket (wss://) for audio streaming.
Python version incompatibility
The PipeCat integration requires Python 3.10 or higher. Check your version: Next Steps 
