FFmpeg 高级配置

本页面列出了 FFmpeg 媒体后端的可配置功能。所有功能均属于私有 API，未来可能会在未经确认的情况下进行更改或移除。请注意，环境变量默认会被子进程继承，这可能会导致意想不到的后果。

启用 FFmpeg 及 Qt FFmpeg 媒体后端的日志记录

您可以通过环境变量配置 FFmpeg 的高级日志输出。

• QT_FFMPEG_DEBUG=1 可启用 FFmpeg 库的额外日志记录，并有助于您理解涉及 FFmpeg 库的问题。
• QT_LOGGING_RULES="*.ffmpeg.*=true" 启用 FFmpeg 插件中的 Qt 开发者日志。FFmpeg 插件中的日志类别通常命名为“qt.multimedia.ffmpeg.XXX”。若要启用Qt Multimedia 下的所有开发者日志，请设置QT_LOGGING_RULES="*.multimedia.*=true"
• 如果您同时设置了QT_FFMPEG_DEBUG 和QT_LOGGING_RULES ，则首次通过QMediaPlayer 、QAudioDecoder 或QMediaRecorder 调用编码或解码功能时，系统将打印所有可用的FFmpeg编解码器。这些信息有助于您理解Qt Multimedia 无法找到合适的FFmpeg解码器或编码器的情况。 如果您遇到与编解码器相关的具体问题，建议将编解码器转储文件作为附件提交至 Qt 错误报告中。

启用实验性 FFmpeg 编解码器

FFmpeg 将某些编解码器（如 Opus 或 Vorbis）列为实验性编解码器。实验性编解码器并不严格遵循标准，且可能不稳定。它们默认处于禁用状态。要启用它们，请设置环境变量QT_ENABLE_EXPERIMENTAL_CODECS=1 。

配置允许的网络协议

出于安全考虑，FFmpeg 库限制了嵌套协议（即被其他协议所使用的协议）的使用；请参阅FFmpeg 协议文档。您可以通过环境变量 `QT_FFMPEG_PROTOCOL_WHITELIST` 显式覆盖允许的协议，例如：

export QT_FFMPEG_PROTOCOL_WHITELIST=file,crypto,rtp,udp

配置 RTSP 传输

通过设置QT_FFMPEG_RTSP_TRANSPORT 环境变量，可以使用特定的FFmpeg RTSP底层传输协议打开RTSP输入流。该值将作为参数传递给FFmpeg的rtsp_transport 输入选项，用于处理rtsp:// 格式的URL。例如，在RTSP控制信道中使用TCP交织：

export QT_FFMPEG_RTSP_TRANSPORT=tcp

常见值包括udp 、tcp 、udp_multicast 、http 和https ；请参阅FFmpeg 的 RTSP 协议文档。该选项默认未设置，且对于非 RTSP 媒体源将被忽略。

在后端中配置硬件加速

• 显式指定解码和编码的硬件加速后端。

  FFmpeg 插件会根据可用性、稳定性、效率和实现细节来选择用于解码和编码的硬件加速后端。如果选定的硬件后端未按预期工作，您可以尝试设置自定义优先级列表，或通过环境变量QT_FFMPEG_DECODING_HW_DEVICE_TYPES 和QT_FFMPEG_ENCODING_HW_DEVICE_TYPES 禁用所有硬件后端。可用的硬件后端包括：

  • cuda
  • drm
  • dxva2
  • d3d11va
  • d3d12va,
  • OpenCL
  • QSV
  • VAAPI
  • vdpau
  • 视频工具箱
  • 媒体编解码器
  • Vulkan

  不过，硬件后端的可用性取决于操作系统、已安装的驱动程序、FFmpeg 版本以及配置。需要注意的是，某些设备类型尚未经过 Qt 维护人员使用Qt Multimedia 进行测试，因此可能无法按预期运行。在撰写本文时，这些后端包括：

  • drm
  • opencl
  • qsv
  • vdpau
  • Vulkan

  示例：

  # 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=,

• 硬件纹理转换。

  利用基于 GPU 的转换来处理已解码和渲染的视频帧，可以显著降低 CPU 占用率。 我们的目标是尽可能在更多硬件后端上利用此功能。如果您发现任何渲染问题，请考虑在不启用 GPU 纹理转换的情况下进行渲染测试，以查明原因。您可以通过设置环境变量 `QT_DISABLE_HW_TEXTURES_CONVERSION ` 来禁用 GPU 纹理转换：QT_DISABLE_HW_TEXTURES_CONVERSION=1 。对于 `VAAPI ` 硬件后端，硬件纹理转换默认处于禁用状态。请将 `QT_XCB_GL_INTEGRATION=xcb_egl ` 设为 1 以启用该功能。

• 允许编解码器配置文件不匹配。

  如果编解码器配置文件与硬件报告的能力不匹配，您可以通过QT_FFMPEG_HW_ALLOW_PROFILE_MISMATCH=1 忽略此不匹配并允许硬件解码。 例如，当您使用VAAPI 硬件后端对基线配置文件 H.264 进行硬件加速解码时，设置此选项可能会有所帮助，因为此类流大多符合现有 H.264 硬件解码器的限制条件。

  警告：如果 媒体流不受支持，强制进行硬件解码可能会导致视频输出完全错误。