Signaling

Before two WebRTC peers can send media they have to exchange an SDP offer/answer and a set of ICE candidates. pi-webrtc can do that over three signaling transports, and more than one can be enabled at a time. If none is enabled the process exits — there would be no way to reach it.

All three are configured in Configuration.

MQTTCopy Anchor Link

pi-webrtc registers with the broker at startup and waits for a client to start the handshake. Use HiveMQ, EMQX, or a self-hosted broker.

/path/to/pi-webrtc --camera=libcamera:0 \
  --fps=30 \
  --width=1280 \
  --height=960 \
  --use-mqtt \
  --mqtt-host=your.mqtt.cloud \
  --mqtt-port=8883 \
  --mqtt-username=hakunamatata \
  --mqtt-password=Wonderful \
  --uid=home-pi-5 \
  --no-audio

Topics are namespaced by --uid. Below, --uid=home-pi-5 and ${mqttId} is a random id the client generates to identify its own connection, so several clients can talk to one device at once.

sequenceDiagram
Note over pi-webrtc, mqtt server: sub: home-pi-5/sdp/+/offer<br>sub: home-pi-5/ice/+/offer

client--> pi-webrtc: start connecting

Note over client, mqtt server: sub: home-pi-5/sdp/${mqttId}<br>sub: home-pi-5/ice/${mqttId}

client ->> mqtt server: client's SDP
Note over client, mqtt server: pub: home-pi-5/sdp/${mqttId}/offer

mqtt server ->> pi-webrtc: client's SDP

pi-webrtc ->> mqtt server : pi's SDP
Note over pi-webrtc, mqtt server: pub: home-pi-5/sdp/${mqttId}

mqtt server ->> client: pi's SDP

client ->> mqtt server: client's ICE
Note over client, mqtt server: pub: home-pi-5/ice/${mqttId}/offer

mqtt server ->> pi-webrtc: client's ICE

pi-webrtc ->> mqtt server : pi's ICE
Note over pi-webrtc, mqtt server: pub: home-pi-5/ice/${mqttId}

mqtt server ->> client: pi's ICE
client ->pi-webrtc: connected

Clients:

• client-sdk-js
• picamera-web (Web demo)
• picamera-app (Android demo)

WHEPCopy Anchor Link

Play WebRTC streams directly using a WHEP standard URL, with no third-party broker or registration.

/path/to/pi-webrtc --camera=libcamera:0 \
  --fps=30 \
  --width=1280 \
  --height=960 \
  --use-whep \
  --whep-port=8080 \
  --uid=home-pi-5 \
  --no-audio

Clients:

• Home Assistant WebRTC Camera (see using-the-webrtc-camera-in-home-assistant)
• eyevinn/webrtc-player (see WHEP with webrtc-player)

SFUCopy Anchor Link

With MQTT or WHEP, each viewer connects directly to the device. More viewers means more connections, bandwidth, and encoding load on the device.

With an SFU, the device sends the stream once, and the SFU forwards it to all viewers. See broadcasting to many viewers for a worked example.

Supported SFU backends:

• LiveKit — self-hosted, or LiveKit cloud.
• Cloudflare Realtime — fully managed by Cloudflare.

Client:

• client-sdk-js
• livekit-sdk