Files
WiVRn/docs/configuration.md
schlegp 04837ba215 Add Vulkan AV1 video encoder (#1087)
Experimental support, is never automatically selected.
2026-11-16 17:24:08 +01:00

5.7 KiB

Configurable items

Configuration is split between headset and server. Headset contains most configuration, while server has system specific items such as encoders and paths. Files are read from

  • /usr/share/wivrn/config.json (where /usr is selected at configure time with CMAKE_INSTALL_PREFIX)
  • /etc/wivrn/config.json
  • $XDG_CONFIG_HOME/wivrn/config.json or if $XDG_CONFIG_HOME is not set, $HOME/.config/wivrn/config.json.

Files later in the list replace top-level values from previous ones.

If you installed WiVRn from a flatpack, the config is in $HOME/.var/app/io.github.wivrn.wivrn/config/wivrn/config.json.

All elements are optional and have default values.

bit-depth

Default value: 10-bit if supported by the selected codec, encoder and decoder. 8-bit otherwise.

Bit depth of the video. 8-bit is supported by all encoders. 10-bit is supported by vulkan, vaapi and nvenc with h265 or av1 codecs.

encoder

The encoder to use, either a single string or object applied to all streams, or a list of string or objects with values for left, right and alpha. When a string it is used, it is equivalent to the encoder item of the object.

WiVRn encodes each eye separately, and the alpha channel as one for both eyes. Each stream is processed independently, this may use resources more effectively and reduce latency.

encoder

Default value, in order: vulkan if supported, nvenc on Nvidia GPU, vaapi on all other GPU, else x264.

Identifier of the encoder, one of

  • x264: software encoding
  • nvenc: Nvidia hardware encoding
  • vaapi: AMD/Intel hardware encoding
  • vulkan: Vulkan Video encode, cross-vendor hardware encoding

codec

Default value: best supported by both headset and encoder of av1, h264, h265.

One of h264, h265, av1, raw.

Not all encoders support every codec:

  • x264 encoder only supports h264 codec
  • vulkan encoder supports h264, h265 and av1 codecs, but av1 is never selected automatically: it must be requested by setting encoder to vulkan
  • raw encoder only supports raw codec
  • nvenc and vaapi support all codecs, except raw

If nvenc encoder is in use, you can refer to nvidia website to make sure that your GPU supports encoding with the desired codec.

Examples

  1. Simple configuration
{
	"encoder": {
		"encoder": "vaapi",
		"codec": "h265"
	}
}

Use vaapi hardware encoding, h265 video codec (HEVC).

  1. Hardware + software encoder
{
	"encoder": [
		{
			"encoder": "vaapi",
			"codec": "h265",
		},
		{
			"encoder": "x264",
			"codec": "h264",
		},
		{
			"encoder": "vaapi",
			"codec": "h265",
		},
	]
}

Creates a hardware encoder for left eye and transparency, and a software encoder for right eye.

device, only for vaapi

Default value: unset

Manually specify the device for encoding, can be used to offload encode to an iGPU. Device shall be in the form "/dev/dri/renderD128".

options (very advanced), only for vaapi

Default value: unset

Json object of additional options to pass directly to ffmpeg avcodec_open2's option parameter.

application

Default value: unset

An application to start when connection with the headset is established, can be a string or an array of strings if parameters need to be provided.

Example

{
	"application": ["steam", "steam://launch/275850/VR"]
}

Launch No Man's Sky in VR mode on Steam when connection with headset is established.

tcp-only

Default value: false

Only use TCP for communications with the client, this may have increased latency. If false or unset, WiVRn will use both TCP and UDP.

Example

{
	"tcp-only": true
}

publish-service

Default value: avahi

How to publish the service over the network, avahi or null.

If set to null, service will not be published and address has to be entered manually on the headset.

openvr-compat-path

Default value: unset

Provides the path to the directory of an OpenVR compatibility tool (such as OpenComposite).

If unset, WiVRn will autodetect the path of such a tool as usual (see the SteamVR guide).

If set to an null, WiVRn will not manage the OpenVR configuration.

hid-forwarding

Default value: false

Only available when the uinput kernel module is loaded and the user has write access.

Mirrors input devices forwarded from the headset (keyboard, mouse, gamepad) to uinput devices, for applications that do not read them through OpenXR. Which devices are forwarded is chosen on the headset.

A forwarded gamepad is also exposed as a native OpenXR gamepad at /user/gamepad, which needs no permission and is always available. Only the digested controller state is forwarded (buttons, two sticks, analog triggers and a d-pad), so device specific features such as gyro, adaptive triggers or the touchpad are not available.

debug-gui

Default value: false

Only available when built with WIVRN_FEATURE_DEBUG_GUI.

Enables the Monado debug gui.

use-steamvr-lh

Default value: false

Only available when built with WIVRN_FEATURE_STEAMVR_LIGHTHOUSE.

Enables the driver to load SteamVR Lighthouse devices.

lh-max-extrapolation

Default value: unset

Only available when built with WIVRN_FEATURE_STEAMVR_LIGHTHOUSE.

Maximum time in milliseconds that poses may be extrapolated ahead for SteamVR Lighthouse devices.

lh-stick-deadzone

Default value: 0

Only available when built with WIVRN_FEATURE_STEAMVR_LIGHTHOUSE

Applies a deadzone to joysticks on SteamVR controllers (e.g. Index).

port

Default value: 9757

Change the TCP/UDP port used for the connection.

hostname

Default value: unset

If set, overrides the name displayed in the server list.