wl-webrtc

Wayland screen capture and encoding tool.

Prerequisites

• Rust toolchain (1.87+; MSRV pinned to match u32::is_multiple_of / Option::is_none_or usage): rustup default stable
• FFmpeg 6.0+ dev libraries with VAAPI support:
  • Arch: pacman -S ffmpeg
  • Ubuntu/Debian: apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libva-dev
  • Fedora: dnf install ffmpeg-devel libva-devel
• Wayland dev libraries:
  • Arch: pacman -S wayland-protocols
  • Ubuntu/Debian: apt install libwayland-dev wayland-protocols
  • Fedora: dnf install wayland-devel wayland-protocols-devel
• DRM dev libraries:
  • Arch: pacman -S libdrm
  • Ubuntu/Debian: apt install libdrm-dev
  • Fedora: dnf install libdrm-devel

Build

cargo build --release

Run

# Basic capture to file
wl-webrtc --output output.mp4

# With custom FPS and bitrate
wl-webrtc --output output.mp4 --fps 60 --bitrate 8000000

# Specify DRM device for hardware encoding
wl-webrtc --output output.mp4 --drm-device /dev/dri/renderD128

# Verbose mode
wl-webrtc --output output.mp4 -v

# WebRTC streaming mode (HTTP signaling server)
wl-webrtc --port 8080 -v

# Force a fresh portal authorization dialog (ignore saved restore token)
wl-webrtc --output output.mp4 --no-persist

# Pin the capture backend instead of auto-detecting
wl-webrtc --output output.mp4 --backend portal    # or: --backend screencopy

CLI Arguments

src/args.rs is the authoritative source. Run wl-webrtc --help for the live list.

Argument	Default	Description
-o, --output	(optional)	Output file path (e.g. output.mp4). Optional when using --port for WebRTC mode.
--output-name	auto	Wayland output name to capture
--fps	30	Target frames per second
--codec	h264	Video codec (h264 only for MVP)
--hw-accel	vaapi	Hardware acceleration method
--drm-device	auto	DRM render device path
--bitrate	auto	Target bitrate in bps
--max-bitrate	8000000	Max bitrate cap for WebRTC mode (caps BWE escalation; no effect in MP4 mode)
--gop-size	auto	Group of Pictures size
-v, --verbose	false	Enable verbose logging
--backend	auto	Capture backend: screencopy (wlroots) or portal (KWin/KDE). Auto-detected if omitted.
--port	0	WebRTC HTTP signaling server port. 0 keeps MP4 file output mode.
--no-persist	false	Force re-authorization (ignore saved portal restore token)
--stats	false	Print per-second pipeline statistics for stutter diagnosis

Capture backends

The tool supports two Wayland capture backends, auto-detected by default:

• wlr-screencopy (preferred when zwlr_screencopy_manager_v1 is advertised): works on wlroots-based compositors (Sway, Hyprland, etc.).
• XDG Portal / PipeWire (fallback when D-Bus ScreenCast is available): works on KWin/KDE and any compositor that implements the XDG Desktop Portal screen-cast protocol. The first run shows an authorization dialog; a restore token is cached under wl-webrtc/portal-restore-token so subsequent runs don't re-prompt (use --no-persist to force a fresh authorization).