1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39#include <QDebug>
40#include <qaudioformat.h>
41
42
43QT_BEGIN_NAMESPACE
44
45static void qRegisterAudioFormatMetaTypes()
46{
47 qRegisterMetaType<QAudioFormat>();
48 qRegisterMetaType<QAudioFormat::SampleType>();
49 qRegisterMetaType<QAudioFormat::Endian>();
50}
51
52Q_CONSTRUCTOR_FUNCTION(qRegisterAudioFormatMetaTypes)
53
54class QAudioFormatPrivate : public QSharedData
55{
56public:
57 QAudioFormatPrivate()
58 {
59 sampleRate = -1;
60 channels = -1;
61 sampleSize = -1;
62 byteOrder = QAudioFormat::Endian(QSysInfo::ByteOrder);
63 sampleType = QAudioFormat::Unknown;
64 }
65
66 QAudioFormatPrivate(const QAudioFormatPrivate &other):
67 QSharedData(other),
68 codec(other.codec),
69 byteOrder(other.byteOrder),
70 sampleType(other.sampleType),
71 sampleRate(other.sampleRate),
72 channels(other.channels),
73 sampleSize(other.sampleSize)
74 {
75 }
76
77 QAudioFormatPrivate& operator=(const QAudioFormatPrivate &other)
78 {
79 codec = other.codec;
80 byteOrder = other.byteOrder;
81 sampleType = other.sampleType;
82 sampleRate = other.sampleRate;
83 channels = other.channels;
84 sampleSize = other.sampleSize;
85
86 return *this;
87 }
88
89 QString codec;
90 QAudioFormat::Endian byteOrder;
91 QAudioFormat::SampleType sampleType;
92 int sampleRate;
93 int channels;
94 int sampleSize;
95};
96
97/*!
98 \class QAudioFormat
99 \brief The QAudioFormat class stores audio stream parameter information.
100
101 \inmodule QtMultimedia
102 \ingroup multimedia
103 \ingroup multimedia_audio
104
105 An audio format specifies how data in an audio stream is arranged,
106 i.e, how the stream is to be interpreted. The encoding itself is
107 specified by the codec() used for the stream.
108
109 In addition to the encoding, QAudioFormat contains other
110 parameters that further specify how the audio sample data is arranged.
111 These are the frequency, the number of channels, the sample size,
112 the sample type, and the byte order. The following table describes
113 these in more detail.
114
115 \table
116 \header
117 \li Parameter
118 \li Description
119 \row
120 \li Sample Rate
121 \li Samples per second of audio data in Hertz.
122 \row
123 \li Number of channels
124 \li The number of audio channels (typically one for mono
125 or two for stereo)
126 \row
127 \li Sample size
128 \li How much data is stored in each sample (typically 8
129 or 16 bits)
130 \row
131 \li Sample type
132 \li Numerical representation of sample (typically signed integer,
133 unsigned integer or float)
134 \row
135 \li Byte order
136 \li Byte ordering of sample (typically little endian, big endian)
137 \endtable
138
139 This class is typically used in conjunction with QAudioInput or
140 QAudioOutput to allow you to specify the parameters of the audio
141 stream being read or written, or with QAudioBuffer when dealing with
142 samples in memory.
143
144 You can obtain audio formats compatible with the audio device used
145 through functions in QAudioDeviceInfo. This class also lets you
146 query available parameter values for a device, so that you can set
147 the parameters yourself. See the \l QAudioDeviceInfo class
148 description for details. You need to know the format of the audio
149 streams you wish to play or record.
150
151 In the common case of interleaved linear PCM data, the codec will
152 be "audio/pcm", and the samples for all channels will be interleaved.
153 One sample for each channel for the same instant in time is referred
154 to as a frame in Qt Multimedia (and other places).
155*/
156
157/*!
158 Construct a new audio format.
159
160 Values are initialized as follows:
161 \list
162 \li sampleRate() = -1
163 \li channelCount() = -1
164 \li sampleSize() = -1
165 \li byteOrder() = QAudioFormat::Endian(QSysInfo::ByteOrder)
166 \li sampleType() = QAudioFormat::Unknown
167 \c codec() = ""
168 \endlist
169*/
170QAudioFormat::QAudioFormat():
171 d(new QAudioFormatPrivate)
172{
173}
174
175/*!
176 Construct a new audio format using \a other.
177*/
178QAudioFormat::QAudioFormat(const QAudioFormat &other):
179 d(other.d)
180{
181}
182
183/*!
184 Destroy this audio format.
185*/
186QAudioFormat::~QAudioFormat()
187{
188}
189
190/*!
191 Assigns \a other to this QAudioFormat implementation.
192*/
193QAudioFormat& QAudioFormat::operator=(const QAudioFormat &other)
194{
195 d = other.d;
196 return *this;
197}
198
199/*!
200 Returns true if this QAudioFormat is equal to the \a other
201 QAudioFormat; otherwise returns false.
202
203 All elements of QAudioFormat are used for the comparison.
204*/
205bool QAudioFormat::operator==(const QAudioFormat &other) const
206{
207 return d->sampleRate == other.d->sampleRate &&
208 d->channels == other.d->channels &&
209 d->sampleSize == other.d->sampleSize &&
210 d->byteOrder == other.d->byteOrder &&
211 d->codec == other.d->codec &&
212 d->sampleType == other.d->sampleType;
213}
214
215/*!
216 Returns true if this QAudioFormat is not equal to the \a other
217 QAudioFormat; otherwise returns false.
218
219 All elements of QAudioFormat are used for the comparison.
220*/
221bool QAudioFormat::operator!=(const QAudioFormat& other) const
222{
223 return !(*this == other);
224}
225
226/*!
227 Returns true if all of the parameters are valid.
228*/
229bool QAudioFormat::isValid() const
230{
231 return d->sampleRate != -1 && d->channels != -1 && d->sampleSize != -1 &&
232 d->sampleType != QAudioFormat::Unknown && !d->codec.isEmpty();
233}
234
235/*!
236 Sets the sample rate to \a samplerate Hertz.
237
238*/
239void QAudioFormat::setSampleRate(int samplerate)
240{
241 d->sampleRate = samplerate;
242}
243
244/*!
245 Returns the current sample rate in Hertz.
246
247*/
248int QAudioFormat::sampleRate() const
249{
250 return d->sampleRate;
251}
252
253/*!
254 Sets the channel count to \a channels.
255
256*/
257void QAudioFormat::setChannelCount(int channels)
258{
259 d->channels = channels;
260}
261
262/*!
263 Returns the current channel count value.
264
265*/
266int QAudioFormat::channelCount() const
267{
268 return d->channels;
269}
270
271/*!
272 Sets the sample size to the \a sampleSize specified, in bits.
273
274 This is typically 8 or 16, but some systems may support higher sample sizes.
275*/
276void QAudioFormat::setSampleSize(int sampleSize)
277{
278 d->sampleSize = sampleSize;
279}
280
281/*!
282 Returns the current sample size value, in bits.
283
284 \sa bytesPerFrame()
285*/
286int QAudioFormat::sampleSize() const
287{
288 return d->sampleSize;
289}
290
291/*!
292 Sets the codec to \a codec.
293
294 The parameter to this function should be one of the types
295 reported by the QAudioDeviceInfo::supportedCodecs() function
296 for the audio device you are working with.
297
298 \sa QAudioDeviceInfo::supportedCodecs()
299*/
300void QAudioFormat::setCodec(const QString &codec)
301{
302 d->codec = codec;
303}
304
305/*!
306 Returns the current codec identifier.
307
308 \sa QAudioDeviceInfo::supportedCodecs()
309*/
310QString QAudioFormat::codec() const
311{
312 return d->codec;
313}
314
315/*!
316 Sets the byteOrder to \a byteOrder.
317*/
318void QAudioFormat::setByteOrder(QAudioFormat::Endian byteOrder)
319{
320 d->byteOrder = byteOrder;
321}
322
323/*!
324 Returns the current byteOrder value.
325*/
326QAudioFormat::Endian QAudioFormat::byteOrder() const
327{
328 return d->byteOrder;
329}
330
331/*!
332 Sets the sampleType to \a sampleType.
333*/
334void QAudioFormat::setSampleType(QAudioFormat::SampleType sampleType)
335{
336 d->sampleType = sampleType;
337}
338
339/*!
340 Returns the current SampleType value.
341*/
342QAudioFormat::SampleType QAudioFormat::sampleType() const
343{
344 return d->sampleType;
345}
346
347/*!
348 Returns the number of bytes required for this audio format for \a duration microseconds.
349
350 Returns 0 if this format is not valid.
351
352 Note that some rounding may occur if \a duration is not an exact fraction of the
353 sampleRate().
354
355 \sa durationForBytes()
356 */
357qint32 QAudioFormat::bytesForDuration(qint64 duration) const
358{
359 return bytesPerFrame() * framesForDuration(duration);
360}
361
362/*!
363 Returns the number of microseconds represented by \a bytes in this format.
364
365 Returns 0 if this format is not valid.
366
367 Note that some rounding may occur if \a bytes is not an exact multiple
368 of the number of bytes per frame.
369
370 \sa bytesForDuration()
371*/
372qint64 QAudioFormat::durationForBytes(qint32 bytes) const
373{
374 if (!isValid() || bytes <= 0)
375 return 0;
376
377 // We round the byte count to ensure whole frames
378 return qint64(1000000LL * (bytes / bytesPerFrame())) / sampleRate();
379}
380
381/*!
382 Returns the number of bytes required for \a frameCount frames of this format.
383
384 Returns 0 if this format is not valid.
385
386 \sa bytesForDuration()
387*/
388qint32 QAudioFormat::bytesForFrames(qint32 frameCount) const
389{
390 return frameCount * bytesPerFrame();
391}
392
393/*!
394 Returns the number of frames represented by \a byteCount in this format.
395
396 Note that some rounding may occur if \a byteCount is not an exact multiple
397 of the number of bytes per frame.
398
399 Each frame has one sample per channel.
400
401 \sa framesForDuration()
402*/
403qint32 QAudioFormat::framesForBytes(qint32 byteCount) const
404{
405 int size = bytesPerFrame();
406 if (size > 0)
407 return byteCount / size;
408 return 0;
409}
410
411/*!
412 Returns the number of frames required to represent \a duration microseconds in this format.
413
414 Note that some rounding may occur if \a duration is not an exact fraction of the
415 \l sampleRate().
416*/
417qint32 QAudioFormat::framesForDuration(qint64 duration) const
418{
419 if (!isValid())
420 return 0;
421
422 return qint32((duration * sampleRate()) / 1000000LL);
423}
424
425/*!
426 Return the number of microseconds represented by \a frameCount frames in this format.
427*/
428qint64 QAudioFormat::durationForFrames(qint32 frameCount) const
429{
430 if (!isValid() || frameCount <= 0)
431 return 0;
432
433 return (frameCount * 1000000LL) / sampleRate();
434}
435
436/*!
437 Returns the number of bytes required to represent one frame (a sample in each channel) in this format.
438
439 Returns 0 if this format is invalid.
440*/
441int QAudioFormat::bytesPerFrame() const
442{
443 if (!isValid())
444 return 0;
445
446 return (sampleSize() * channelCount()) / 8;
447}
448
449/*!
450 \enum QAudioFormat::SampleType
451
452 \value Unknown Not Set
453 \value SignedInt Samples are signed integers
454 \value UnSignedInt Samples are unsigned intergers
455 \value Float Samples are floats
456*/
457
458/*!
459 \enum QAudioFormat::Endian
460
461 \value BigEndian Samples are big endian byte order
462 \value LittleEndian Samples are little endian byte order
463*/
464
465#ifndef QT_NO_DEBUG_STREAM
466QDebug operator<<(QDebug dbg, QAudioFormat::Endian endian)
467{
468 QDebugStateSaver saver(dbg);
469 dbg.nospace();
470 switch (endian) {
471 case QAudioFormat::BigEndian:
472 dbg << "BigEndian";
473 break;
474 case QAudioFormat::LittleEndian:
475 dbg << "LittleEndian";
476 break;
477 }
478 return dbg;
479}
480
481QDebug operator<<(QDebug dbg, QAudioFormat::SampleType type)
482{
483 QDebugStateSaver saver(dbg);
484 dbg.nospace();
485 switch (type) {
486 case QAudioFormat::SignedInt:
487 dbg << "SignedInt";
488 break;
489 case QAudioFormat::UnSignedInt:
490 dbg << "UnSignedInt";
491 break;
492 case QAudioFormat::Float:
493 dbg << "Float";
494 break;
495 default:
496 dbg << "Unknown";
497 break;
498 }
499 return dbg;
500}
501
502QDebug operator<<(QDebug dbg, const QAudioFormat &f)
503{
504 QDebugStateSaver saver(dbg);
505 dbg.nospace();
506 dbg << "QAudioFormat(" << f.sampleRate() << "Hz, "
507 << f.sampleSize() << "bit, channelCount=" << f.channelCount()
508 << ", sampleType=" << f.sampleType() << ", byteOrder=" << f.byteOrder()
509 << ", codec=" << f.codec() << ')';
510
511 return dbg;
512}
513#endif
514
515
516
517QT_END_NAMESPACE
518
519

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