Advanced FFmpeg Configuration
Lists the FFmpeg media backend's configurable features. All the features are a part of the private API and can be changed or removed in the future without confirmation.
Debug the FFmpeg library and the FFmpeg plugin using logs
You can configure advanced FFmpeg log output via environment variables.
QT_FFMPEG_DEBUG=1
setsAV_LOG_DEBUG
log level to the FFmpeg library. The debug log level can give any hint if you assume that the reason for your issue is in the FFmpeg library.QT_LOGGING_RULES="*.ffmpeg.*=true"
turns on Qt developer logs in the FFmpeg plugin. Logging categories in the FFmpeg plugin are usually called "qt.multimedia.ffmpeg.XXX". To see developer logs of the whole Qt Multimedia, setQT_LOGGING_RULES="*.multimedia.*=true"
- If you set both
QT_FFMPEG_DEBUG
andQT_LOGGING_RULES
, all available FFmpeg codecs will be printed out upon the first invocation of decoding or encoding functionality, specifically, QMediaPlayer, QAudioDecoder, or QMediaRecorder. This information can help if Qt Multimedia doesn't find a proper FFmpeg decoder or encoder. We recommend attaching the codecs dump to Qt bug reports if you encounter codec-specific issues.
Enable experimental FFmpeg codecs
FFmpeg exposes a few codecs, Opus or Vorbis for example, as experimental ones. Experimental codecs don't strictly follow the standard and may be unstable. To turn them on, set the environment variable QT_ENABLE_EXPERIMENTAL_CODECS=1
.
Setting allowed network protocols
For security reasons, the FFmpeg library restricts the list of protocols used by other protocols (nested protocols). See the FFmpeg protocols documentation to check out the list of available protocols and for further information. You may explicitly define the protocols whitelist via the environment variable QT_FFMPEG_PROTOCOL_WHITELIST
, for example:
export QT_FFMPEG_PROTOCOL_WHITELIST=file,crypto,rtp,udp
Warning: Note that many nested protocols can cause vulnerabilities as long as you work with untrusted data. Allow only the protocols that comply with your security and business requirements.
Configure hardware acceleration backends
- Explicit decoding and encoding hardware acceleration backends.
The FFmpeg plugin prioritizes the selection of the hardware acceleration backend for decoding and encoding considering availability, stability, efficiency, and implementation details. If the chosen hardware backend doesn't work as expected, you may try to set a custom priority list or disable all the hardware backends via the environment variables
QT_FFMPEG_DECODING_HW_DEVICE_TYPES
andQT_FFMPEG_ENCODING_HW_DEVICE_TYPES
. The list of the hardware backends you can use is: cuda, drm, dxva2, d3d11va, d3d12va, opencl, qsv, vaapi, vdpau, videotoolbox, mediacodec, vulkan. However, available hardware backends depend on the OS, the installed drivers, and the FFmpeg version. Note that some device types, specifically drm, opencl, qsv, vdpau, and vulkan, haven't been tested with Qt Multimedia by the Qt maintainers, so use them at your own risk.Examples:
# Set vdpau or cuda encoding hardware backends export QT_FFMPEG_ENCODING_HW_DEVICE_TYPES=vdpau,cuda # Set only d3d12va decoding hardware backend export QT_FFMPEG_DECODING_HW_DEVICE_TYPES=d3d12va # Disable decoding hw backends (set an empty list) export QT_FFMPEG_DECODING_HW_DEVICE_TYPES=,
- Hardware textures conversion.
GPU-based conversion between decoded video frames and rendered video frames significantly reduces CPU usage, so we strive to utilize the feature with as many hardware backends as possible. If you notice any rendering issues, to detect the reason, try to test rendering without the GPU texture conversion. To disable the GPU textures conversion, set the
QT_DISABLE_HW_TEXTURES_CONVERSION
environment variable to1
:QT_DISABLE_HW_TEXTURES_CONVERSION=1
. WithVAAPI
hardware backend, hardware texture conversion is still not available by default, setQT_XCB_GL_INTEGRATION=xcb_egl
to turn it on. - Allow codec profile mismatch.
If the codec profile does not match the reported capabilities of the hardware, you may ignore the mismatch and allow hardware decoding via
QT_FFMPEG_HW_ALLOW_PROFILE_MISMATCH=1
. Setting this option may be helpful, for example, when you use the hardware accelerated decoding for baseline profile H.264 with theVAAPI
hardware backend, because the most of such streams satisfy the constraints of the existing H.264 hardware decoder.Warning: If the stream is not supported, the enforced hardware decoding can cause entirely incorrect video output.