Advanced FFmpeg Configuration

This page 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. Be aware that environment variables are by default inherited by child processes and can have unintended consequences.

Enable logging from FFmpeg and the Qt FFmpeg media backend

You can configure advanced FFmpeg log output via environment variables.

• QT_FFMPEG_DEBUG=1 enables extra logging from the FFmpeg library and can help you understand issues that involve 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 enable developer logs from all of Qt Multimedia, set QT_LOGGING_RULES="*.multimedia.*=true"
• If you set both QT_FFMPEG_DEBUG and QT_LOGGING_RULES, all available FFmpeg codecs will be printed the first time encoding or decoding functionality is used from QMediaPlayer, QAudioDecoder, or QMediaRecorder. This information can help you understand situations where Qt Multimedia doesn't find a proper FFmpeg decoder or encoder. We recommend attaching the codec dump to Qt bug reports if you encounter codec-specific issues.

Enable experimental FFmpeg codecs

FFmpeg exposes a few codecs, such as Opus or Vorbis, as experimental ones. Experimental codecs don't strictly follow the standard and may be unstable. They are disabled by default. To enable them, set the environment variable QT_ENABLE_EXPERIMENTAL_CODECS=1.

Configuring allowed network protocols

For security reasons, the FFmpeg library restricts use of nested protocols, meaning protocols used by other protocols; see FFmpeg protocols documentation. You may explicitly override the allowed protocols via the environment variable QT_FFMPEG_PROTOCOL_WHITELIST, for example:

 export QT_FFMPEG_PROTOCOL_WHITELIST=file,crypto,rtp,udp

Configure hardware acceleration in backends

• Explicit decoding and encoding hardware acceleration backends.

  The FFmpeg plugin chooses the hardware acceleration backend for decoding and encoding based on availability, stability, efficiency, and implementation details. If the selected hardware backend doesn't work as expected, you can try setting a custom priority list or disable all the hardware backends via the environment variables QT_FFMPEG_DECODING_HW_DEVICE_TYPES and QT_FFMPEG_ENCODING_HW_DEVICE_TYPES. The available hardware backends include:

  • cuda
  • drm
  • dxva2
  • d3d11va
  • d3d12va,
  • opencl
  • qsv
  • vaapi
  • vdpau
  • videotoolbox
  • mediacodec
  • vulkan

  However, the availability of hardware backends depends on the OS, installed drivers, the FFmpeg version, and configuration. It's important to keep in mind that some device types have not been tested with Qt Multimedia by the Qt maintainers, and may not operate as intended. At the time of writing, these backends include:

  • drm
  • opencl
  • qsv
  • vdpau
  • vulkan

  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.

  Utilizing GPU-based conversion for decoded and rendered video frames can significantly reduce CPU usage. We aim to make use of this reature feature with as many hardware backends as possible. If you notice any rendering issues, consider testing the rendering without GPU texture conversion to identify the cause. You can disable GPU texture conversion by using the QT_DISABLE_HW_TEXTURES_CONVERSION environment variable: QT_DISABLE_HW_TEXTURES_CONVERSION=1. With the VAAPI hardware backend, hardware texture conversion is disabled by default. Set QT_XCB_GL_INTEGRATION=xcb_egl to enable it.

• 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 the VAAPI hardware backend because 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.