Linux 和 Android 上的 FFmpeg 代理库

概述

为了支持符合 LGPL 许可证要求的FFmpeg动态链接，Qt Multimedia 在 Linux 和 Android 平台上使用存根库来处理可选的外部依赖项。

在这些平台上，FFmpeg 可能需要 Qt 未随附的额外共享库：

• OpenSSL——用于安全的网络流媒体传输。
• VAAPI（仅限 Linux）——支持硬件加速的视频解码和编码。

由于许可限制，这些库通常无法获得或无法打包。为确保基于 FFmpeg 的功能（不包括不受支持的部分）保持正常运行，Qt 提供了存根库作为备用方案。

为何需要存根库

如果运行时缺少这些依赖项，FFmpeg 将无法加载或正常运行。存根机制可实现：

• 即使缺少 OpenSSL 或 VAAPI，也能成功加载 FFmpeg。
• 功能的平滑降级（例如，缺少 VAAPI 会导致无法使用硬件加速，但播放功能仍可正常工作）。
• 用户可在系统提供这些库的版本时，选择使用系统自带的版本。

什么是存根

存根库模拟真实库的接口（例如libssl.so 、libva.so ），但并不实现全部功能。相反，它们：

• 提供返回安全回退值或无操作的虚拟实现。
• 通过QLibrary::load /QLibrary::resolve 动态尝试解析真实符号。
• 若未找到真实库，则优雅地处理错误。

Qt 提供以下名称的这些存根：

• libQt6FFmpegStub-ssl.so.x
• libQt6FFmpegStub-crypto.so.x
• libQt6FFmpegStub-va.so.x
• libQt6FFmpegStub-va-drm.so.x
• libQt6FFmpegStub-va-x11.so.x
• （未来可能会添加更多）

Qt 中存根的工作原理

当 FFmpeg 被动态链接时：

• 它通常期望与libssl.so.3 或libva.so.2 等系统库进行链接。
• Qt 使用patchelf 工具对 FFmpeg 二进制文件进行修补，将这些真实的依赖项替换为相应的存根。

示例：

# Original linkage
libffmpegmediaplugin.so: needs libavcodec.so (depends on the FFmpeg libs)
libavcodec.so: needs libssl.so.3

# After patching
libffmpegmediaplugin.so: needs libavcodec.so (no changes)
libavcodec.so: needs libQt6FFmpegStub-ssl.so.3
libQt6FFmpegStub-ssl.so.3: optionally needs libssl.so.3 (no explicit linkage)

此修补操作作为构建/分发流程的一部分自动执行。

运行时行为与安全注意事项

• FFmpeg 插件通过dlopen(..., RTLD_LOCAL) 加载，因此占位符符号不会泄漏到全局符号表中。
• 如果应用程序已使用 OpenSSL 或 VAAPI，系统库可能会从全局作用域中获取，因此必须确保二进制兼容性。
• 随附的QtMultimedia 和FFmpeg二进制文件兼容以下版本：
  • OpenSSL 3.x.x（采用@OPENSSL_3.0.0 符号版本控制）
  • VAAPI ABI 0.33（明确不支持较旧的 ABI 0.32）

要完全停止使用存根库，有两种方法：

• 使用patchelf 将 FFmpeg 的依赖项恢复为系统库（例如，将libQt6FFmpegStub-ssl.so.3 替换为libssl.so.3 ）。此操作必须针对所有 FFmpeg 库进行：libavcodec 、libavformat 、libavutil 、libswresample 以及libswscale 。
• 将随附的 FFmpeg 库替换为用户手动构建的库。请参阅《从源代码构建 FFmpeg》。