Client/Server Web Example

Learn how to build web applications using Pipecat's client/server architecture. This approach separates your bot logic from your user interface, giving you full control over the client experience while maintaining real-time voice communication.

This example demonstrates:

• Server-side bot running with Pipecat
• React client using Pipecat's client SDK
• Real-time voice communication between client and server
• UI components from voice-ui-kit for common voice interface patterns

This is the recommended architecture for web applications that need custom interfaces or client-side functionality.

Prerequisites

• Python 3.10+
• uv package manager installed
• npm installed
• AI Service API keys for: Deepgram, OpenAI, and Cartesia

Setup

This example requires running both a server and client in two separate terminal windows.

Clone this repository

git clone https://github.com/pipecat-ai/pipecat-quickstart-client-server.git
cd pipecat-quickstart-client-server

Terminal 1: Server Setup

1. Configure environment variables

   Create a .env file:

   cp env.example .env

   Then, add your API keys:

   DEEPGRAM_API_KEY=your_deepgram_api_key
   OPENAI_API_KEY=your_openai_api_key
   CARTESIA_API_KEY=your_cartesia_api_key
   

   You can optionally provide a DAILY_API_KEY for using the DailyTransport when running locally.

2. Set up a virtual environment and install dependencies

   uv sync

3. Run your server bot

   uv run bot.py

   💡 First run note: The initial startup may take ~15 seconds as Pipecat downloads required models, like the Silero VAD model.

Terminal 2: Client Setup

1. Open a new terminal window and navigate to the client folder:

   From the pipecat-quickstart-client-server directory, run:

   cd client

2. Install dependencies:

   npm i

3. Run the client:

   npm run dev

Connect and test

Open http://localhost:5173 in your browser and click Connect to start talking to your bot.

💡 Tip: Check your server terminal for debug logs showing Pipecat's internal workings.

Deploy to Pipecat Cloud

You can deploy your bot to Pipecat Cloud. For guidance, follow the steps outlining in the pipecat-quickstart's Deployment section.

Troubleshooting

• Browser permissions: Make sure to allow microphone access when prompted by your browser.
• Connection issues: If the WebRTC connection fails, first try a different browser. If that fails, make sure you don't have a VPN or firewall rules blocking traffic. WebRTC uses UDP to communicate.
• Audio issues: Check that your microphone and speakers are working and not muted.

Next Steps

• Explore the client SDK: Learn more about Pipecat's client SDKs for web, mobile, and other platforms
• Learn about the voice-ui-kit: Explore voice-ui-kit to simplify your front end development
• Advanced examples: Check out pipecat-examples for more complex client/server applications
• Join Discord: Connect with other developers on Discord