Every option can be given either as a command-line flag or as a key in a YAML config file. Command-line arguments always win over the file.

The camera control options are compatible with the official rpicam-apps, so the Raspberry Pi camera control documentation applies here too.

• Camera and Video Input
• Sub-stream
• Audio
• Image Controls
• Recording
• WebRTC
• IPC
• Signaling
• Object Detection and Tracking
• Config File
• Multi-camera

Camera and Video InputCopy Anchor Link

Sub-streamCopy Anchor Link

A second, usually smaller, capture stream from the same camera. Live streaming and recording can each be pointed at either stream, so you can (for example) record at full resolution while streaming a downscaled copy, or feed a small stream to the detector while the viewer still gets the full picture.

The sub-stream is off unless both --sub-width and --sub-height are set. If either exceeds the main stream's dimensions it is clamped to the main stream.

CSI cameras have a sub-stream: libcamera on a Raspberry Pi and libargus on a Jetson. USB cameras (v4l2) and RTSP sources do not, so both consumers read the main stream.

On a Raspberry Pi, use a sub-stream width that is a multiple of 64, such as 640 or 1280.

AudioCopy Anchor Link

Image ControlsCopy Anchor Link

These are available on builds with libcamera support. They have no effect on a V4L2 or libargus camera.

RecordingCopy Anchor Link

See Recording for the directory layout, rotation policy, and the DataChannel commands that drive on-demand capture.

WebRTCCopy Anchor Link

IPCCopy Anchor Link

Bridges WebRTC DataChannels to local Unix sockets. See IPC messages and Gamepad.

SignalingCopy Anchor Link

At least one signaling transport must be enabled or the process exits. See Signaling for the connection flows.

MQTTCopy Anchor Link

WHEPCopy Anchor Link

LiveKitCopy Anchor Link

Cloudflare Realtime SFUCopy Anchor Link

The device API relays the handshake and holds the session a viewer has to pull. See SFU for a worked example.

The App ID and Secret are what let a device handshake with Cloudflare itself instead of going through the relay, and only the sponsor build carries that logic.

Object Detection and TrackingCopy Anchor Link

Available in the sponsor build on NVIDIA Jetson.

Config FileCopy Anchor Link

--config points at a YAML file. Every long-form option is accepted as a key, without the leading --, and boolean flags take true / false.

/path/to/pi-webrtc --config=/path/to/config.yml

A starting point ships as config/config.yml:

# ── Video input ──
camera: libcamera:0
fps: 60
width: 1920
height: 1080

# ── Hardware / encoding ──
hw-accel: true # Set to false on Raspberry Pi 5, which has no hardware encoder
no-adaptive: false

# ── Audio ──
no-audio: true

# ── Device identity ──
uid: your-device-uid

# ── MQTT signaling ──
use-mqtt: true
mqtt-host: your-mqtt-broker.example.com
mqtt-port: 8883
mqtt-username: your-mqtt-username
mqtt-password: your-mqtt-password

# ── IPC ──
enable-ipc: true

# ── Recording ──
record-path: /path/to/recording/output

Things worth knowing:

• Command-line arguments take priority. A flag on the command line overrides the same key in the file, which makes the file a good place for defaults you occasionally override.
• Unknown keys are ignored rather than treated as errors, so a config file can carry comments-as-keys or settings for a newer version without breaking an older binary.
• Only scalar values are read. Nested mappings and sequences are skipped, with the single exception of the sponsor build's cameras: list (see Multiple cameras).

Multi-cameraCopy Anchor Link

Run one process per camera, or, with the sponsor build, all cameras in one process with a cameras: list. See Multiple cameras.

Sponsor BuildCopy Anchor Link

Options marked ^* above are part of the sponsor build. See Sponsors for what is included.