gfx.toml(8)

💖 gfx.toml — the glow-up config for xrdp(8)'s graphics pipeline 💖

okay bestie, welcome to gfx.toml 💅 this is the config file that runs the Graphics Pipeline Extension for xrdp(8), and it is TOML, which is honestly the cutest config format, no cap. If you need the TOML syntax rundown, the link is down in SEE ALSO, don't worry 🫶

This file has these sections, and yes they're all doing their own little thing:

• [codec] — sets up your preferred codec and encoders for xrdp(8) ✨
• [x264] — all the parameters for the x264 encoder 🎀
• [OpenH264] — all the parameters for the Cisco OpenH264 encoder 🌸

Heads up bestie: all the options and values are case-sensitive, with some exception — and every exception is spelled out below. Read the fine print, it's giving important.

---

✨ CODEC ✨

The [codec] section is where you declare your preferred codec order and your encoder. Options go a little something like this:

• order = <array> — tells xrdp which order to use the codecs in, and your choices are "H.264" and "RFX". Write it as an array of strings, like [ "H.264", "RFX ]. The strings inside the array are case-insensitive (slay), but everything else is still case-sensitive.
• h264_encoder = <string> — pick your fave H.264 encoder: "x264" or "OpenH264". Lowkey this one only kicks in when more than one encoder is enabled at compile time. If only one H.264 encoder is enabled, that one gets used no matter what you put here, periodt. It defaults to "x264" if you don't specify it, or if you specify an encoder that isn't valid. The encoder name is case-insensitive.

---

🌈 X264 🌈

The [x264] section is where you drop the encoding parameters that get passed straight to the x264 encoder. Want the deep lore on each param? Go run x264 --fullhelp, it's all there. The options are:

• preset = <string> — picks a preset encoding setting. Slower presets = higher CPU usage but better screen image quality and lower network bandwidth needed. The available presets are:

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

ngl, presets slower than medium may not be suitable for use with xrdp. Just saying 👀

• tune = <string> — tunes for a source or situation. zerolatency is the most appropriate one for xrdp, fr fr. Available options are:

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

• profile = <string> — picks a profile. Available options are:

main, baseline, high, high10, high422, high444

• vbv_max_bitrate = <integer> — sets the max fill rate for the VBV (Video Buffering Vefifier) buffer, in kbps.
• vbv_buffer_size = <integer> — sets the size of the VBV buffer, in kilobits.
• fps_num = <integer> — sets the fps numerator.
• fps_den = <integer> — sets the fps denominator.
• threads = <integer> — how many CPU threads to use for H.264 encoding per screen (0 means auto). Bestie please evaluate this carefully before you set it, because running out of threads is a whole situation 😭. For example: if 3 users are connected simultaneously with dual screens, xrdp may use up to <threads> * 3 * 2 threads for H.264 encoding. Also note that too many threads can hurt quality. Balance, queen 👑

---

🦋 OPENH264 🦋

The [OpenH264] section holds the encoding parameters that get passed to the OpenH264 encoder. The options are:

• EnableFrameSkip = <boolean> — lets the encoder skip frames so it can keep the bitrate within the limits if it's about to exceed the maximum bitrate set by MaxBitrate.
• TargetBitrate = <integer> — sets the target average bitrate (in bps) that the encoder will try to hit throughout the encoding process.
• MaxBitrate = <integer> — sets an upper limit on the bitrate, in bps.
• MaxFrameRate = <float> — sets the maximum frame rate the encoder will process per second.

---

💜 CONNECTION TYPES 💜

[x264] and [OpenH264] are tables (aka dictionaries, iykyk) that have subtables with connection types in their keys. Like [x264.lan], [OpenH264.wan] — that vibe.

This means you can configure different parameters (bitrate, whatever you want) for the encoder per connection type. The move is: define your default parameter set first, and it gets inherited by all connection types unless you explicitly override it in a specific one.

The available connection types are:

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

Real talk: currently, xrdp does not support connection type autodetection. So if autodetect is selected on the client side, it will be treated as if LAN is selected. That's just how it is 🫠

---

🌟 EXAMPLES 🌟

Here's an example gfx.toml, look at her go:

[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 this data structure in TOML format, and the following two representations are semantically equivalent — BUT the latter one is discouraged because of concerns about complexity and readability. So like, don't 🙈

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

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

---

🎀 SEE ALSO 🎀

For more info on gfx.toml configuration, go check the wiki page:

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

And the syntax for TOML files lives right here:

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

---

that's the whole page, bestie 💖 this was brought to you by the xrdp team, version 0.10.6.1, and it's the gfx.toml(8) manual. go configure something iconic, ily 👑✨