Skip to content

🚀 Quickstart

Get started with Bubbaloop in minutes.

Prerequisites

  • Linux (tested on Ubuntu 22.04, Jetson)
  • RTSP cameras on your network
  • Pixi package manager
  • Modern browser (Chrome 94+, Edge 94+, or Safari 16.4+)

Installation

1. Install Pixi

curl -fsSL https://pixi.sh/install.sh | sh

Restart your shell

After installing Pixi, restart your terminal or run source ~/.bashrc to update your PATH.

2. Clone the Repository

git clone https://github.com/kornia/bubbaloop.git
cd bubbaloop

3. Install Dependencies

pixi install

This installs all required dependencies including:

  • Rust toolchain
  • GStreamer and plugins
  • Node.js (for dashboard)
  • Build tools (pkg-config, cmake)

4. Build zenoh-bridge-remote-api (automatic)

The bridge is built automatically when you run pixi run bridge for the first time.

Configuration

Create or edit config.yaml with your camera settings:

cameras:
  - name: "entrance"
    url: "rtsp://user:password@192.168.1.100:554/stream1"
    latency: 200

  - name: "backyard"
    url: "rtsp://user:password@192.168.1.101:554/stream1"
    latency: 200

See Configuration for detailed options.

Running

pixi run up

This uses process-compose to launch all services:

  • bridge — Zenoh WebSocket bridge
  • cameras — RTSP camera capture
  • dashboard — React dashboard

Press Ctrl+C to stop all services.

Run services individually

If you prefer separate terminals:

# Terminal 1
pixi run bridge

# Terminal 2
pixi run cameras

# Terminal 3
pixi run dashboard

Visualization

Local: http://localhost:5173 Remote: https://\<your-ip>:5173 (accept self-signed cert)

Connection

The dashboard auto-connects via built-in proxy. Check the header for status:

  • 🟢 Connected — ready to stream
  • 🟡 Connecting — establishing connection
  • 🔴 Error — click ↻ to retry

View Camera Streams

Cameras appear automatically. To add manually:

  1. Click Add Camera
  2. Click ✏️ to edit
  3. Select topic or enter: 0/camera%entrance%compressed/**
  4. Click Save

Dashboard Features

Action How
Add Camera "Add Camera" button
Edit ✏️ icon
Metadata ⓘ icon (shows latency, timestamps)
Remove ✕ icon
Reorder Drag grip handle
Maximize Expand icon

Live Stats

Each camera displays: FPS · frame count · resolution · LIVE/INIT status

Stopping

Press Ctrl+C to gracefully shutdown (stops all services if using pixi run up).

Browser Requirements

Browser Minimum Version Status
Chrome 94+ ✅ Recommended
Edge 94+ ✅ Supported
Safari 16.4+ ✅ Supported
Firefox - ❌ Not supported

Firefox not supported

Firefox does not support the WebCodecs API required for H264 decoding.

Troubleshooting

"WebSocket disconnected"

  • Ensure pixi run bridge is running in Terminal 1
  • Check it's listening on port 10000

"Waiting for keyframe"

  • Verify pixi run cameras is running in Terminal 2
  • Check the camera URL is correct in config.yaml
  • Look at Terminal 2 for error messages

"WebCodecs not supported"

  • Use Chrome 94+, Edge 94+, or Safari 16.4+
  • Access via localhost (secure context required)

Next Steps