Qt Multimedia
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.
The functionality of this module is divided into the following submodules:
Qt Multimedia | Provides an API for multimedia-specific use cases. |
Qt Multimedia Widgets | Provides a widget-based multimedia API. |
Qt Spatial Audio | Provides an API for implementing sound fields in 3D space. |
Getting started
If you are porting from Qt 5 to Qt 6, see Changes to Qt Multimedia.
If you are new to Qt Multimedia, the QML types can be imported into an application using the following statement in your .qml
file.
import QtMultimedia
To link against the C++ libraries, add the following to your project's CMakeLists.txt
file. Substitute my_project
with the name of your project.
find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(my_project PRIVATE Qt6::Multimedia)
See Building Qt Multimedia from sources for guidance on building Qt Multimedia from sources.
Overviews and important topics
- Changes in Qt 6
- Multimedia Overview
- Audio Overview
- Spatial Audio Overview
- Video Overview
- Camera Overview
- Supported Media Formats
QML types
The following table outlines some important QML types.
Type | Description |
---|---|
MediaPlayer | Add audio/video playback functionality to a scene. |
CaptureSession | Create a session for capturing audio/video. |
Camera | Access a camera connected to the system. |
AudioInput | Access an audio input (microphone) connected to the system. |
AudioOutput | Access an audio output (speaker, headphone) connected to the system. |
VideoOutput | Display video content. |
MediaRecorder | Record audio/video from the CaptureSession. |
ImageCapture | Capture still images from the Camera. |
Video | Add Video playback functionality to a scene. Uses MediaPlayer and VideoOutput types to provide video playback functionality. |
ScreenCapture | Captures a screen. |
WindowCapture | Captures a top-level window. |
C++ classes
The following table outlines some important C++ classes.
Class | Description |
---|---|
QMediaPlayer | Playback media from a source. |
QVideoWidget | Display video from a media player or a capture session. |
QMediaCaptureSession | Capture audio and video. |
QCamera | Access a camera connected to the system |
QAudioInput | Access an audio input (microphone) connected to the system. |
QAudioOutput | Access an audio output (speaker, headphone) connected to the system. |
QImageCapture | Capture still images with a camera. |
QMediaRecorder | Record media content from a capture session. |
QVideoSink | Access and render individual video frames. |
QAudioSink | Sends raw audio data to an audio output device. |
QScreenCapture | Captures a screen. |
QWindowCapture | Captures a top-level window. |
QVideoFrameInput | Used to display or record video frames from memory buffers. |
QAudioBufferInput | Supports playing or recording audio from memory buffers. |
For playback of audio and video, QMediaPlayer, QAudioOutput, and 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.
Licenses and attributions
The Qt Multimedia module is available under commercial licenses from The Qt Company. In addition, it is available under free software licenses. Since Qt 5.6, these free software licenses are GNU Lesser General Public License, version 3, or the GNU General Public License, version 2. See Qt Licensing for further details.
Furthermore, Qt Multimedia in Qt 6.8.1 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 Software License 1.0 | |
Independent JPEG Group License | |
zlib License |
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.
Target platform and backend notes
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, and 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
environment variable.
The FFmpeg backend
The FFmpeg media backend relies on the FFmpeg 7.0 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 Deploying Qt Applications 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.
Note: 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 Licenses and Attributions.
To ease development and debugging, some FFmpeg functionality is configurable via environment varibles which are part of the private Qt Multimedia API.
Native backends
For compatibility with existing applications, we maintain native media backends for each operating system:
- GStreamer on Linux
- AVFoundation on macOS and iOS
- Windows Media Foundation on Windows
- MediaCodec framework on Android
Note: 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.
Note: 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 GStreamer.
Backend limitations will be documented, and their status will be maintained in the respective classes.
Changing backends
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
environment variable to windows
, gstreamer
(on Linux), darwin
(on macOS and iOS), or 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
.
Target platform notes
The following pages list issues for specific target platforms that are not related to the multimedia backend.
Permissions
Starting from Qt 6.6, the Qt Multimedia module uses the new QPermission API to handle camera and microphone permissions. This means that Qt itself no longer queries for these permissions, so this needs to be done directly from the client application.
Please refer to the Application Permissions page for an example of how to integrate the new QPermission API into the application.
Reference and examples
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.