Quick Start

Everything needed to get a stream running, from a blank SD card to a picture in the browser. Check out the tutorial video for a walkthrough.

• Requirements
• MQTT broker
• Raspberry Pi setup
• Jetson setup
• Camera setup
• Browser connection
• Common errors
• Troubleshooting

Requirements複製段落連結

Releases are built per OS release, so the package names and the tarball have to match the system. Check yours with cat /etc/os-release on a Pi, or head -n 1 /etc/nv_tegra_release on a Jetson.

MQTT broker複製段落連結

Signaling is how the device and the browser exchange the SDP and ICE needed to open a WebRTC connection. With MQTT it works from anywhere, with no public IP and no port forwarding. Skip this section if you only want the local WHEP test.

Pick one:

• HiveMQ Cloud — free tier, nothing to host. Create a cluster, add a user under Access Management, and note the cluster URL.
• EMQX — free tier as well.
• Self-hosted Mosquitto — on your own machine.

Two ports matter, and they are different:

Putting 8883 into the browser is the single most common mistake — see Common errors.

Raspberry Pi setup複製段落連結

1. Flash Raspberry Pi OS Lite (64-bit) with the Raspberry Pi Imager, enabling SSH and WiFi in the Imager's settings.

2. Install dependencies:

   複製

   sudo apt update
   sudo apt install libmosquitto1 pulseaudio libavformat61 libswscale8 libyaml-cpp0.8

3. Download the latest release and confirm it runs:

   複製

   wget https://github.com/mazupo/pi-webrtc/releases/latest/download/pi-webrtc_raspios-trixie-arm64.tar.gz
   tar -xzf pi-webrtc_raspios-trixie-arm64.tar.gz
   ./pi-webrtc -h

   The option list should print. A cannot execute binary file or missing-library error means the release does not match the OS.

4. Test locally over WHEP, with no broker involved:

   複製

   ./pi-webrtc --camera=libcamera:0 --uid=home-pi-5 --no-audio --use-whep

   Open app.mazupo.com/whep, put http://<your-pi-ip>:8080 in the WHEP URL field, and connect. Get the IP with hostname -I.

   Load that player over http, not https. The device answers over plain HTTP, so an https player page makes the request mixed content, which browsers either block outright or gate behind a local-network permission prompt.

5. Once that works, switch to MQTT for remote access:

   複製

   ./pi-webrtc \
       --camera=libcamera:0 \
       --fps=60 \
       --width=1280 \
       --height=720 \
       --use-mqtt \
       --mqtt-host=example.s1.eu.hivemq.cloud \
       --mqtt-port=8883 \
       --mqtt-username=your-username \
       --mqtt-password=your-password \
       --uid=home-pi-5 \
       --no-audio \
       --hw-accel

   --uid is any name you choose. It namespaces the MQTT topics ({uid}/sdp/..., {uid}/ice/...), so the browser has to use exactly the same value, and anyone holding it plus the broker credentials can reach the device.

   The device is ready when the log shows MQTT connected to broker ... followed by MQTT service is ready., then goes quiet waiting for a viewer. Continue to Browser connection.

To start it automatically on boot, see Running as a Linux Service.

Jetson setup複製段落連結

Tested on JetPack 6 (L4T R36).

1. Install dependencies:

   複製

   sudo apt update
   sudo apt install libmosquitto1 pulseaudio libyaml-cpp0.7 libboost-program-options1.74.0

   JetPack already ships NVIDIA's own ffmpeg package, which bundles the libavformat and libswscale shared libraries, so those are not listed here. Do not install Ubuntu's libavformat58 / libswscale5 on top — they claim the same file paths as NVIDIA's build.

2. Check your L4T version, then download the matching pi-webrtc_jetson-l4t-<version>.tar.gz from the releases:

   複製

   head -n 1 /etc/nv_tegra_release   # e.g. "# R36 (release), REVISION: 5.2" → 36.5.2
   tar -xzf pi-webrtc_jetson-l4t-<version>.tar.gz
   ./pi-webrtc -h

3. Run with a CSI camera through libargus. There is no libcamera backend on Jetson; USB cameras use --camera=v4l2:<id>.

   複製

   ./pi-webrtc \
       --camera=libargus:0 \
       --fps=60 \
       --width=1280 \
       --height=720 \
       --use-mqtt \
       --mqtt-host=example.s1.eu.hivemq.cloud \
       --mqtt-port=8883 \
       --mqtt-username=your-username \
       --mqtt-password=your-password \
       --uid=jetson-1 \
       --no-audio \
       --hw-accel

Camera setup複製段落連結

--camera takes a <backend>:<id> string. Asking for a backend the platform does not have is a startup error.

CSI camera on a Raspberry Pi複製段落連結

Keep the default camera_auto_detect=1 in /boot/firmware/config.txt. The <id> is the camera's position, so the only attached camera is libcamera:0, and a second one on a Pi 5 is libcamera:1.

libcamera only produces yuv420, so --v4l2-format is ignored. Resolution and frame rate are usually limited by the MIPI link rather than the sensor — see Camera and Encoding.

USB camera複製段落連結

On a modern Raspberry Pi OS and on JetPack, USB cameras appear as V4L2 devices with no configuration. Find the /dev/videoX node and check what it supports:

v4l2-ctl --list-devices
v4l2-ctl -d /dev/videoX --list-formats-ext

Then pass the index and one of the listed formats (i420, yuyv, mjpeg, or h264). For a camera on /dev/video2 doing YUYV 720p60:

./pi-webrtc --camera=v4l2:2 --v4l2-format=yuyv --fps=60 --width=1280 --height=720 ...

Picking mjpeg or h264 where the camera offers it moves the compression onto the camera and saves both USB bandwidth and CPU.

CSI camera through the legacy V4L2 driver複製段落連結

You probably do not need this. It is only for driving a CSI camera through the legacy driver instead of libcamera, and it turns USB auto-detection off.

1. Edit /boot/firmware/config.txt:

   複製

   # camera_auto_detect=1  # Default setting
   camera_auto_detect=0    # Turn off default libcamera

2. Run with --camera=v4l2:0 for the camera at /dev/video0:

   複製

   ./pi-webrtc --camera=v4l2:0 \
       --v4l2-format=mjpeg \
       --fps=60 \
       --width=1280 \
       --height=720 \
       --uid=home-pi-5 \
       --no-audio \
       --hw-accel

Browser connection複製段落連結

Open the demo web and fill in:

Several browsers can connect to one device at the same time; each generates its own client id.

Other clients: client-sdk-js to build your own, picamera-app on Android, or Home Assistant over WHEP.

Common errors複製段落連結

Troubleshooting複製段落連結

See every available option. The full flag list, with defaults, comes from the binary itself:

./pi-webrtc -h

List the USB cameras the system can see, independently of pi-webrtc:

v4l2-ctl --list-devices

Confirm the WHEP port is reachable from another machine on the LAN. Anything other than a connection refusal means the device side is serving:

curl -v http://<your-pi-ip>:8080

Check the broker independently of pi-webrtc, to separate credential problems from everything else:

mosquitto_sub -h example.s1.eu.hivemq.cloud -p 8883 --capath /etc/ssl/certs/ \
  -u your-username -P your-password -t 'home-pi-5/#' -v

Reduce the problem. Drop to --width=640 --height=480 --fps=30 and add --no-audio. If a smaller stream connects, the issue is bandwidth or encoding rather than signaling.

Still stuck? Open an issue with the full command, the log output, and the device and OS versions.

Next複製段落連結

• Configuration — every flag and the YAML config file
• Camera and Encoding — backends, formats, and bandwidth
• Signaling — MQTT, WHEP, and SFU compared
• Recording — MP4 files and snapshots
• Advanced Usage — SFU, two-way audio, DataChannels, running as a service