Encoding Encodings

Xpra supports a wide variety of picture and video encodings for sending the window contents to the client fast and efficiently.
For some background information on picture encodings, see https://images.guide/.

Choosing which encoding to use for a given window is best left to the xpra engine.
It will make this decision using the window's characteristics (size, state, metadata, etc), network performance (latency, congestion, etc), user preference, client and server capabilities and performance, etc

Generally, if any tuning is needed, instead of trying to guess what should be used and overriding the encodings and encoding options, it is best to use the min-speed and min-quality options instead.

The xpra configure encodings is designed to help you do exactly that. Use it first and only try other options later.


Encodings:

The following pseudo encodings just control which actual encodings can be selected by the engine:

You can select the pseudo-encoding using the --encoding=ENC switch.

| Codename | Bit Depths | Characteristics | Details | |----------|------------------------------------------|-----------------|-----------------------------------------------------------------------------| | mmap | all | fastest | only available with local connections, selected automatically | | rgb | all | very fast | raw RGB pixels, potentially compressed with a stream compressor (ie: lz4) | | webp | 24 / 32 | good | fast, supports transparency, lossy and lossless modes | | jpeg | 24 | fast | easy to support | | avif | 24 | average | limited support | | png | 24 / 32 | slow | easy to support | | png/P | 8 | slow | only useful for 8-bit desktop mode | | png/L | 8 | slow | greyscale |

Using a video stream is often the most efficient way of sending large amounts of screen updates without consuming too much bandwidth. The xpra engine should automatically detect when it makes sense to switch to a video codec.

| Codename | Bit Depths | Characteristics | |----------|------------------------------------------|------------------------------------| | vp8 | 24 | fast but less efficient | | vp9 | 24 / 30 | more efficient but somewhat slower | | h264 | 24 / 30 | licensing issues | | hevc | 24 / 30 | licensing issues - usually slower |

Which ones of these video encodings are available depends on the video encoders enabled:

Video Encoders

Xpra ships the following encoder modules:

| Codename | Encodings supported | Notes | |---------------------|---------------------|-----------------------------| | vpx | vp8, vp9 | | x264 | h264 | fast | | nvenc | h264, hevc | fastest (requires hardware) |

Which encodings are actually supported by each encoder may vary, depending on the version used, the build options, hardware capabilities, etc.

You can choose which video encoders are loaded at runtime using the video-encoders option.

Some of these video encoders may require a colorspace conversion step:

These modules are used for:

| Codename | Colorspaces supported | Notes | |-----------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------| | cython | r210, BGR48, GBRP10, YUV444P10 | slow but useful for some high bit depth modes | | libyuv | BGRX, YUV420P, NV12 | fastest |

You can choose which colorspace conversion modules are loaded at runtime using the csc-modules option.

Xpra ships the following decoder modules: |Codename|Encodings supported| |--------|-------------------| |openh264|h264| |vpx|vp8, vp9|

You can choose which video decoders are loaded at runtime using the video-decoders option.

Diagnostics

xpra encoding

(on MS Windows and MacOS, you can also use the Encodings_info wrapper)

xpra video
xpra attach --encoding=help
xpra start --encoding=help
xpra start -d damage,compress,encoding

Tuning

Warning: tuning is very often misused and ends up being counterproductive.

Rather than selecting a lossless picture encoding, which may use far too much bandwidth and cause performance issues:

Acceptable values range from 1 (lowest) to 100 (lossless).
Rather than tuning the quality option, it is almost always preferable to set the min-quality instead.
Using lower values saves bandwidth and CPU, but the screen updates may become more blurry.

Acceptable values range from 1 (lowest) to 100 (lossless).
Rather than tuning the speed option, it is almost always preferable to set the min-speed instead.
Using lower values costs more CPU, which reduces bandwidth consumption but may also lower the framerate.

The best possible setup is to use NVENC or another hardware encoder supported by libva: hardware encoders compress very well and do so incredibly fast.

When comparing performance, make sure that you use the right metrics...
The number of updates per second (aka fps) is not always a good one: if there are many small regions, this can be a good or a bad thing.