This wiki provides comprehensive information on configuring and using thepi-webrtc for video streaming, along with detailed technical insights on encoders, signaling protocols, and recording options.

• Architecture
• Flags
• Camera Mode
  • V4L2
  • Libcamera
• Encoding Mode
  • Hardware (V4L2 H264)
  • Software (H264/VP8/VP9/AV1)
• Signaling
  • MQTT
  • WHEP
  • WebSocket
• Recording
• Misc
  • Make Timelapse Video from .jpg Files
  • Useful Commands
  • Use the Eclipse Mosquitto debian repository

The camera control options are fully compatible with officialrpicam-apps. Just follow theinstructions.

Available flags forpi-webrtc:

There are two ways to read images from the camera. TheV4L2 only supports the v1 and v2 cameras and the HQ camera. After Camera Module 3, future updates will be based onLibcamera.

In general, the USB camera will be detected as a v4l2 device while using default setting.This is for older camera module on Pi OS (beforeBookworm) want to be read via v4l2, please modify thecamera_auto_detect=1 flag in file/boot/firmware/config.txt to

# camera_auto_detect=1camera_auto_detect=0start_x=1gpu_mem=256

Setcamera_auto_detect=0 in order to read CSI camera by V4L2. The size ofgpu_mem depends on desired resolution,256MB for 1080p.

This is the Raspberry Pi officially recommended way to read the camera.

Use the default settingcamera_auto_detect=1 in/boot/firmware/config.txt.In this project, Libcamera only provides theyuv420 format, and the--v4l2-format flags will be disabled.Sinceyuv420 is an uncompressed format, you should check the bandwidth of the CSI/USB interface to ensure the camera can handle high resolution and frame rate images.Each MIPI lane provides 1.5 Gbps bandwidth on the Pi 5, but each MIPI lane provides 1 Gbps on earlier models. [ref]

For example:

YUV 4:2:0 need 12 bits/pixel. 4Kp60 = 3840 x 2160 x 60 x 12 = 5.56 Gbps.

The encoder used in WebRTC depends on whether the--hw-accel flag is set and the SDP context offered by the client. I recommend runningv4l2-ctl -d /dev/video0 --list-formats-ext to check which formats your camera supports before specifying the V4L2 source format, allowing you to choose the most suitable encoding mode.

Hardware H264 encoding is only available on the Raspberry Pi 3, 4, and Zero 2. The Raspberry Pi 5 no longer supports the hardware encoder. For other single-board computers, such as Radxa, Odroid, etc., H264 hardware encoding may be supported according to their specifications. However, if their codecs do not implement the V4L2 driver, it is recommended to useSoftware encoding instead. The Raspberry Pi codec device files are located at [ref]:

pi-webrtc only listH264 codecs in theSDP while running with the--hw-accel flag.

• Forh264 camera source

  /path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=h264 --fps=30 --width=1280 --height=960 --hw-accel ...

  graph LRA(Camera) -- h264 --> B(hw decoder) -- yuv420 --> C(hw scaler) --yuv420--> D(hw encoder) --h264-->E(webrtc client)A --h264--> F(mp4)

  Loading

  This command grabs theh264 stream directly from the camera and uses the hardware decoder to convert it toyuv420. If WebRTC detects network or device performance issues, the hardware scaler will automatically adjust by scaling down the decodedyuv420 frame resolution, and vice versa when conditions improve. When the resolution changes, the hardware encoder will be reset to match the new resolution. All frame data is transferred via DMA (zero-copy) between hardware codecs. Furthermore, if the--record-path flag is set (enabling recording), theh264 packets from the camera are directly copied into MP4 files.

• Formjpeg camera source

  /path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=mjpeg --fps=30 --width=1280 --height=960 --hw-accel ...

  graph LRA(camera) -- mjpeg --> B(hw decoder) -- yuv420 --> C(hw scaler) --yuv420--> D(hw encoder) --h264-->E(webrtc client)B --yuv420--> F(openh264) -- h264--> G(mp4)

  Loading

  All processes are similar to theh264 source camera in hardware mode. The main difference isOpenH264 software encoder will be used in video recording.

• Fori420 camera source

  # use v4l2 camera/path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=i420 --fps=30 --width=1280 --height=960 --hw-accel ...# use libcamera/path/to/pi-webrtc --camera=libcamera:0 --fps=30 --width=1280 --height=960 --hw-accel ...

  graph LRA(camera) -- yuv420 --> C(hw scaler) --yuv420--> D(hw encoder) --h264-->E(webrtc client)A --yuv420--> F(openh264) -- h264--> G(mp4)

  Loading

  This command captures uncompressedyuv420 from the camera. Since it is uncompressed, the CSI/USB bandwidth may not support high resolution and fps.i420 is useful when running on a Pi Zero or if CPU usage is excessively high due to many background services. TheOpenH264 software encoder will be used for video recording, but this method is typically chosen because of limited system resources, and the recorder is usually not enabled.

pi-webrtc will list allH264,VP8,VP9 andAV1 codecs in theSDP while running without the--hw-accel flag. The encoder used depends on theSDP provided by the client. For example, if the client'sSDP only includes H264, WebRTC will use theH264 encoder for live streaming. Make sure the client'sSDP contains the only codec you want to use."

• Forh264 camera source

  /path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=h264 --fps=30 --width=1280 --height=960 ...

  It's not available inpi-webrtc. I didn't implement H264 software decoding.

• Formjpeg camera source

  /path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=mjpeg --fps=30 --width=1280 --height=960 ...

  graph LRA(camera) -- mjpeg --> B(libyuv) -- yuv420 --> C(libyuv scaler) --yuv420--> D(openh264) --h264-->E(webrtc client)B --yuv420--> F(openh264) -- h264--> G(mp4)

  Loading

  It's suitable for most devices that do not support the V4L2 hardware encoder.Themjpeg frames will be decoded intoyuv420 bylibyuv. If WebRTC requires a lower resolution for live streaming, the scaling will also be handled bylibyuv. The recording will use separate instances of theOpenH264 encoder.

• Fori420 camera source

  # use v4l2 camera/path/to/pi-webrtc --camera=v4l2:0 --v4l2-format=i420 --fps=30 --width=1280 --height=960  ...# use libcamera/path/to/pi-webrtc --camera=libcamera:0 --fps=30 --width=1280 --height=960 ...

  graph LRA(camera) -- yuv420 --> C(libyuv scaler) --yuv420--> D(openh264) --h264-->E(webrtc client)A --yuv420--> F(openh264) -- h264--> G(mp4)

  Loading

  It's suitable for devices do not support the V4L2 hardware encoder, but it provides a very high CSI/USB bandwidth.

pi-webrtc registers itself with theMQTT server at the beginning and waits for theapp client to send a request to initiate the connection. The diagram below shows how the connection process operates between theapp client,MQTT server, andpi-webrtc. Assume that the--uid=home-pi-5, and${mqttId} is another random UID used to identify each MQTT connection.

/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

sequenceDiagramNote over pi-webrtc, mqtt server: sub: home-pi-5/sdp/+/offer<br>sub: home-pi-5/ice/+/offerclient--> pi-webrtc: start connectingNote over client, mqtt server: sub: home-pi-5/sdp/${mqttId}<br>sub: home-pi-5/ice/${mqttId}client ->> mqtt server: client's SDPNote over client, mqtt server: pub: home-pi-5/sdp/${mqttId}/offermqtt server ->> pi-webrtc: client's SDPpi-webrtc ->> mqtt server : pi's SDPNote over pi-webrtc, mqtt server: pub: home-pi-5/sdp/${mqttId}mqtt server ->> client: pi's SDPclient ->> mqtt server: client's ICENote over client, mqtt server: pub: home-pi-5/ice/${mqttId}/offermqtt server ->> pi-webrtc: client's ICEpi-webrtc ->> mqtt server : pi's ICENote over pi-webrtc, mqtt server: pub: home-pi-5/ice/${mqttId}mqtt server ->> client: pi's ICEclient ->pi-webrtc: connected

You can play the video directly using a URL likehttps://your.ddns-to-pi.net byWHEP player without server registration. This allows you to stream video like a traditional RTSP/RTMP stream using a simple URL.Most of web require TLS/SSL, you might neednginx proxy.

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

sequenceDiagram    participant Server as pi-webrtc    participant Client as WHEP Player    Client->>Server: client's SDP/ICE    Note over Client, Server: POST to `https://your.ddns-to-pi.net`    Server->>Client: pi's SDP/ICE    Note over Client, Server: 201 Created    Client->Server: connected

The websocket is designed to connect with a SFU (Selective Forwarding Unit) server.

The video files will be recorded every minute, and each video file will generate a snapshot image for preview. If the disk space falls below400MB, it will start rotation.

This will create a 30fps MP4 timelapse video from all.jpg images under a specific folder, including subfolders.

Usefind andsed to recursively list all.jpg files and format them in a way thatffmpeg expects (file '...' per line):

find /mnt/ext_disk/video/20250509/ -type f -iname"*.jpg"| sort| sed"s/^/file '/; s/$/'/"> file_list.txt

This ensures all files are listed in order and quoted properly (required byffmpeg -f concat).

ffmpeg -f concat -safe 0 -i file_list.txt -r 30 -c:v libx264 -pix_fmt yuv420p timelapse.mp4

• -f concat: Tells ffmpeg to read input from the list file.
• -safe 0: Allows using absolute paths.
• -r 30: Sets the output frame rate to 30fps.
• -c:v libx264: Encodes the video with H.264 codec.
• -pix_fmt yuv420p: Ensures compatibility with most players (e.g., browsers, mobile devices).

The result will be saved astimelapse.mp4 in the current directory.

Please follow officialReadme.txt to use the latest mosquitto packages.