BigBlueButton STT Agent for LiveKit

This application provides Speech-to-Text (STT) for BigBlueButton meetings using LiveKit as their audio bridge.

Initially, the only supported STT engine is Gladia through the official LiveKit Gladia Plugin.

It'll be expanded in the future to support other STT plugins from the LiveKit Agents ecosystem.

Getting Started

Environment prerequisites

• Python 3.10+
• A LiveKit instance
• A Gladia API key
• uv:
  • See installation instructions: https://docs.astral.sh/uv/getting-started/installation/

Installing

1. Clone the repository:

   git clone git@github.com:bigbluebutton/bbb-livekit-stt.git
   cd bbb-livekit-stt

2. Install the dependencies:

   uv sync

3. Configure environment variables:

   Copy the example .env file:

   cp .env.example .env

   Now, edit the .env file and fill at least the following environment vars:

   LIVEKIT_URL=...
   LIVEKIT_API_KEY=...
   LIVEKIT_API_SECRET=...
   
   # Gladia API Key
   GLADIA_API_KEY=...
   

   Feel free to check .env.example for any other configurations of interest.

   All options ingested by the Gladia STT plugin are exposed via env vars.

Running

The agent is run using the command-line interface provided by the livekit-agents library. The necessary environment variables will be picked up automatically.

Once started, the worker will connect to your LiveKit server and wait to be assigned to rooms. By default, the LiveKit server will dispatch a job to the worker for every new room created. The agent will then join the room, start listening to audio tracks, and generate transcription events when required.

Development

For development, use the dev command.

uv run python3 main.py dev

Production

For production, use the start command.

uv run python3 main.py start

Docker

Build the image:

docker build . -t bbb-livekit-stt

Run:

docker run --network host --rm -it --env-file .env bbb-livekit-stt

Pre-built images are available via GitHub Container Registry as well.

Development

Testing

Run the unit tests:

uv run pytest tests/ --ignore=tests/integration

Run with coverage:

uv run pytest tests/ --ignore=tests/integration --cov --cov-report=term-missing

Integration tests require a real Gladia API key and make live requests to the Gladia service. Set GLADIA_API_KEY and run:

GLADIA_API_KEY=your-key uv run pytest tests/integration -m integration

Linting

This project uses ruff for linting and formatting. To check for issues:

uv run ruff check .

To automatically fix fixable issues:

uv run ruff check --fix .

To format the code:

uv run ruff format .