Qt Multimedia

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

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

开始使用

如果您要从 Qt 5 移植到 Qt 6，请参阅 Qt Multimedia 的更改。

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

import QtMultimedia

要与 C++ 库链接，请在项目的CMakeLists.txt 文件中添加以下语句。用项目名称代替my_project 。

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

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

概述和重要主题

• Qt 6 中的变化
• 多媒体概述
• 音频概述
• 空间音频概述
• 视频概述
• 相机概述
• 支持的媒体格式

QML 类型

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

C++ 类

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

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

许可和归属

Qt Multimedia 模块可通过Qt XML Company 的商业许可获得。此外，它还可根据自由软件许可证使用。自 Qt 5.6 起，这些自由软件许可证为GNU Lesser General Public License 第 3 版或GNU General Public License 第 2 版。更多详情，请参阅Qt 许可。

此外，Qt 6.9.1 中的Qt Multimedia 可能包含以下许可下的第三方模块：

请注意，视频压缩标准（如 H.264 媒体压缩标准）可能受专利保护，并可能产生专利使用费。这可能适用于任何实现，也适用于作为操作系统服务、通过第三方库或Qt Multimedia 的任何后端提供的实现。Qt 许可证不包含此类费用。

目标平台和后端说明

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

FFmpeg 后端

FFmpeg 媒体后端依赖于FFmpeg 7.1库，这些库包含在Qt Online Installer 中，并由维护者进行了测试。在线安装程序中的二进制包使用动态链接到 FFmpeg。因此，应用程序必须在其安装程序中捆绑 FFmpeg 二进制文件，或依赖于操作系统上已安装的 FFmpeg。除Linux/X11 外，FFmpeg 库会使用 Qt 的部署工具自动部署，如 "部署 Qt 应用程序"文档中所述。只要 FFmpeg 的主要版本与 Qt 使用的版本一致，应用程序也可以以共享或静态库的形式部署自己的 FFmpeg 构建。

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

为便于开发和调试，某些 FFmpeg 功能可通过环境变量进行配置，这些环境变量是Qt Multimedia API 的一部分。

本地后端

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

• 嵌入式 Linux 上的GStreamer 后端
• MacOS 和 iOS 上的 AVFoundation
• Windows 上的 Windows Media Foundation
• 安卓系统上的 MediaCodec 框架

Qt 维护人员将努力修复本地后端的关键问题，但不保证修复次要问题，包括跨平台的不一致行为。新功能只会在 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 配置默认媒体后端。

目标平台注意事项

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

• Windows
• macOS 和 iOS
• WebAssembly
• 嵌入式 Linux
• 嵌入式 Linux 和 GStreamer

权限

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

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

参考资料和示例

• QML Types
• C++ 类
• 示例