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:

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.

C++ classes

The following table outlines some important C++ classes.

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.0 may contain third-party modules under the following permissive licenses:

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.

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

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.

• macOS and iOS
• WebAssembly
• Linux using the Wayland compositor

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

• QML Types
• C++ Classes
• Examples