Configuration

The agent uses a configuration file to control capture, encoding, and connection behaviour. Most settings have sensible defaults and do not need to be changed.

Config File Location

~/.config/vdo/config.toml

If the file does not exist, the agent runs with defaults. You can create it to override specific settings.

Capture Settings

[capture]
# Which display to capture (default: auto-detected primary)
display = 0

# Preferred capture method: "auto", "x11", or "kms"
# "auto" tries hardware capture first, then falls back
backend = "auto"

• display -- The index of the display to capture by default. 0 is usually the primary monitor. Connected viewers can switch displays from the toolbar.
• backend -- The capture backend. "auto" is recommended. Use "kms" to force direct hardware capture (requires appropriate permissions) or "x11" for X11 shared memory capture.

Encoding Settings

[encode]
# Preferred codec: "hevc" or "h264"
codec = "hevc"

# Target bitrate in kbps (0 = automatic based on resolution)
bitrate = 0

# Capture framerate
framerate = 60

# Force a specific encoder: "auto", "nvenc", "vaapi", "x264"
encoder = "auto"

• codec -- HEVC provides better quality at the same bitrate. H.264 has wider compatibility.
• bitrate -- Leave at 0 for automatic bitrate selection based on resolution and quality preset. Set a value in kbps to override (e.g., 20000 for 20 Mbps).
• framerate -- Maximum capture framerate. The actual framerate may be lower depending on system performance.
• encoder -- "auto" selects the best available hardware encoder. Force "nvenc" for NVIDIA, "vaapi" for AMD/Intel, or "x264" for CPU-only encoding.

Runtime Escape Hatches

Most hosts should stay on automatic selection. Use environment overrides only to work around a specific field issue, then remove them after upgrading.

Variable	Values	When to use
VDO_AUDIO_MODE	native, pw-record, parec	Force an audio backend. With no override, the agent uses auto selection and can degrade Rocky 9 / PipeWire combinations known to be unstable to parec.
VDO_NVENC_MODE	auto, dmabuf, zerocopy, copy	Control NVIDIA DMA-BUF zero-copy. copy is an in-field kill switch for driver-specific zero-copy issues, not a recommended global default.

To set an override for the user service:

mkdir -p ~/.config/systemd/user/vdo-agent.service.d
cat > ~/.config/systemd/user/vdo-agent.service.d/override.conf <<'EOF'
[Service]
Environment=VDO_AUDIO_MODE=parec
# Environment=VDO_NVENC_MODE=copy
EOF
systemctl --user daemon-reload
systemctl --user restart vdo-agent

Only keep the lines you need. Delete the override file and restart the service to return to automatic selection.

Quality Presets

Viewers can select a quality preset from the session toolbar. These presets adjust encoding parameters on the fly:

Preset	Best For
LAN	Local network, maximum quality
WAN	Internet connections, balanced quality/bandwidth
Review	Colour-accurate review work
Colour Accurate	Professional colour grading
Speed	Lowest latency, lower quality

Presets are selected by the viewer and do not require any agent configuration.

Applying Changes

After editing config.toml, restart the agent:

systemctl --user restart vdo-agent