Set Up

Installation

0. Clone Repository

If you haven't already, clone the repository and navigate to it:

git clone https://github.com/Meeting-Baas/speaking-meeting-bot.git
cd speaking-meeting-bot

1. Prerequisites

Python 3.11+
grpc_tools for protocol buffer compilation
Ngrok for local development (follow our Ngrok Setup Guide)
Poetry for dependency management

You'll also need system dependencies for scientific libraries:

# macOS (using Homebrew)
brew install llvm cython

# Ubuntu/Debian
sudo apt-get install llvm python3-dev cython

# Fedora/RHEL
sudo dnf install llvm-devel python3-devel Cython

2. Set Up Poetry Environment

# Install Poetry (Unix/macOS)
curl -sSL https://install.python-poetry.org | python3 -

# Install Poetry (Windows)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

# Configure Poetry to use Python 3.11+
poetry env use python3.11

# Install dependencies with LLVM config path
# On macOS:
LLVM_CONFIG=$(brew --prefix llvm)/bin/llvm-config poetry install
# On Linux (path may vary):
# LLVM_CONFIG=/usr/bin/llvm-config poetry install

# Activate virtual environment
poetry shell

3. Compile Protocol Buffers

poetry run python -m grpc_tools.protoc --proto_path=./protobufs --python_out=./protobufs frames.proto

Protocol Buffers are used here by Pipecat to define a structured message format for real-time communication between components of the Speaking Bots system. Specifically, the frames.proto file defines three main message types:

TextFrame: For handling text-based messages
AudioRawFrame: For managing raw audio data with properties like sample rate and channels
TranscriptionFrame: For handling speech-to-text transcription results

Protocol Buffers is the backbone of consistent data serialization across services. Read more in the official Protocol Buffer documentation and this Python Protocol Buffers tutorial.

4. Configure Environment

Create a .env file based on the template:

cp env.example .env

Edit the .env file with your API keys. You'll need:

Required API Keys:

MEETING_BAAS_API_KEY: For meeting platform integration
OPENAI_API_KEY: For the conversation LLM
CARTESIA_API_KEY: For text-to-speech
GLADIA_API_KEY or DEEPGRAM_API_KEY: For speech-to-text

For production, also set:

BASE_URL=https://your-server-domain.com

See our full Environment Variables Guide for more details.

5. Run the API Server

The project now follows an API-first approach. There are two ways to run the server:

# Standard mode
poetry run uvicorn app:app --reload --host 0.0.0.0 --port 8766

# Local development mode with ngrok auto-configuration
poetry run python run.py --local-dev

Once the server is running, you can access:

Interactive API docs: http://localhost:8766/docs
OpenAPI specification: http://localhost:8766/openapi.json

To create a bot via the API:

curl -X POST http://localhost:8766/run-bots \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_url": "https://meet.google.com/xxx-yyyy-zzz",
    "personas": ["interviewer"],
    "meeting_baas_api_key": "your-api-key"
  }'

You can also use our CLI tools for testing:

poetry run python scripts/batch.py -c 1 --meeting-url LINK

Follow our Command Line Guide for more examples and options.