Qt Multimedia is an add-on module that provides a rich set of QML types and C++ classes to handle multimedia content. It contains an easy to use API for playing back audio and video files and rendering those on screen, as well as a comprehensive API for recording audio and video from various sources, including system cameras and microphones, screen or window captures, and audio or video memory buffers.
该模块功能分为下列子模块：
| Qt Multimedia | 提供用于特定多媒体用例的 API。 |
| Qt Multimedia Widgets | 提供基于 Widget 的多媒体 API。 |
| Qt Spatial Audio | 提供用于在 3D 空间实现声场的 API。 |
若正从 Qt 5 移植到 Qt 6，见 Qt Multimedia 的变化 .
若是 Qt Multimedia 新手，QML 类型可以
imported
进应用程序使用以下语句在
.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 的有关指导。
下表提纲了一些重要 QML 类型。
| 类型 | 描述 |
|---|---|
| MediaPlayer | 将音频/视频回放功能添加到场景。 |
| CaptureSession | 创建用于捕获音频/视频的会话。 |
| Camera | 访问连接到系统的摄像头。 |
| AudioInput | 访问连接到系统的音频输入 (麦克风)。 |
| AudioOutput | 访问连接到系统的音频输出 (扬声器、耳机)。 |
| VideoOutput | 显示视频内容。 |
| MediaRecorder | 录制音频/视频从 CaptureSession . |
| ImageCapture | 从摄像头捕获静止图像。 |
| 视频 | 将视频回放功能添加到场景。使用 MediaPlayer and VideoOutput 类型以提供视频回放功能。 |
| ScreenCapture | 捕获屏幕。 |
| WindowCapture | 捕获顶层窗口。 |
下表提纲了一些重要 C++ 类。
| 类 | 描述 |
|---|---|
| QMediaPlayer | 从源回放媒体。 |
| QVideoWidget | 显示来自媒体播放器 (或捕获会话) 的视频。 |
| QMediaCaptureSession | 捕获音频/视频。 |
| QCamera | 访问连接到系统的摄像头 |
| QAudioInput | 访问连接到系统的音频输入 (麦克风)。 |
| QAudioOutput | 访问连接到系统的音频输出 (扬声器、耳机)。 |
| QImageCapture | 以摄像头捕获静止图像。 |
| QMediaRecorder | 从捕获会话录制媒体内容。 |
| QVideoSink | 访问和渲染单个视频帧。 |
| QAudioSink | 将原生音频数据发送给音频输出设备。 |
| QScreenCapture | 捕获屏幕。 |
| QWindowCapture | 捕获顶层窗口。 |
| QVideoFrameInput | 用于显示 (或录制) 来自内存缓冲的视频帧。 |
| QAudioBufferInput | 支持播放 (或录制) 来自内存缓冲的音频。 |
对于音频和视频的回放， QMediaPlayer , QAudioOutput ，和 QVideoWidget contain all necessary functionality. Other classes are dedicated to capturing audio and video content, with QMediaCaptureSession serving as the central class that manages the entire capture and recording process.
Qt Multimedia 模块在商业许可下是可用的来自 Qt 公司 。此外，它在自由软件许可下也是可用的。从 Qt 5.6 起，这些自由软件许可是 GNU LGPL (次一般公共许可) 第 3 版 ，或 GNU GPL (一般公共许可) 第 2 版 。见 Qt 许可 进一步了解细节。
Furthermore, Qt Multimedia in Qt 6.8.5 may contain third-party modules under the following permissive licenses:
| GNU Lesser General Public License v2.1 or later and BSD 3-Clause "New" or "Revised" License and BSD 2-Clause "Simplified" License and BSD Source Code Attribution and ISC License and MIT License and Mozilla Public License 2.0 | |
| Boost 软件许可 1.0 | |
| 独立 JPEG 组许可 | |
| zlib 许可类 |
Note that video compression standards, such as the H.264 media compression standard, may be covered by patents and can incur royalty fees. This can apply to any implementation, also if the implementation is provided as an operating system service, through a third-party library, or any of Qt Multimedia's backends. The Qt licenses do not cover such fees.
Qt Multimedia offers user-friendly, cross-platform APIs for media playback, recording, and device management. The implementation of core APIs, including
QMediaDevices
,
QAudioDevice
,
QSoundEffect
,
QAudioSink
，和
QAudioSource
are integrated into the main Qt Multimedia library, eliminating the need for additional libraries. Other Qt Multimedia APIs are implemented using plugin libraries known as media backends. The main media backend, built on
FFmpeg
, ensures seamless cross-platform functionality, and is the default on all platforms except WebAssembly and embedded Linux/Boot2Qt. With Boot2Qt, the default backend is built on top of
GStreamer
, but the FFmpeg media backend can be enabled using the
QT_MEDIA_BACKEND
环境变量。
The FFmpeg media backend relies on the FFmpeg 7.1 libraries, which are included with the Qt Online Installer and tested by the maintainers. The binary packages from the online installer use dynamic linking to FFmpeg. Therefore, applications must either bundle FFmpeg binaries in their installer or depend on FFmpeg being installed on the operating system. The FFmpeg libraries are automatically deployed using Qt's deployment tools as described in the 部署 Qt 应用程序 documentation, except for Linux/X11 . Applications can also deploy their own build of FFmpeg, either as shared or static libraries, provided the FFmpeg major version matches the version used by Qt.
While Qt Multimedia leverages the FFmpeg media backend on most operating systems, platform specific functional or visual differences may arise between applications on different platforms. FFmpeg does not provide identical codec and format support across all platforms, and the performance of Qt Multimedia features may depend on hardware support that is only available on certain platforms. For instance, FFmpeg encounters specific issues with hardware acceleration on Linux targets with ARM architectures. Therefore, it is recommended to test Qt Multimedia applications on all target platforms.
注意： The FFmpeg project provides features under various licenses. The pre-built FFmpeg libraries that are provided through the Online Installer are only including features that agree with the permissive licenses listed under 许可和归属 .
To ease development and debugging, some FFmpeg functionality is configurable via environment varibles which are part of the private Qt Multimedia API.
For compatibility with existing applications, we maintain native media backends for each operating system:
注意： The FFmpeg media backend is the default backend, but native backends are still available but with limited support. The GStreamer backend is only available on Linux, and is only recommended for embedded applications.
注意： MediaCodec on Android is deprecated as of Qt 6.8 and will be removed in the next major release.
Qt Maintainers will strive to fix critical issues with the native backends but don't guarantee fixing minor issues, including inconsistent behavior across platforms. New features will only be implemented on the FFmpeg media backend.
The GStreamer backend has some private APIs to allow more fine-grained control. However, there are known bugs in the GStreamer backend. More details can be found in platform notes for the GStreamer backend .
Backend limitations will be documented, and their status will be maintained in the respective classes.
In the case of issues with the default FFmpeg backend, we suggest testing with a native backend. You can switch to native backends by setting the
QT_MEDIA_BACKEND
环境变量到
windows
,
gstreamer
(on Embedded Linux),
darwin
(在 macOS 和 iOS)，或
android
:
export QT_MEDIA_BACKEND=darwin
To force assign FFmpeg as the used backend, set the variable to
ffmpeg
:
export QT_MEDIA_BACKEND=ffmpeg
On the Qt Multimedia compilation stage, the default media backend can be configured via cmake variable
QT_DEFAULT_MEDIA_BACKEND
.
以下页列出了针对特定目标平台的问题。
从 Qt 6.6 开始，Qt Multimedia 模块使用新的 QPermission API 处理 camera and microphone 权限。这意味着 Qt 自身不再查询这些权限，所以，做到这需要直接从客户端应用程序。
请参考 应用程序权限 页了解范例如何集成新 QPermission API 进应用程序。