gfx.toml(8) gfx.toml(8)
gfx.toml - Configuration file for xrdp(8) graphics pipeline extension
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
[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.
threads = <integer>
Specify how many CPU threads to use for H.264 encoding per
screen (0 for auto). Carefully evaluate this value when
configuring it to avoid exhausting the available threads. For
example, if 3 users are connected simultaneously with dual
screens, xrdp may use up to <threads> * 3 * 2 threads for
H.264 encoding. Please also note that too many threads can
hurt quality.
OPENH264
[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>
xrdp team 0.10.5 gfx.toml(8)
NAME
gfx.toml - Configuration file for xrdp(8) graphics pipeline extension
DESCRIPTION
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
[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
[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.
threads = <integer>
Specify how many CPU threads to use for H.264 encoding per
screen (0 for auto). Carefully evaluate this value when
configuring it to avoid exhausting the available threads. For
example, if 3 users are connected simultaneously with dual
screens, xrdp may use up to <threads> * 3 * 2 threads for
H.264 encoding. Please also note that too many threads can
hurt quality.
OPENH264
[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.
CONNECTION TYPES
[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.
EXAMPLES
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" } }
SEE ALSO
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>
xrdp team 0.10.5 gfx.toml(8)