Qt Multimedia

Qt Multimedia 提供了一个附加模块，其中包含一套丰富的 QML 类型和 C++ 类，用于处理多媒体内容。 它包含一个易于使用的 API，用于播放音频和视频文件并在屏幕上渲染，还包含一个全面的 API，用于从各种来源录制音频和视频，包括系统摄像头和麦克风、屏幕或窗口捕获，以及音频或视频内存缓冲区。

该模块的功能分为以下子模块：

入门指南

如果您正在从 Qt 5 移植到 Qt 6，请参阅《Qt Multimedia 的变更》。

如果您是首次使用Qt Multimedia ，可以在.qml 文件中使用以下语句将 QML 类型导入应用程序。

import QtMultimedia

要链接 C++ 库，请在项目的CMakeLists.txt 文件中添加以下内容。将mytarget 替换为您的项目名称。

find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)

有关从源代码构建 Qt Multimedia 的指导，请参阅《从源代码构建 Qt Multimedia 》。

概述和重要主题

• Qt 6 中的变更
• 多媒体概述
• 音频概述
• 空间音频概述
• 视频概述
• 摄像头概述
• 支持的媒体格式

QML 类型

下表概述了一些重要的 QML 类型。

C++ 类

下表概述了一些重要的 C++ 类。

对于音频和视频的播放，QMediaPlayer 、QAudioOutput 和QVideoWidget 包含所有必要的功能。其他类专门用于捕获音频和视频内容，其中QMediaCaptureSession 作为管理整个捕获和录制过程的核心类。

许可与署名

Qt Multimedia 模块由The Qt Company提供商业许可。此外，该模块还提供自由软件许可。自Qt 5.6起，这些自由软件许可包括GNU较少通用公共许可证（GNU Lesser General Public License）第3版或GNU通用公共许可证（GNU General Public License）第2版。更多详细信息请参阅Qt许可说明。

此外，Qt 6.12.0 中的Qt Multimedia 可能包含采用以下宽松许可协议的第三方模块：

请注意，视频压缩标准（例如 H.264 媒体压缩标准）可能受专利保护，并可能产生专利使用费。这适用于任何实现方式，无论该实现是以操作系统服务形式提供、通过第三方库提供，还是通过Qt Multimedia 中的任何后端提供。Qt 许可不涵盖此类费用。

目标平台和后端说明

Qt Multimedia 提供用于媒体播放、录制和设备管理的用户友好型跨平台 API。核心 API 的实现，包括QMediaDevices 、QAudioDevice 、QSoundEffect 、QAudioSink 和QAudioSource ，均已集成到主Qt Multimedia 库中，无需额外库。其他Qt Multimedia API 则通过称为媒体后端的插件库实现。 基于FFmpeg 构建的主媒体后端确保了无缝的跨平台功能，并且是除 WebAssembly 和嵌入式 Linux/Boot2Qt 以外所有平台上的默认后端。在 Boot2Qt 环境中，默认后端基于GStreamer 构建，但可以通过设置环境变量QT_MEDIA_BACKEND 来启用 FFmpeg 媒体后端。

FFmpeg 后端

FFmpeg 媒体后端依赖于FFmpeg 9.0.1库，这些库已包含在Qt Online Installer 中，并经过维护人员的测试。在线安装程序提供的二进制包采用动态链接方式连接 FFmpeg。因此，应用程序必须在安装程序中捆绑 FFmpeg 二进制文件，或者依赖于操作系统上已安装的 FFmpeg。 除Linux/X11 之外，FFmpeg 库将按照《部署 Qt 应用程序》文档中的说明，通过 Qt 的部署工具自动进行部署。应用程序也可以部署自己构建的 FFmpeg（无论是共享库还是静态库），前提是 FFmpeg 的主版本号与 Qt 使用的版本一致。

虽然Qt Multimedia 在大多数操作系统上都利用FFmpeg媒体后端，但在不同平台上的应用程序之间仍可能出现特定于平台的功能或视觉差异。FFmpeg在所有平台上提供的编解码器和格式支持并不完全一致，且Qt Multimedia 功能的性能可能取决于仅在某些平台上可用的硬件支持。 例如，FFmpeg 在基于 ARM 架构的 Linux 目标平台上会遇到与硬件加速相关的特定问题。因此，建议在所有目标平台上测试Qt Multimedia 应用程序。

为了简化开发和调试，部分 FFmpeg 功能可通过环境变量进行配置，这些变量属于私有 APIQt Multimedia 的一部分。

原生后端

为了与现有应用程序兼容，我们为每个操作系统维护了原生媒体后端：

• 嵌入式 Linux 上的GStreamer 后端
• macOS 和 iOS 上的 AVFoundation
• Windows 上的 Windows Media Foundation（自 Qt 6.10 起已弃用）
• Android 上的 MediaCodec 框架
• WebAssembly 上的 WebAudio 和 WebVideo

Qt 维护团队将致力于修复原生后端中的关键问题，但不保证修复次要问题，包括跨平台行为不一致的情况。除 WebAssembly 之外，新功能将仅在 FFmpeg 媒体后端上实现。

GStreamer 后端提供了一些私有 API，以实现更精细的控制。不过，GStreamer 后端中存在已知错误。更多详细信息请参阅GStreamer 后端的平台说明。

后端限制将予以记录，其状态将在相应的类中进行维护。

切换后端

如果默认的 FFmpeg 后端出现问题，我们建议尝试使用原生后端。您可以通过将环境变量 `QT_MEDIA_BACKEND ` 设置为 `windows`、`gstreamer `（在嵌入式 Linux 上）、`darwin `（在 macOS 和 iOS 上）或 `android` 来切换到原生后端：

export QT_MEDIA_BACKEND=darwin

若要强制指定 FFmpeg 作为后端，请将该变量设置为ffmpeg ：

export QT_MEDIA_BACKEND=ffmpeg

在Qt Multimedia 编译阶段，可通过 cmake 变量QT_DEFAULT_MEDIA_BACKEND 配置默认媒体后端。

目标平台说明

以下页面列出了针对特定目标平台的问题。

• macOS 和 iOS
• WebAssembly
• Windows
• Linux
• 嵌入式 Linux 的 GStreamer 后端

权限

从 Qt 6.6 开始，Qt Multimedia 模块使用新的QPermission API 来处理camera 和microphone 权限。这意味着 Qt 本身不再查询这些权限，因此需要由客户端应用程序直接进行查询。

请参阅“应用程序权限”页面，了解如何将新的QPermission API 集成到应用程序中的示例。

参考资料和示例

• QML Types
• C++ 类
• 示例