1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qmediadevices.h"
5#include "private/qplatformmediaintegration_p.h"
6#include "private/qplatformaudiodevices_p.h"
7#include "private/qplatformvideodevices_p.h"
8
9#include <QtCore/qmetaobject.h>
10
11#include <qaudiodevice.h>
12#include <qcameradevice.h>
13
14QT_BEGIN_NAMESPACE
15
16/*!
17 \class QMediaDevices
18 \brief The QMediaDevices class provides information about available
19 multimedia input and output devices.
20 \ingroup multimedia
21 \inmodule QtMultimedia
22
23 The QMediaDevices class provides information about the available multimedia
24 devices and the system defaults. It monitors the following three groups:
25 \list
26 \li Audio input devices (Microphones)
27 \li Audio output devices (Speakers, Headsets)
28 \li Video input devices (Cameras)
29 \endlist
30
31 QMediaDevices provides a separate list for each device group. If it detects that a
32 new device has been connected to the system or an attached device has been disconnected
33 from the system, it will update the corresponding device list and emit a signal
34 notifying about the change.
35
36 The QMediaDevices::audioInputs and QMediaDevices::audioOutputs functions can be used
37 to enumerate all microphones and speakers/headsets on the system. This example first
38 gets a list of all connected microphones, and then prints their identifier, description,
39 and if it is the default device or not.
40
41 \snippet multimedia-snippets/devices.cpp Media Audio Input Device Enumeration
42
43 Similarly, the QMediaDevices::videoInputs will return a list of all connected cameras.
44 In this example we list all connected cameras and their identifier, description, and
45 if it is the default camera or not.
46
47 \snippet multimedia-snippets/devices.cpp Media Video Input Device Enumeration
48
49 QMediaDevices monitors the system defaults for each device group. It will notify about
50 any changes done through the system settings. For example, if the user selects a new
51 default audio output in the system settings, QMediaDevices will update the default audio
52 output accordingly and emit a signal. If the system does not provide a default for a
53 camera or an audio input, QMediaDevices will select the first device from the list as
54 the default device.
55
56 While using the default input and output devices is often sufficient for
57 playing back or recording multimedia, there is often a need to explicitly
58 select the device to be used.
59
60 QMediaDevices is a singleton object and all getters are thread-safe.
61
62 \note On WebAssembly platform, due to it's asynchronous nature,
63 the lists of devices will only be available after audioInputsChanged,
64 audioOutputsChanded, or videoInputsChanged notifications.
65
66*/
67
68/*!
69 \qmltype MediaDevices
70 \since 6.2
71 \nativetype QMediaDevices
72 \brief MediaDevices provides information about available
73 multimedia input and output devices.
74 \inqmlmodule QtMultimedia
75 \ingroup multimedia_qml
76
77 The MediaDevices type provides information about the available multimedia
78 devices and the system defaults. It monitors the following three groups:
79 \list
80 \li Audio input devices (Microphones)
81 \li Audio output devices (Speakers, Headsets)
82 \li Video input devices (Cameras)
83 \endlist
84
85 MediaDevices provides a separate list for each device group. If it detects that a
86 new device has been connected to the system or an attached device has been disconnected
87 from the system, it will update the corresponding device list and emit a signal
88 notifying about the change.
89
90 MediaDevices monitors the system defaults for each device group. It will notify about
91 any changes done through the system settings. For example, if the user selects a new
92 default audio output in the system settings, MediaDevices will update the default audio
93 output accordingly and emit a signal. If the system does not provide a default for a
94 camera or an audio input, MediaDevices will select the first device from the list as
95 the default device.
96
97 While using the default input and output devices is often sufficient for
98 playing back or recording multimedia, there is often a need to explicitly
99 select the device to be used.
100
101 For example, the snippet below will ensure that the media player always uses
102 the systems default audio output device for playback:
103
104 \qml
105 MediaDevices {
106 id: devices
107 }
108 MediaPlayer {
109 ...
110 audioOutput: AudioOutput {
111 device: devices.defaultAudioOutput
112 }
113 }
114 \endqml
115
116 \sa Camera, AudioInput, VideoOutput
117*/
118
119/*!
120 \qmlproperty list<audioDevice> QtMultimedia::MediaDevices::audioInputs
121 Contains a list of available audio input devices on the system.
122
123 Those devices are usually microphones. Devices can be either built-in, or
124 connected through for example USB or Bluetooth.
125*/
126
127/*!
128 \property QMediaDevices::audioInputs
129
130 Returns a list of available audio input devices on the system.
131
132 Those devices are usually microphones. Devices can be either built-in, or
133 connected through for example USB or Bluetooth.
134*/
135QList<QAudioDevice> QMediaDevices::audioInputs()
136{
137 return QPlatformMediaIntegration::instance()->audioDevices()->audioInputs();
138}
139
140/*!
141 \qmlproperty list<audioDevice> QtMultimedia::MediaDevices::audioOutputs
142 Contains a list of available audio output devices on the system.
143
144 Those devices are usually loudspeakers or head sets. Devices can be either
145 built-in, or connected through for example USB or Bluetooth.
146*/
147
148/*!
149 \property QMediaDevices::audioOutputs
150
151 Returns a list of available audio output devices on the system.
152
153 Those devices are usually loudspeakers or head sets. Devices can be either
154 built-in, or connected through for example USB or Bluetooth.
155*/
156QList<QAudioDevice> QMediaDevices::audioOutputs()
157{
158 return QPlatformMediaIntegration::instance()->audioDevices()->audioOutputs();
159}
160
161/*!
162 \qmlproperty list<cameraDevice> QtMultimedia::MediaDevices::videoInputs
163 Contains a list of cameras on the system.
164*/
165
166/*!
167 \property QMediaDevices::videoInputs
168
169 Returns a list of available cameras on the system.
170*/
171QList<QCameraDevice> QMediaDevices::videoInputs()
172{
173 QPlatformVideoDevices *videoDevices = QPlatformMediaIntegration::instance()->videoDevices();
174 return videoDevices ? videoDevices->videoInputs() : QList<QCameraDevice>{};
175}
176
177/*!
178 \qmlproperty audioDevice QtMultimedia::MediaDevices::defaultAudioInput
179 Returns the default audio input device.
180
181 The default device can change during the runtime of the application. The value
182 of this property will automatically adjust itself to such changes.
183*/
184
185/*!
186 \property QMediaDevices::defaultAudioInput
187
188 Returns the default audio input device.
189
190 The default device can change during the runtime of the application.
191 The audioInputsChanged() signal is emitted in this case.
192*/
193QAudioDevice QMediaDevices::defaultAudioInput()
194{
195 const auto inputs = audioInputs();
196 if (inputs.isEmpty())
197 return {};
198 for (const auto &info : inputs)
199 if (info.isDefault())
200 return info;
201 return inputs.value(i: 0);
202}
203
204/*!
205 \qmlproperty audioDevice QtMultimedia::MediaDevices::defaultAudioOutput
206 Returns the default audio output device.
207
208 The default device can change during the runtime of the application. The value
209 of this property will automatically adjust itself to such changes.
210*/
211
212/*!
213 \property QMediaDevices::defaultAudioOutput
214
215 Returns the default audio output device.
216
217 The default device can change during the runtime of the application. The
218 audioOutputsChanged() signal is emitted in this case.
219*/
220QAudioDevice QMediaDevices::defaultAudioOutput()
221{
222 const auto outputs = audioOutputs();
223 if (outputs.isEmpty())
224 return {};
225 for (const auto &info : outputs)
226 if (info.isDefault())
227 return info;
228 return outputs.value(i: 0);
229}
230
231/*!
232 \qmlproperty cameraDevice QtMultimedia::MediaDevices::defaultVideoInput
233 Returns the default camera on the system.
234
235 \note The returned object should be checked using isNull() before being used,
236 in case there is no camera available.
237
238 The default device can change during the runtime of the application. The value
239 of this property will automatically adjust itself to such changes.
240*/
241
242/*!
243 \property QMediaDevices::defaultVideoInput
244
245 Returns the default camera on the system.
246
247 \note The returned object should be checked using isNull() before being used,
248 in case there is no default camera or no cameras at all.
249
250 The default device can change during the runtime of the application. The
251 videoInputsChanged() signal is emitted in that case.
252
253 \sa videoInputs()
254*/
255QCameraDevice QMediaDevices::defaultVideoInput()
256{
257 const auto inputs = videoInputs();
258 if (inputs.isEmpty())
259 return {};
260 for (const auto &info : inputs)
261 if (info.isDefault())
262 return info;
263 return inputs.value(i: 0);
264}
265
266/*!
267 \internal
268*/
269QMediaDevices::QMediaDevices(QObject *parent) : QObject(parent) { }
270
271/*!
272 \internal
273*/
274QMediaDevices::~QMediaDevices() = default;
275
276void QMediaDevices::connectNotify(const QMetaMethod &signal)
277{
278 // we don't connect in the constructor in order to not initialize
279 // the cameras tracking pipeline or audio tracking pipeline if cameras or audio devices
280 // are not requested. The instance of device provider is lazily created upon the first
281 // connection or the first devices request.
282
283 auto ensureConnection = [&](auto devicesMethod, auto platformDevicesSignal, auto targetSignal) {
284 if (signal == QMetaMethod::fromSignal(targetSignal))
285 if (auto devices = (QPlatformMediaIntegration::instance()->*devicesMethod)()) {
286 connect(devices, platformDevicesSignal, this, targetSignal, Qt::UniqueConnection);
287 return true;
288 }
289
290 return false;
291 };
292
293 // clang-format off
294 ensureConnection(&QPlatformMediaIntegration::videoDevices,
295 &QPlatformVideoDevices::videoInputsChanged,
296 &QMediaDevices::videoInputsChanged) ||
297 ensureConnection(&QPlatformMediaIntegration::audioDevices,
298 &QPlatformAudioDevices::audioInputsChanged,
299 &QMediaDevices::audioInputsChanged) ||
300 ensureConnection(&QPlatformMediaIntegration::audioDevices,
301 &QPlatformAudioDevices::audioOutputsChanged,
302 &QMediaDevices::audioOutputsChanged);
303 // clang-format on
304
305 QObject::connectNotify(signal);
306}
307
308QT_END_NAMESPACE
309
310#include "moc_qmediadevices.cpp"
311

source code of qtmultimedia/src/multimedia/qmediadevices.cpp