1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
|
// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
/*!
\page qtmultimedia-index.html
\title Qt Multimedia
\image noun_Media_166644.svg "image of multimedia icons, courtesy of misirlou from the Noun Project"
\brief The Qt Multimedia module provides APIs for playing back and recording
audiovisual content
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:
\table
\row
\li \l{Multimedia Overview}{Qt Multimedia}
\li Provides an API for multimedia-specific use cases.
\row
\li \l{Qt Multimedia Widgets}
\li Provides a widget-based multimedia API.
\row
\li \l{Qt Spatial Audio}
\li Provides an API for implementing sound fields in 3D space.
\endtable
\section1 Getting started
If you are porting from Qt 5 to Qt 6 see \l{Changes to Qt Multimedia}.
If you are new to Qt Multimedia, the QML types can be
\l{qtqml import syntax}{imported} into an application using the following
statement in your \c {.qml} file.
\qml
import QtMultimedia
\endqml
To link against the C++ libraries, add the following to your project's
\c CMakeLists.txt file. Substitute \c my_project with the name of your
project.
\code
find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(my_project PRIVATE Qt6::Multimedia)
\endcode
\section1 Overviews and important topics
\list
\li \l{Changes to Qt Multimedia}{Changes in Qt 6}
\li \l{Multimedia Overview}
\li \l{Audio Overview}
\li \l{Spatial Audio Overview}
\li \l{Video Overview}
\li \l{Camera Overview}
\li \l{Supported Media Formats}
\endlist
\section1 QML types
The following table outlines some important QML types.
\table
\header
\li Type
\li Description
\row
\li \l{MediaPlayer}
\li Add audio/video playback functionality to a scene.
\row
\li \l {QtMultimedia::CaptureSession}{CaptureSession}
\li Create a session for capturing audio/video.
\row
\li \l {QtMultimedia::Camera}{Camera}
\li Access a camera connected to the system.
\row
\li \l {QtMultimedia::AudioInput}{AudioInput}
\li Access an audio input (microphone) connected to the system.
\row
\li \l {QtMultimedia::AudioOutput}{AudioOutput}
\li Access an audio output (speaker, headphone) connected to the system.
\row
\li \l {QtMultimedia::VideoOutput}{VideoOutput}
\li Display video content.
\row
\li \l {QtMultimedia::MediaRecorder}{MediaRecorder}
\li Record audio/video from the CaptureSession.
\row
\li \l {QtMultimedia::ImageCapture}{ImageCapture}
\li Capture still images from the Camera.
\row
\li \l {QtMultimedia::Video}{Video}
\li Add Video playback functionality to a scene. Uses MediaPlayer and
VideoOutput types to provide video playback functionality.
\row
\li \l {QtMultimedia::ScreenCapture}{ScreenCapture}
\li Captures a screen.
\row
\li \l {QtMultimedia::WindowCapture}{WindowCapture}
\li Captures a top-level window.
\endtable
\section1 C++ classes
The following table outlines some important C++ classes
\table
\header
\li Class
\li Description
\row
\li QMediaPlayer
\li Playback media from a source.
\row
\li QVideoWidget
\li Display video from a media player or a capture session.
\row
\li QMediaCaptureSession
\li Capture audio and video.
\row
\li QCamera
\li Access a camera connected to the system
\row
\li QAudioInput
\li Access an audio input (microphone) connected to the system.
\row
\li QAudioOutput
\li Access an audio output (speaker, headphone) connected to the system.
\row
\li QImageCapture
\li Capture still images with a camera.
\row
\li QMediaRecorder
\li Record media content from a capture session.
\row
\li QVideoSink
\li Access and render individual video frames.
\row
\li QAudioSink
\li Sends raw audio data to an audio output device.
\row
\li QScreenCapture
\li Captures a screen.
\row
\li QWindowCapture
\li Captures a top-level window.
\endtable
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.
\section1 Licenses and attributions
The Qt Multimedia module is available under commercial licenses from
\l{The Qt Company}.
In addition, it is available under free software licenses. Since Qt 5.6,
these free software licenses are
\l{GNU Lesser General Public License, version 3}, or
the \l{GNU General Public License, version 2}.
See \l{Qt Licensing} for further details.
The FFmpeg backend uses the \l {https://ffmpeg.org}{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 \l {https://ffmpeg.org/legal.html}{FFmpeg licensing page} for further
details.
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.
\section1 Target platform and backend notes
We aim to align the behavior on all the platforms but there are some issues
to consider.
\section2 Backends
On most platforms, there are two different backends that can be used for
Qt Multimedia.
\section3 FFmpeg as the default backend
In this release the \l {http://ffmpeg.org}{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 \b{FFmpeg 6.0} and is tested
by the maintainers.
\note See \l{Licenses and Attributions} regarding what components are removed
in the package shipped by Qt.
\section3 Native backends
These are:
\list
\li gstreamer on Linux
\li AVFoundation on macOS
\li WMF Windows
\li MediaCodec framework on Android
\endlist
\note These are still available but with \b limited support.
\section2 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.
\section2 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 \c{QT_MEDIA_BACKEND} environment variable
to \c windows, \c gstreamer (on Linux), \c darwin (on macOS), or \c android:
\code
export QT_MEDIA_BACKEND=darwin
\endcode
In order to force assign FFmpeg as the used backend, set the variable to \c ffmpeg:
\code
export QT_MEDIA_BACKEND=ffmpeg
\endcode
On the Qt Multimedia compilation stage the default media backend can be configured
via cmake variable \c{QT_DEFAULT_MEDIA_BACKEND}.
\section2 Target platform notes
The following pages list issues for specific target platforms that are not
related to the multimedia backed.
\list
\li \l{Qt Multimedia on macOS and iOS}{macOS and iOS}
\li \l{Qt Multimedia on WebAssembly}{WebAssembly}
\endlist
\section1 Permissions
Starting from Qt 6.6, the Qt Multimedia module uses new \l QPermission API
to handle \l {QCameraPermission}{camera} and
\l {QMicrophonePermission}{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 \l {Application Permissions} page for an example of how
to integrate the new \l QPermission API into the application.
\section1 Reference and examples
\list
\li \l{Qt Multimedia QML Types}{QML Types}
\li \l{Qt Multimedia C++ Classes}{C++ Classes}
\li \l{Qt Multimedia Examples}{Examples}
\endlist
*/
|
