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 the system's cameras and microphones.
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. |
For playback QMediaPlayer, QAudioOutput and QVideoOutput contain all the required functionality. The other classes are used for capturing audio and video content, where the QMediaCaptureSession is the central class managing the whole capture/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.7.2 may contain third-party modules under 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 through any of Qt Multimedia's backends. Such fees are not covered by the Qt licenses.
Target platform and backend notes
We aim to align the behavior on all the platforms but there are some issues to consider.
Backends
On most platforms, there are two different backends that can be used for Qt Multimedia.
FFmpeg as the default backend
In this release the FFmpeg framework is set as the default backend on Windows, macOS, Android, and Linux except Yocto distribution.
The version shipped with Qt binary packages is FFmpeg 6.1.1 and is tested by the maintainers.
Note: On the Windows and macOS platforms, Qt's FFmpeg media backend uses dynamic linking to the FFmpeg libraries. Windows and macOS applications must therefore bundle FFmpeg binaries in their installer, and make them visible to the application at runtime. On Windows, we recommend to store the FFmpeg dlls in the same directory as the application's executable file, because this guarantees that the correct build of FFmpeg is being used if multiple versions are available on the system. All necessary FFmpeg libraries are shipped with the Qt Online Installer and are automatically deployed if the windeployqt or macdeployqt tools are used to create the deployment. Applications can also deploy their own build of FFmpeg, as long as the FFmpeg major version matches the version used by Qt.
Note: See Licenses and Attributions regarding what components are removed in the package shipped by Qt.
Native backends
These are:
- gstreamer on Linux
- AVFoundation on macOS and iOS
- WMF Windows
- MediaCodec framework on Android
Note: These are still available but with limited support. The gstreamer backend is only available on Linux.
Backend support
Maintainers will strive to fix critical issues with the native backends but don't guarantee fixing minor issues and won't implement new features for the native backends. Furthermore, even some major issues with the gstreamer backend (on Linux) won't be fixed since gstreamer is difficult to debug and is further complicated as it is dependent on Linux distributions.
We aim to align the behavior on all the platforms, especially, with the FFmpeg backend. Despite this fact we still have platform-dependent issues with formats, codecs, advanced camera features, and screen capturing due to the Qt Multimedia API relying on target platform APIs. For example, with FFmpeg, there are specific problems with hardware acceleration on Linux targets with ARM architectures.
Backend-dependent limitations will be documented and their status 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
In order 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 backed.
Permissions
Starting from Qt 6.6, the Qt Multimedia module uses 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.