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 "qaudiosystem_p.h"
5#include "qaudiodevice_p.h"
6#include <private/qplatformaudiodevices_p.h>
7#include <private/qplatformmediaintegration_p.h>
8
9#include <QtCore/qmap.h>
10
11QT_BEGIN_NAMESPACE
12
13QAudioDevicePrivate::~QAudioDevicePrivate() = default;
14
15QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioDevicePrivate);
16
17/*!
18 \class QAudioDevice
19 \brief The QAudioDevice class provides an information about audio devices and their
20 functionality.
21 \inmodule QtMultimedia
22 \ingroup multimedia
23 \ingroup multimedia_audio
24
25 QAudioDevice describes an audio device available in the system, either for input or for
26 playback.
27
28 A QAudioDevice is used by Qt to construct
29 classes that communicate with the device -- such as
30 QAudioSource, and QAudioSink. It is also used to determine the
31 input or output device to use in a capture session or during media playback.
32
33 The QAudioDevice instance retains its properties throughout its lifetime,
34 even if the corresponding physical device is disconnected or its settings are
35 modified. To keep track of updated properties, the user should load new instances
36 of QAudioDevice from \l{QMediaDevices} when the relevant signals are fired.
37
38 You can also query each device for the formats it supports. A
39 format in this context is a set consisting of a channel count, sample rate, and sample type. A
40 format is represented by the QAudioFormat class.
41
42 The values supported by the device for each of these parameters can be
43 fetched with minimumChannelCount(), maximumChannelCount(),
44 minimumSampleRate(), maximumSampleRate() and supportedSampleFormats(). The
45 combinations supported are dependent on the audio device capabilities. If
46 you need a specific format, you can check if the device supports it with
47 isFormatSupported(). For instance:
48
49 \snippet multimedia-snippets/audio.cpp Audio output setup
50
51 The set of available devices can be retrieved from the QMediaDevices class.
52
53 For instance:
54
55 \snippet multimedia-snippets/audio.cpp Dumping audio formats
56
57 In this code sample, we loop through all devices that are able to output
58 sound, i.e., play an audio stream in a supported format. For each device we
59 find, we simply print the deviceName().
60
61 \sa QAudioSink, QAudioSource, QAudioFormat
62*/
63
64/*!
65 \qmlvaluetype audioDevice
66 \inqmlmodule QtMultimedia
67 \since 6.2
68 //! \nativetype QAudioDevice
69 \brief Describes an audio device.
70 \ingroup multimedia_qml
71 \ingroup multimedia_audio_qml
72 \ingroup qmlvaluetypes
73
74 The audioDevice value type describes the properties of an audio device that
75 is connected to the system.
76
77 The audioDevice instance retains its properties throughout its lifetime,
78 even if the corresponding physical device is disconnected or its settings are
79 modified. To keep track of updated properties, the user should load new instances
80 of audioDevice from \l{MediaDevices} when the relevant signals are fired.
81
82 The list of audio input or output devices can be queried from the \l{MediaDevices}
83 type. To select a certain audio device for input or output set it as the device
84 on \l{AudioInput} or \l{AudioOutput}.
85
86 \qml
87 MediaPlayer {
88 audioOutput: AudioOutput {
89 device: mediaDevices.defaultAudioOutput
90 }
91 }
92 MediaDevices {
93 id: mediaDevices
94 }
95 \endqml
96*/
97
98/*!
99 Constructs a null QAudioDevice object.
100*/
101QAudioDevice::QAudioDevice() = default;
102
103/*!
104 Constructs a copy of \a other.
105*/
106QAudioDevice::QAudioDevice(const QAudioDevice &other) = default;
107
108/*!
109 \fn QAudioDevice::QAudioDevice(QAudioDevice &&other)
110
111 Move constructs from \a other.
112*/
113/*!
114 \fn void QAudioDevice::swap(QAudioDevice &other) noexcept
115
116 Swaps the audio device with the \a other.
117*/
118/*!
119 Destroy this audio device info.
120*/
121QAudioDevice::~QAudioDevice() = default;
122
123/*!
124 Sets the QAudioDevice object to be equal to \a other.
125*/
126QAudioDevice &QAudioDevice::operator=(const QAudioDevice &other) = default;
127
128/*!
129 \fn QAudioDevice& QAudioDevice::operator=(QAudioDevice &&other)
130
131 Moves \a other into this QAudioDevice object.
132*/
133
134/*!
135 Returns true if this QAudioDevice class represents the
136 same audio device as \a other.
137*/
138bool QAudioDevice::operator==(const QAudioDevice &other) const
139{
140 return mode() == other.mode() && id() == other.id();
141}
142
143/*!
144 Returns true if this QAudioDevice class represents a
145 different audio device than \a other
146*/
147bool QAudioDevice::operator!=(const QAudioDevice &other) const
148{
149 return !operator==(other);
150}
151
152/*!
153 Returns whether this QAudioDevice object holds a valid device definition.
154*/
155bool QAudioDevice::isNull() const
156{
157 return d == nullptr;
158}
159
160/*!
161 \qmlproperty string QtMultimedia::audioDevice::id
162
163 Holds an identifier for the audio device.
164
165 Device names vary depending on the platform/audio plugin being used.
166
167 They are a unique identifier for the audio device.
168*/
169
170/*!
171 \property QAudioDevice::id
172
173 Returns an identifier for the audio device.
174
175 Device names vary depending on the platform/audio plugin being used.
176
177 They are a unique identifier for the audio device.
178*/
179QByteArray QAudioDevice::id() const
180{
181 return isNull() ? QByteArray() : d->id;
182}
183
184/*!
185 \qmlproperty string QtMultimedia::audioDevice::description
186
187 Holds a human readable name of the audio device.
188
189 Use this string to present the device to the user.
190*/
191
192/*!
193 \property QAudioDevice::description
194
195 Returns a human readable name of the audio device.
196
197 Use this string to present the device to the user.
198*/
199QString QAudioDevice::description() const
200{
201 return isNull() ? QString() : d->description;
202}
203
204/*!
205 \qmlproperty bool QtMultimedia::audioDevice::isDefault
206
207 Is true if this is the default audio device.
208*/
209
210/*!
211 \property QAudioDevice::isDefault
212
213 Returns true if this is the default audio device.
214*/
215bool QAudioDevice::isDefault() const
216{
217 return d ? d->isDefault : false;
218}
219
220/*!
221 Returns true if the supplied \a settings are supported by the audio
222 device described by this QAudioDevice.
223*/
224bool QAudioDevice::isFormatSupported(const QAudioFormat &settings) const
225{
226 if (isNull())
227 return false;
228 if (settings.sampleRate() < d->minimumSampleRate
229 || settings.sampleRate() > d->maximumSampleRate)
230 return false;
231 if (settings.channelCount() < d->minimumChannelCount
232 || settings.channelCount() > d->maximumChannelCount)
233 return false;
234 if (!d->supportedSampleFormats.contains(t: settings.sampleFormat()))
235 return false;
236 return true;
237}
238
239/*!
240 Returns the default audio format settings for this device.
241
242 These settings are provided by the platform/audio plugin being used.
243
244 They are also dependent on the \l {QtAudio}::Mode being used.
245
246 A typical audio system would provide something like:
247 \list
248 \li Input settings: 48000Hz mono 16 bit.
249 \li Output settings: 48000Hz stereo 16 bit.
250 \endlist
251*/
252QAudioFormat QAudioDevice::preferredFormat() const
253{
254 return isNull() ? QAudioFormat() : d->preferredFormat;
255}
256
257/*!
258 Returns the minimum supported sample rate (in Hertz).
259*/
260int QAudioDevice::minimumSampleRate() const
261{
262 return isNull() ? 0 : d->minimumSampleRate;
263}
264
265/*!
266 Returns the maximum supported sample rate (in Hertz).
267*/
268int QAudioDevice::maximumSampleRate() const
269{
270 return isNull() ? 0 : d->maximumSampleRate;
271}
272
273/*!
274 Returns the minimum number of supported channel counts.
275
276 This is typically 1 for mono sound, or 2 for stereo sound.
277*/
278int QAudioDevice::minimumChannelCount() const
279{
280 return isNull() ? 0 : d->minimumChannelCount;
281}
282
283/*!
284 Returns the maximum number of supported channel counts.
285
286 This is typically 1 for mono sound, or 2 for stereo sound.
287*/
288int QAudioDevice::maximumChannelCount() const
289{
290 return isNull() ? 0 : d->maximumChannelCount;
291}
292
293/*!
294 Returns a list of supported sample types.
295*/
296QList<QAudioFormat::SampleFormat> QAudioDevice::supportedSampleFormats() const
297{
298 return isNull() ? QList<QAudioFormat::SampleFormat>() : d->supportedSampleFormats;
299}
300
301/*!
302 Returns the channel configuration of the device.
303*/
304QAudioFormat::ChannelConfig QAudioDevice::channelConfiguration() const
305{
306 return isNull() ? QAudioFormat::ChannelConfigUnknown : d->channelConfiguration;
307}
308
309/*!
310 \fn QAudioDevicePrivate QAudioDevice::handle() const
311 \internal
312*/
313/*!
314 \internal
315*/
316QAudioDevice::QAudioDevice(QAudioDevicePrivate *p) : d(p) { }
317
318/*!
319 \enum QAudioDevice::Mode
320
321 Describes the mode of this device.
322
323 \value Null
324 A null device.
325 \value Input
326 An input device.
327 \value Output
328 An output device.
329*/
330
331/*!
332 \qmlproperty enumeration QtMultimedia::audioDevice::mode
333
334 Holds whether this device is an input or output device.
335
336 The returned value can be one of the following:
337
338
339 \value audioDevice.Null A null device.
340 \value audioDevice.Input input device.
341 \value audioDevice.Output An output device.
342
343*/
344
345/*!
346 \property QAudioDevice::mode
347
348 Returns whether this device is an input or output device.
349*/
350QAudioDevice::Mode QAudioDevice::mode() const
351{
352 return d ? d->mode : Null;
353}
354
355#ifndef QT_NO_DEBUG_STREAM
356QDebug operator<<(QDebug dbg, QAudioDevice::Mode mode)
357{
358 QDebugStateSaver saver(dbg);
359 dbg.nospace();
360 switch (mode) {
361 case QAudioDevice::Input:
362 dbg << "QAudioDevice::Input";
363 break;
364 case QAudioDevice::Output:
365 dbg << "QAudioDevice::Output";
366 break;
367 case QAudioDevice::Null:
368 dbg << "QAudioDevice::Null";
369 break;
370 }
371 return dbg;
372}
373#endif
374
375QT_END_NAMESPACE
376
377#include "moc_qaudiodevice.cpp"
378

source code of qtmultimedia/src/multimedia/audio/qaudiodevice.cpp