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

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