gfx.toml - Man Page

This file configures the detailed settings of the Graphics Pipeline Extension for xrdp(8). The file format is TOML. See the link in the See Also section for TOML syntax.

The file contains following sections:

[codec] - configure preferred codec and encoders for xrdp(8).

[x264] - parameters for x264 encoder.

[OpenH264] - parameters for Cisco OpenH264 encoder.

All options and values are case-sensitive, with some exception, and are described in detail below.

[codec] section defines preferred codec order and encoder. The options to be specified in this section are the following:

order = <array>

Define the order in which codecs should be used, "H.264" and "RFX". Specify as an array of strings like [ "H.264", "RFX ]. Strings in the array are case-insensitive, while others are case-sensitive.

h264_encoder = <string>

Specify a preferred H.264 encoder, "x264" or "OpenH264". This parameter takes effect only when more than one encoder is enabled at compile time. If only one H.264 encoder is enabled, the encoder will be used regardless the value of this parameter. Defaults to "x264" if not specified or if an invalid encoder is specified. The encoder name is case-insensitive.

[x264] section defines encoding parameters that will be passed to x264 encoder. See x264 --fullhelp for the detailed explanations of the parameters. The options to be specified in this section are following:

preset = <string>

Select a preset encoding settings. Slower presets result in higher CPU usage but offer better screen image quality and require lower network bandwidth. Here are available presets:

ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo

Presets slower than medium may not suitable for use with xrdp.

tune = <string>

Select a tune for source or situation. zerolatency is most appropriate for use with xrdp. Here are available options:

film, grain, stillimage, psnr, ssim, fastdecode, zerolatency

profile = <string>

Select a profile.  Here are available options:

main, baseline, high, high10, high422, high444

vbv_max_bitrate = <integer>

Set the maximum fill rate for the VBV (Video Buffering Vefifier) buffer in kbps.

vbv_buffer_size = <integer>

Set the size of the VBV buffer size in kilobits.

fps_num = <integer>

Set the fps numerator.

fps_den = <integer>

Set the fps denominator.

[OpenH264] section defines encoding parameters that will be passed to OpenH264 encoder. The options to be specified in this section are following:

EnableFrameSkip = <boolean>

Allows the encoder to skip frames in order to keep the bitrate within the limits if it is about to exceed the maximum bitrate set by MaxBitrate.

TargetBitrate = <integer>

Sets the target average bitrate (in bps) that the encoder will attempt to achieve throughout the encoding process.

MaxBitrate = <integer>

Sets an upper limit of the bitrate in bps.

MaxFrameRate = <float>

Sets the maximum frame rate that the encoder will process per second.

[x264] and [OpenH264] section are tables (also known as dictionaries) that have subtables with connection types in their keys. For example, [x264.lan], [OpenH264.wan].

You can configure different parameters such as bitrate for the encoder per connection type. Define the default parameter set first, this will be inherited to all connection types unless explicitly overridden in each connection type.

List of available connection types are:

lan, wan, broadband_high, satellite, broadband_low, modem, and default

Currently, xrdp does not support connection type autodetection. If autodetect is selected on the client side, it will be treated as if LAN is selected.

This is an example gfx.toml:

[codec]
order = [ "H.264", "RFX" ]
h264_encoder = "x264"

[x264.default]
preset = "ultrafast"
tune = "zerolatency"
profile = "main"     # profile is forced to baseline if preset == ultrafast
vbv_max_bitrate = 0
vbv_buffer_size = 0
fps_num = 60
fps_den = 1

[x264.lan]
# inherits default, everything is same with the default
[x264.wan]
# parameters that are not explicitly overridden inherit the default values
preset = "veryfast"
vbv_max_bitrate = 15_000
vbv_buffer_size = 1_500

There are multiple ways to represent the data structure in TOML format. The following two representations are semantically equivalent but the latter is  discouraged due to concerns about complexity and readability.

[x264.default]
preset = "ultrafast"
tune = "zerolatency"

x264 = { default = { preset = "ultrafast", tune="zerolatency" } }

For more information on gfx.toml configuration, see the wiki page.

https://github.com/neutrinolabs/xrdp/wiki/H.264-encoding

The syntax for TOML files can be found at the following page.

https://toml.io/en/v1.0.0