Qt Multimedia

"image of multimedia icons, courtesy of misirlou from the Noun Project"

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 MultimediaProvides an API for multimedia-specific use cases.
Qt Multimedia WidgetsProvides a widget-based multimedia API.
Qt Spatial AudioProvides 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)

Overviews and Important Topics

QML Types

The following table outlines some important QML types.

MediaPlayerAdd audio/video playback functionality to a scene.
CaptureSessionCreate a session for capturing audio/video.
CameraAccess a camera connected to the system.
AudioInputAccess an audio input (microphone) connected to the system.
AudioOutputAccess an audio output (speaker, headphone) connected to the system.
VideoOutputDisplay video content.
MediaRecorderRecord audio/video from the CaptureSession.
ImageCaptureCapture still images from the Camera.
VideoAdd Video playback functionality to a scene. Uses MediaPlayer and VideoOutput types to provide video playback functionality.

C++ Classes

The following table outlines some important C++ Classes

QMediaPlayerPlayback media from a source.
QVideoWidgetDisplay video from a media player or a capture session.
QMediaCaptureSessionCapture audio and video.
QCameraAccess a camera connected to the system
QAudioInputAccess an audio input (microphone) connected to the system.
QAudioOutputAccess an audio output (speaker, headphone) connected to the system.
QImageCaptureCapture still images with a camera.
QMediaRecorderRecord media content from a capture session.
QVideoSinkAccess and render individual video frames.
QAudioSinkSends raw audio data to an audio output device.

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.

The FFmpeg backend uses the FFmpeg framework. FFmpeg is licensed under LGPLv2.1, GPLv2, or later versions of the licenses. Some optional components of FFmpeg are only available under GPL. The FFmpeg backend shipped with the Qt binary packages is configured to not contain any of the components that are available under GPLv2 only. See the FFmpeg licensing page for further details.

Target platform and backend notes

On most platforms, there are two different backends that can be used for Qt Multimedia.

In Qt 6.5, we're setting FFmpeg framework as the default backend on Windows, macOS, Android, and Linux except Yocto distribution. Native backends, namely gstreamer on Linux, AVFoundation on macOS, WMF on Windows, and the MediaCodec framework on Android, were the default in 6.4. These are still available but with limited support. This means that we will strive to fix critical issues with the native backends, but don't guarantee fixing minor issues and won't implement new features with native backends. Furthermore, even some major issues with the gstreamer backend (on Linux) won't be fixed since gstreamer is the hardest for debugging and is dependent on linux distributives issues.

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. This happens since we use some platform API anyway, even with ffmpeg, and there are specific problems with ffmpeg hardware acceleration, mostly on Linux run on ARM architectures. Known backend-dependent limitations will be documented in the respective classes and methods.

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), 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.

Reference and Examples

© 2023 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.