diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index 6eb91517c..a05964812 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -1,14 +1,52 @@ -## Quickstart - TBD TBD TBD TBD +# Pipecat Quickstart -### Setup +Run your first Pipecat bot in under 5 minutes. This example creates a voice AI bot that you can talk to in your browser. -1. Set up a venv +## Prerequisites + +### Python 3.10+ + +Pipecat requires Python 3.10 or newer. Check your version: + +```bash +python --version +``` + +If you need to upgrade Python, we recommend using a version manager like `uv` or `pyenv`. + +### AI Service API keys + +Pipecat orchestrates different AI services in a pipeline, ensuring low latency communication. In this quickstart example, we'll use: + +- [Deepgram](https://console.deepgram.com/signup) for Speech-to-Text transcriptions +- [OpenAI](https://auth.openai.com/create-account) for LLM inference +- [Cartesia](https://play.cartesia.ai/sign-up) for Text-to-Speech audio generation + +Have your API keys ready. We'll add them to your `.env` shortly. + +## Setup + +1. Set up a virtual environment + +From the root directory of the `pipecat` repo, run: + +```bash +cd examples/quickstart +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate +``` + +> Using `uv`? Create your venv using: `uv venv && source .venv/bin/activate`. 2. Install packages -pip install "pipecat-ai[webrtc,deepgram,openai,cartesia,silero]" \ - "pipecat-ai-small-webrtc-prebuilt" \ - "python-dotenv" +Then, install the requirements: + +```bash +pip install -r requirements.txt +``` + +> Using `uv`? Install requirements using: `uv pip install -r requirements.txt`. 3. Configure environment variables @@ -28,8 +66,25 @@ CARTESIA_API_KEY=your_cartesia_api_key 4. Run the example +Run your bot using: + ```bash python bot.py ``` -Connect to your bot in a browser at http://localhost:7860 +> Using `uv`? Run your bot using: `uv run bot.py`. + +Connect to your bot in a browser at http://localhost:7860. + +> 💡 First run note: The initial startup may take ~10 seconds as Pipecat downloads required models, like the Silero VAD model. + +## 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 + +- **Read the docs**: Check out [Pipecat's docs](https://docs.pipecat.ai/) for guides and reference information. +- **Join Discord**: Join [Pipecat's Discord server](https://discord.gg/pipecat) to get help and learn about what others are building. diff --git a/examples/quickstart/bot.py b/examples/quickstart/bot.py new file mode 100644 index 000000000..3d3b51798 --- /dev/null +++ b/examples/quickstart/bot.py @@ -0,0 +1,102 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +import argparse +import os + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.audio.vad.silero import SileroVADAnalyzer +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineParams, PipelineTask +from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.processors.frameworks.rtvi import RTVIConfig, RTVIObserver, RTVIProcessor +from pipecat.services.cartesia.tts import CartesiaTTSService +from pipecat.services.deepgram.stt import DeepgramSTTService +from pipecat.services.openai.llm import OpenAILLMService +from pipecat.transports.base_transport import BaseTransport, TransportParams + +load_dotenv(override=True) + + +async def run_bot(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): + logger.info(f"Starting bot") + + stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY")) + + tts = CartesiaTTSService( + api_key=os.getenv("CARTESIA_API_KEY"), + voice_id="71a7ad14-091c-4e8e-a314-022ece01c121", # British Reading Lady + ) + + llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY")) + + messages = [ + { + "role": "system", + "content": "You are a friendly AI assistant. Respond naturally and keep your answers conversational.", + }, + ] + + context = OpenAILLMContext(messages) + context_aggregator = llm.create_context_aggregator(context) + + rtvi = RTVIProcessor(config=RTVIConfig(config=[])) + + pipeline = Pipeline( + [ + transport.input(), # Transport user input + rtvi, # RTVI processor + stt, + context_aggregator.user(), # User responses + llm, # LLM + tts, # TTS + transport.output(), # Transport bot output + context_aggregator.assistant(), # Assistant spoken responses + ] + ) + + task = PipelineTask( + pipeline, + params=PipelineParams( + enable_metrics=True, + enable_usage_metrics=True, + ), + observers=[RTVIObserver(rtvi)], + ) + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + logger.info(f"Client connected") + # Kick off the conversation. + messages.append({"role": "system", "content": "Say hello and briefly introduce yourself."}) + await task.queue_frames([context_aggregator.user().get_context_frame()]) + + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + await task.cancel() + + runner = PipelineRunner(handle_sigint=handle_sigint) + + await runner.run(task) + + +if __name__ == "__main__": + from pipecat.runner.local import main + + # SmallWebRTCTransport for a P2P WebRTC connection + transport_params = { + "webrtc": lambda: TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), + } + + main(run_bot, transport_params=transport_params) diff --git a/examples/quickstart/requirements.txt b/examples/quickstart/requirements.txt index b3538b7e9..25fba8ee0 100644 --- a/examples/quickstart/requirements.txt +++ b/examples/quickstart/requirements.txt @@ -1,3 +1,3 @@ -pipecatcloud -pipecat-ai[openai,daily,deepgram,cartesia,silero] -python-dotenv +pipecat-ai[webrtc,silero,deepgram,openai,cartesia] +pipecat-ai-small-webrtc-prebuilt +python-dotenv \ No newline at end of file diff --git a/examples/quickstart/Dockerfile b/examples/runner-examples/Dockerfile similarity index 100% rename from examples/quickstart/Dockerfile rename to examples/runner-examples/Dockerfile diff --git a/examples/quickstart/build.sh b/examples/runner-examples/build.sh similarity index 100% rename from examples/quickstart/build.sh rename to examples/runner-examples/build.sh diff --git a/examples/quickstart/cloud-multi-bot.py b/examples/runner-examples/cloud-multi-bot.py similarity index 100% rename from examples/quickstart/cloud-multi-bot.py rename to examples/runner-examples/cloud-multi-bot.py diff --git a/examples/quickstart/cloud-simple-bot.py b/examples/runner-examples/cloud-simple-bot.py similarity index 100% rename from examples/quickstart/cloud-simple-bot.py rename to examples/runner-examples/cloud-simple-bot.py diff --git a/examples/runner-examples/env.example b/examples/runner-examples/env.example new file mode 100644 index 000000000..b3e882f5d --- /dev/null +++ b/examples/runner-examples/env.example @@ -0,0 +1,3 @@ +DEEPGRAM_API_KEY=your_deepgram_api_key +OPENAI_API_KEY=your_openai_api_key +CARTESIA_API_KEY=your_cartesia_api_key \ No newline at end of file diff --git a/examples/quickstart/local-multi-bot.py b/examples/runner-examples/local-multi-bot.py similarity index 100% rename from examples/quickstart/local-multi-bot.py rename to examples/runner-examples/local-multi-bot.py diff --git a/examples/quickstart/local-simple-bot.py b/examples/runner-examples/local-simple-bot.py similarity index 100% rename from examples/quickstart/local-simple-bot.py rename to examples/runner-examples/local-simple-bot.py diff --git a/examples/quickstart/pcc-deploy.toml b/examples/runner-examples/pcc-deploy.toml similarity index 100% rename from examples/quickstart/pcc-deploy.toml rename to examples/runner-examples/pcc-deploy.toml diff --git a/examples/runner-examples/requirements.txt b/examples/runner-examples/requirements.txt new file mode 100644 index 000000000..182ac8324 --- /dev/null +++ b/examples/runner-examples/requirements.txt @@ -0,0 +1,4 @@ +pipecatcloud +pipecat-ai[openai,daily,deepgram,cartesia,silero] +python-dotenv +pipecat-ai-small-webrtc-prebuilt \ No newline at end of file