Bedrud uses LiveKit to handle real-time video and audio communication. LiveKit provides the SFU (Selective Forwarding Unit) media server, and Bedrud handles authentication, room management, and admin controls.

Embedded vs. External

Bedrud supports two LiveKit deployment modes:

1. Embedded Mode (Default): The backend starts and manages a LiveKit server process internally. No additional infrastructure is required - the backend handles the LiveKit process lifecycle. When server TLS is enabled, TURN/TLS is automatically configured using the server’s certificate.
2. External Mode: Bedrud connects to a separate LiveKit server or cluster. This is useful for horizontal scaling or when using a managed LiveKit Cloud instance.

Configuring External Mode

To use an external LiveKit server, set the following keys in config.yaml:

livekit:
  host: "wss://livekit.example.com:7880"    # Client WebSocket URL (ws:// or wss://)
  internalHost: "https://livekit.example.com:7880"  # Server-to-server API URL
  apiKey: "your-api-key"
  apiSecret: "your-api-secret"
  external: true          # Skip embedded LiveKit startup
  skipTLSVerify: false    # Set true if LiveKit uses self-signed certs

When external is true, Bedrud skips starting the embedded LiveKit binary. The internalHost (for server-to-server API calls) and host (for client WebSocket connections) may differ if your LiveKit server is behind a reverse proxy.

The API key and secret must match the external server’s credentials.

Webhook Configuration (External Only)

When using an external LiveKit server, you must configure webhooks so LiveKit can notify Bedrud of participant disconnects and room closures. Without webhooks, the database state will go stale.

Endpoint: https://<your-domain>/api/livekit/webhook

Authentication: Uses LiveKit’s JWT signing — the same apiKey/apiSecret you configured above. No separate secret needed.

LiveKit Cloud: Settings → Webhooks → Create new webhook. Enter the endpoint URL and select your API key.

Self-hosted LiveKit: Add to your LiveKit YAML config (e.g., livekit.yaml):

webhook:
  urls: ["https://bedrud.example.com/api/livekit/webhook"]
  api_key: "your-api-key"

LiveKit Version Compatibility

Bedrud’s embedded LiveKit mode auto-generates a compatible config. However, if you self-host an external LiveKit server, be aware of breaking changes across LiveKit versions:

• LiveKit v1.12+ removed the top-level tls field from its config. If you were using tls: in your LiveKit YAML, remove it. Configure http:// for internalHost and ws:// for host in Bedrud’s config. TURN TLS is still supported under the turn: section.
• LiveKit v1.11 and earlier support tls: at the top level. Use https:// for internalHost and wss:// for host.

When in doubt, check your LiveKit server version with livekit-server --version and consult the LiveKit release notes.

Embedded Config Generation

When TLS is enabled in embedded mode, Bedrud generates a temporary LiveKit YAML config (/tmp/bedrud-livekit-*.yaml) with:

• TURN enabled, domain auto-set from server.host, udp_port: 3478, tls_port: 5349, and the server’s TLS certificate reused for TURN/TLS
• node_ip resolved via livekit.nodeIP → server.host → outbound IP auto-detection
• bind_addresses omitted (LiveKit binds all interfaces by default)

The temp file is cleaned up when the LiveKit process exits. To bypass auto-generation with a static config, set livekit.configPath or LIVEKIT_CONFIG_PATH.

How It Works

1. Room Creation

When a user creates a room in Bedrud, the server does not create a LiveKit room immediately. LiveKit rooms are created on demand when the first participant joins.

2. Join Tokens

When a user joins a meeting:

1. The frontend sends a request to /api/room/join.

2. The backend verifies the user has permission to join that room.

3. The backend uses its API Key and Secret to generate a signed JWT (Join Token).

4. The token contains:

   • The room name.
   • The user’s identity (display name).
   • Permissions - for example, whether the user can publish audio or share their screen.

5. The frontend receives this token and connects directly to the LiveKit media port (default 7880).

3. Room Controls (Admin)

The backend uses the LiveKit Go SDK to perform administrative actions:

• Kick: Disconnects a participant.
• Mute: Force-mutes a participant’s microphone.
• Permissions: Changes what a participant can do in real-time.

Network Architecture

• API Port (8090/443): Handles HTTP requests and WebSocket signaling for call setup.
• Media Port (7880): Handles video and audio data using WebRTC protocols. ICE/TCP fallback uses port 7881 when UDP is blocked.
• TURN Port (3478 UDP / 5349 TLS): Relays media for clients behind restrictive NATs or firewalls. See TURN Server Guide.

For firewall and port requirements, see WebRTC Connectivity.

Troubleshooting

Startup & Config Crashes

Connectivity

Media & TURN

Webhook & State

Recording (Egress)

🚧 Recording is a planned feature. This guide describes functionality that will be available in a future release.

Bedrud uses LiveKit’s RoomCompositeEgress API to record rooms as MP4 files.

Prerequisites

• Redis — LiveKit egress requires Redis for coordinating egress workers. Without Redis, StartRoomCompositeEgress returns permission errors.

• Egress S3 storage (external mode only) — For embedded mode, the file lives on the LiveKit file server and Bedrud downloads it directly. For external LiveKit, you must configure an egress: section in your LiveKit YAML so recordings are stored to durable S3-compatible storage. Otherwise the produced FileURL is a local path unreachable from Bedrud.

  Example LiveKit YAML:

  egress:
    s3:
      access_key: "your-s3-access-key"
      secret_key: "your-s3-secret-key"
      endpoint: "http://minio:9000"          # S3-compatible endpoint
      bucket: "bedrud-recordings"
      region: "us-east-1"
      force_path_style: true                 # Required for MinIO/RustFS/etc.

Recording Lifecycle

1. Start: Handler calls StartRoomCompositeEgress with a room-scoped JWT (requires RoomRecord: true and Room: <roomName>).
2. Stop: Handler calls StopEgress, transitions recording to processing.
3. Process: Background job (process_recording) downloads the file from LiveKit’s file server or S3 and stores it via ChatUploadStore.
4. Complete: Webhook dispatched (recording.completed) to registered webhooks.

Egress Client: Created at startup via lkutil.NewEgressClient(). If unavailable, recording is disabled but the server starts normally.

Egress API Auth: The JWT used to call StartRoomCompositeEgress / StopEgress must include both RoomRecord: true and Room: <roomName>. LiveKit’s Egress service requires room-scoped permission — bare RoomRecord without a room name returns twirp error unauthenticated: permissions denied.

Download Auth: Recording file URLs get a short-lived (5 min) LiveKit JWT scoped to the specific room for download.

Webhook Event: When a recording completes, a recording.completed event is dispatched to all webhooks subscribed to that event.

See the Recordings API for endpoint details.

Troubleshooting: Recording

See also

• TURN Server Guide - TURN architecture, configuration, TLS, and troubleshooting
• WebRTC Connectivity - full STUN/ICE/TURN/SFU connectivity stack
• Architecture Overview - full system architecture