Qt Multimedia | Qt 6.12.0
Description: The Qt Multimedia module provides APIs for playing back and recording audiovisual content

- Qt 6.12
- Qt Multimedia
- Qt 6.12.0 Reference Documentation

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

DR Libs, version 0.14.5 | The Unlicense or MIT No Attribution
DR Libs, version 0.14.5 | MIT No Attribution
FFmpeg, version 7.1.3 | 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
Signalsmith Stretch, version 1.0.0 | MIT License
Two-Level Segregated Fit, version v3.1 | BSD 3-Clause "New" or "Revised" License
boost | Boost Software License 1.0
libjpeg | Independent JPEG Group License
zlib | 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.1.3 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 backend on Embedded Linux
- AVFoundation on macOS and iOS
- Windows Media Foundation on Windows (deprecated since Qt 6.10)
- MediaCodec framework on Android
- WebAudio and WebVideo on WebAssembly

Note: The FFmpeg media backend is the default backend except on WebAssembly, 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.

Note: The Windows media backend built on top of Windows Media Foundation is deprecated as of Qt 6.10 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, with the exception of WebAssembly.

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.

### 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 Embedded 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.

- macOS and iOS
- WebAssembly
- Windows
- Linux
- GStreamer backend for embedded Linux

## 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