Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
QAudioFormat Class Reference

The QAudioFormat class stores audio stream parameter information. More...

#include <qaudioformat.h>

+ Collaboration diagram for QAudioFormat:

Public Types

enum  SampleFormat : quint16 {
  Unknown , UInt8 , Int16 , Int32 ,
  Float , NSampleFormats
}
 Qt will always expect and use samples in the endianness of the host platform. More...
 
enum  AudioChannelPosition {
  UnknownPosition , FrontLeft , FrontRight , FrontCenter ,
  LFE , BackLeft , BackRight , FrontLeftOfCenter ,
  FrontRightOfCenter , BackCenter , SideLeft , SideRight ,
  TopCenter , TopFrontLeft , TopFrontCenter , TopFrontRight ,
  TopBackLeft , TopBackCenter , TopBackRight , LFE2 ,
  TopSideLeft , TopSideRight , BottomFrontCenter , BottomFrontLeft ,
  BottomFrontRight
}
 Describes the possible audio channel positions. More...
 
enum  ChannelConfig : quint32 {
  ChannelConfigUnknown = 0 , ChannelConfigMono = QtPrivate::channelConfig(FrontCenter) , ChannelConfigStereo = QtPrivate::channelConfig(FrontLeft, FrontRight) , ChannelConfig2Dot1 = QtPrivate::channelConfig(FrontLeft, FrontRight, LFE) ,
  ChannelConfig3Dot0 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter) , ChannelConfig3Dot1 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter, LFE) , ChannelConfigSurround5Dot0 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter, BackLeft, BackRight) , ChannelConfigSurround5Dot1 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter, LFE, BackLeft, BackRight) ,
  ChannelConfigSurround7Dot0 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter, BackLeft, BackRight, SideLeft, SideRight) , ChannelConfigSurround7Dot1 = QtPrivate::channelConfig(FrontLeft, FrontRight, FrontCenter, LFE, BackLeft, BackRight, SideLeft, SideRight)
}
 \variable QAudioFormat::NChannelPositions More...
 

Public Member Functions

constexpr bool isValid () const noexcept
 Returns true if all of the parameters are valid.
 
constexpr void setSampleRate (int sampleRate) noexcept
 Sets the sample rate to samplerate in Hertz.
 
constexpr int sampleRate () const noexcept
 Returns the current sample rate in Hertz.
 
Q_MULTIMEDIA_EXPORT void setChannelConfig (ChannelConfig config) noexcept
 Sets the channel configuration to config.
 
constexpr ChannelConfig channelConfig () const noexcept
 Returns the current channel configuration.
 
constexpr void setChannelCount (int channelCount) noexcept
 Sets the channel count to channels.
 
constexpr int channelCount () const noexcept
 Returns the current channel count value.
 
Q_MULTIMEDIA_EXPORT int channelOffset (AudioChannelPosition channel) const noexcept
 Returns the position of a certain audio channel inside an audio frame for the given format.
 
constexpr void setSampleFormat (SampleFormat f) noexcept
 Sets the sample format to format.
 
constexpr SampleFormat sampleFormat () const noexcept
 Returns the current sample format.
 
Q_MULTIMEDIA_EXPORT qint32 bytesForDuration (qint64 microseconds) const
 Returns the number of bytes required for this audio format for microseconds.
 
Q_MULTIMEDIA_EXPORT qint64 durationForBytes (qint32 byteCount) const
 Returns the number of microseconds represented by bytes in this format.
 
Q_MULTIMEDIA_EXPORT qint32 bytesForFrames (qint32 frameCount) const
 Returns the number of bytes required for frameCount frames of this format.
 
Q_MULTIMEDIA_EXPORT qint32 framesForBytes (qint32 byteCount) const
 Returns the number of frames represented by byteCount in this format.
 
Q_MULTIMEDIA_EXPORT qint32 framesForDuration (qint64 microseconds) const
 Returns the number of frames required to represent microseconds in this format.
 
Q_MULTIMEDIA_EXPORT qint64 durationForFrames (qint32 frameCount) const
 Return the number of microseconds represented by frameCount frames in this format.
 
constexpr int bytesPerFrame () const
 Returns the number of bytes required to represent one frame (a sample in each channel) in this format.
 
constexpr int bytesPerSample () const noexcept
 Returns the number of bytes required to represent one sample in this format.
 
Q_MULTIMEDIA_EXPORT float normalizedSampleValue (const void *sample) const
 Normalizes the sample value to a number between -1 and 1.
 

Static Public Member Functions

template<typename... Args>
static constexpr ChannelConfig channelConfig (Args... channels)
 Returns the current channel configuration for the given channels.
 
static Q_MULTIMEDIA_EXPORT ChannelConfig defaultChannelConfigForChannelCount (int channelCount)
 Returns a default channel configuration for channelCount.
 

Static Public Attributes

static constexpr int NChannelPositions = BottomFrontRight + 1
 

Friends

bool operator== (const QAudioFormat &a, const QAudioFormat &b)
 Returns true if audio format a is equal to b, otherwise returns false.
 
bool operator!= (const QAudioFormat &a, const QAudioFormat &b)
 Returns true if audio format a is not equal to b, otherwise returns false.
 

Detailed Description

The QAudioFormat class stores audio stream parameter information.

\inmodule QtMultimedia

An audio format specifies how data in a raw audio stream is arranged. For example, how the stream is to be interpreted.

QAudioFormat contains parameters that specify how the audio sample data is arranged. These are the frequency, the number of channels, and the sample format. The following table describes these in more detail.

\table \header

  • Parameter
  • Description \row
  • Sample Rate
  • Samples per second of audio data in Hertz. \row
  • Number of channels
  • The number of audio channels (typically one for mono or two for stereo). These are the amount of consecutive samples that together form one frame in the stream \row
  • Sample format
  • The format of the audio samples in the stream \endtable

This class is used in conjunction with QAudioSource or QAudioSink to allow you to specify the parameters of the audio stream being read or written, or with QAudioBuffer when dealing with samples in memory.

You can obtain audio formats compatible with the audio device used through functions in QAudioDevice. This class also lets you query available parameter values for a device, so that you can set the parameters yourself. See the \l QAudioDevice class description for details. You need to know the format of the audio streams you wish to play or record.

Samples for all channels will be interleaved. One sample for each channel for the same instant in time is referred to as a frame in Qt Multimedia (and other places).

Definition at line 24 of file qaudioformat.h.

Member Enumeration Documentation

◆ AudioChannelPosition

Describes the possible audio channel positions.

These follow the standard definition used in the 22.2 surround sound configuration.

\value UnknownPosition Unknown position \value FrontLeft \value FrontRight \value FrontCenter \value LFE Low Frequency Effect channel (Subwoofer) \value BackLeft \value BackRight \value FrontLeftOfCenter \value FrontRightOfCenter \value BackCenter \value LFE2 \value SideLeft \value SideRight \value TopFrontLeft \value TopFrontRight \value TopFrontCenter \value TopCenter \value TopBackLeft \value TopBackRight \value TopSideLeft \value TopSideRight \value TopBackCenter \value BottomFrontCenter \value BottomFrontLeft \value BottomFrontRight

Enumerator
UnknownPosition 
FrontLeft 
FrontRight 
FrontCenter 
LFE 
BackLeft 
BackRight 
FrontLeftOfCenter 
FrontRightOfCenter 
BackCenter 
SideLeft 
SideRight 
TopCenter 
TopFrontLeft 
TopFrontCenter 
TopFrontRight 
TopBackLeft 
TopBackCenter 
TopBackRight 
LFE2 
TopSideLeft 
TopSideRight 
BottomFrontCenter 
BottomFrontLeft 
BottomFrontRight 

Definition at line 37 of file qaudioformat.h.

◆ ChannelConfig

\variable QAudioFormat::NChannelPositions

This enum describes a standardized audio channel layout. The most common configurations are Mono, Stereo, 2.1 (stereo plus low frequency), 5.1 surround, and 7.1 surround configurations.

\value ChannelConfigUnknown The channel configuration is not known. \value ChannelConfigMono The audio has one Center channel. \value ChannelConfigStereo The audio has two channels, Left and Right. \value ChannelConfig2Dot1 The audio has three channels, Left, Right and LFE (low frequency effect). \value ChannelConfig3Dot0 The audio has three channels, Left, Right, and Center. \value ChannelConfig3Dot1 The audio has four channels, Left, Right, Center, and LFE (low frequency effect). \value ChannelConfigSurround5Dot0 The audio has five channels, Left, Right, Center, BackLeft, and BackRight. \value ChannelConfigSurround5Dot1 The audio has 6 channels, Left, Right, Center, LFE, BackLeft, and BackRight. \value ChannelConfigSurround7Dot0 The audio has 7 channels, Left, Right, Center, BackLeft, BackRight, SideLeft, and SideRight. \value ChannelConfigSurround7Dot1 The audio has 8 channels, Left, Right, Center, LFE, BackLeft, BackRight, SideLeft, and SideRight.

Enumerator
ChannelConfigUnknown 
ChannelConfigMono 
ChannelConfigStereo 
ChannelConfig2Dot1 
ChannelConfig3Dot0 
ChannelConfig3Dot1 
ChannelConfigSurround5Dot0 
ChannelConfigSurround5Dot1 
ChannelConfigSurround7Dot0 
ChannelConfigSurround7Dot1 

Definition at line 66 of file qaudioformat.h.

◆ SampleFormat

Qt will always expect and use samples in the endianness of the host platform.

When processing audio data from external sources yourself, ensure you convert them to the correct endianness before writing them to a QAudioSink or QAudioBuffer.

\value Unknown Not Set \value UInt8 Samples are 8 bit unsigned integers \value Int16 Samples are 16 bit signed integers \value Int32 Samples are 32 bit signed integers \value Float Samples are floats \omitvalue NSampleFormats

Enumerator
Unknown 
UInt8 
Int16 
Int32 
Float 
NSampleFormats 

Definition at line 27 of file qaudioformat.h.

Member Function Documentation

◆ bytesForDuration()

qint32 QAudioFormat::bytesForDuration ( qint64 microseconds) const

Returns the number of bytes required for this audio format for microseconds.

Returns 0 if this format is not valid.

Note that some rounding may occur if microseconds is not an exact fraction of the sampleRate().

See also
durationForBytes()

Definition at line 256 of file qaudioformat.cpp.

References bytesPerFrame(), and framesForDuration().

Referenced by QWindowsAudioSource::bytesReady(), QWindowsResampler::inputBufferSize(), QWindowsResampler::outputBufferSize(), QWasmAudioSink::processedUSecs(), QWasmAudioSink::setFormat(), QWasmAudioSource::setFormat(), and QFFmpeg::AudioRenderer::updateOutput().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ bytesForFrames()

qint32 QAudioFormat::bytesForFrames ( qint32 frameCount) const

Returns the number of bytes required for frameCount frames of this format.

Returns 0 if this format is not valid.

See also
bytesForDuration()

Definition at line 291 of file qaudioformat.cpp.

References bytesPerFrame().

Referenced by QWasmAudioSource::bytesReady(), QWasmAudioSourceDevice::readData(), and QFFmpeg::AudioSourceIO::setFrameSize().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ bytesPerFrame()

int QAudioFormat::bytesPerFrame ( ) const
inlineconstexpr

Returns the number of bytes required to represent one frame (a sample in each channel) in this format.

Returns 0 if this format is invalid.

Definition at line 114 of file qaudioformat.h.

References bytesPerSample(), and channelCount().

Referenced by bytesForDuration(), bytesForFrames(), QWindowsAudioSink::bytesFree(), durationForBytes(), framesForBytes(), QAlsaAudioSource::processedUSecs(), QGStreamerAudioSink::processedUSecs(), and CoreAudioUtils::toAudioStreamBasicDescription().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ bytesPerSample()

int QAudioFormat::bytesPerSample ( ) const
inlineconstexprnoexcept

Returns the number of bytes required to represent one sample in this format.

Returns 0 if this format is invalid.

Definition at line 115 of file qaudioformat.h.

References Float, Int16, Int32, NSampleFormats, UInt8, and Unknown.

Referenced by bytesPerFrame(), and CoreAudioUtils::toAudioStreamBasicDescription().

+ Here is the caller graph for this function:

◆ channelConfig() [1/2]

QAudioFormat::ChannelConfig QAudioFormat::channelConfig ( ) const
inlineconstexprnoexcept

Returns the current channel configuration.

Definition at line 94 of file qaudioformat.h.

Referenced by QAmbisonicDecoder::QAmbisonicDecoder(), QFFmpegMediaFormatInfo::channelConfigForAVLayout(), QPulseAudioInternal::channelConfigFromMap(), channelConfigToMask(), QPulseAudioInternal::channelMapForAudioFormat(), defaultChannelConfigForChannelCount(), CoreAudioUtils::fromAudioChannelLayout(), QWindowsAudioUtils::maskToChannelConfig(), and CoreAudioUtils::toAudioChannelLayout().

+ Here is the caller graph for this function:

◆ channelConfig() [2/2]

template<typename... Args>
template< typename... Args > QAudioFormat::ChannelConfig QAudioFormat::channelConfig ( Args... channels)
inlinestaticconstexpr

Returns the current channel configuration for the given channels.

Definition at line 80 of file qaudioformat.h.

References QtPrivate::channelConfig().

Referenced by QFFmpeg::AVAudioFormat::AVAudioFormat().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ channelCount()

int QAudioFormat::channelCount ( ) const
inlineconstexprnoexcept

Returns the current channel count value.

Definition at line 97 of file qaudioformat.h.

Referenced by QFFmpeg::AVAudioFormat::AVAudioFormat(), bytesPerFrame(), defaultChannelConfigForChannelCount(), QAudioBuffer::sampleCount(), setChannelCount(), QWasmAudioSink::start(), QWasmAudioSource::start(), QAudioOutputStream::startOutput(), and CoreAudioUtils::toAudioStreamBasicDescription().

+ Here is the caller graph for this function:

◆ channelOffset()

int QAudioFormat::channelOffset ( AudioChannelPosition channel) const
noexcept

Returns the position of a certain audio channel inside an audio frame for the given format.

Returns -1 if the channel does not exist for this format or the channel configuration is unknown.

Definition at line 197 of file qaudioformat.cpp.

References channel, and qPopulationCount().

+ Here is the call graph for this function:

◆ defaultChannelConfigForChannelCount()

QAudioFormat::ChannelConfig QAudioFormat::defaultChannelConfigForChannelCount ( int channelCount)
static

Returns a default channel configuration for channelCount.

Default configurations are defined for up to 8 channels, and correspond to standard Mono, Stereo and Surround configurations. For higher channel counts, this simply uses the first channelCount audio channels defined in \l QAudioFormat::AudioChannelPosition.

Definition at line 390 of file qaudioformat.cpp.

References BackLeft, BackRight, channelConfig(), ChannelConfig2Dot1, ChannelConfigMono, ChannelConfigStereo, ChannelConfigSurround5Dot0, ChannelConfigSurround5Dot1, ChannelConfigSurround7Dot0, ChannelConfigSurround7Dot1, ChannelConfigUnknown, channelCount(), FrontLeft, and FrontRight.

Referenced by QFFmpeg::AVAudioFormat::AVAudioFormat(), QFFmpeg::AVAudioFormat::AVAudioFormat(), QFFmpeg::AVAudioFormat::AVAudioFormat(), QWindowsAudioDeviceInfo::QWindowsAudioDeviceInfo(), QFFmpegMediaFormatInfo::audioFormatFromCodecParameters(), QPulseAudioInternal::channelMapForAudioFormat(), QSoundEffectPrivate::sampleReady(), and CoreAudioUtils::toAudioChannelLayout().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ durationForBytes()

qint64 QAudioFormat::durationForBytes ( qint32 bytes) const

Returns the number of microseconds represented by bytes in this format.

Returns 0 if this format is not valid.

Note that some rounding may occur if bytes is not an exact multiple of the number of bytes per frame.

See also
bytesForDuration()

Definition at line 271 of file qaudioformat.cpp.

References bytesPerFrame(), isValid(), Q_UNUSED, and sampleRate().

Referenced by QFFmpeg::AudioRenderer::durationForBytes(), QWindowsResampler::inputBufferSize(), QWindowsResampler::outputBufferSize(), QAndroidAudioSource::processedUSecs(), QAndroidAudioSink::processedUSecs(), QWasmAudioSink::processedUSecs(), QWasmAudioSource::processedUSecs(), QWindowsAudioSink::processedUSecs(), QWindowsAudioSource::processedUSecs(), QGStreamerAudioSource::processedUSecs(), and QWasmAudioSource::start().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ durationForFrames()

qint64 QAudioFormat::durationForFrames ( qint32 frameCount) const

Return the number of microseconds represented by frameCount frames in this format.

Definition at line 331 of file qaudioformat.cpp.

References isValid(), and sampleRate().

Referenced by QWindowsAudioSource::bytesReady(), QAudioBuffer::duration(), and QFFmpeg::AudioEncoder::processOne().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ framesForBytes()

qint32 QAudioFormat::framesForBytes ( qint32 byteCount) const

Returns the number of frames represented by byteCount in this format.

Note that some rounding may occur if byteCount is not an exact multiple of the number of bytes per frame.

Each frame has one sample per channel.

See also
framesForDuration()

Definition at line 306 of file qaudioformat.cpp.

References bytesPerFrame().

Referenced by QAudioBuffer::frameCount(), QQnxAudioSink::processedUSecs(), QQnxAudioSource::processedUSecs(), QWasmAudioSourceDevice::readData(), QFFmpegResampler::resample(), and QWasmAudioSource::start().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ framesForDuration()

qint32 QAudioFormat::framesForDuration ( qint64 microseconds) const

Returns the number of frames required to represent microseconds in this format.

Note that some rounding may occur if microseconds is not an exact fraction of the \l sampleRate().

Definition at line 320 of file qaudioformat.cpp.

References isValid(), and sampleRate().

Referenced by bytesForDuration().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ isValid()

bool QAudioFormat::isValid ( ) const
inlineconstexprnoexcept

◆ normalizedSampleValue()

float QAudioFormat::normalizedSampleValue ( const void * sample) const

Normalizes the sample value to a number between -1 and 1.

The method depends on the QaudioFormat.

Definition at line 359 of file qaudioformat.cpp.

References Float, Int16, Int32, NSampleFormats, UInt8, and Unknown.

◆ sampleFormat()

QAudioFormat::SampleFormat QAudioFormat::sampleFormat ( ) const
inlineconstexprnoexcept

Returns the current sample format.

See also
setSampleFormat()

Definition at line 102 of file qaudioformat.h.

Referenced by QWasmAudioSink::start(), QWasmAudioSource::start(), and CoreAudioUtils::toAudioStreamBasicDescription().

+ Here is the caller graph for this function:

◆ sampleRate()

◆ setChannelConfig()

void QAudioFormat::setChannelConfig ( ChannelConfig config)
noexcept

Sets the channel configuration to config.

Sets the channel configuration of the audio format to one of the standard audio channel configurations.

Note
that this will also modify the channel count.

Definition at line 184 of file qaudioformat.cpp.

References qPopulationCount().

Referenced by QFFmpeg::AudioRenderer::updateOutput().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setChannelCount()

void QAudioFormat::setChannelCount ( int channels)
inlineconstexprnoexcept

Sets the channel count to channels.

Setting this also sets the channel config to ChannelConfigUnknown.

Definition at line 96 of file qaudioformat.h.

References ChannelConfigUnknown, and channelCount().

Referenced by QAlsaAudioDeviceInfo::QAlsaAudioDeviceInfo(), QGStreamerAudioDeviceInfo::QGStreamerAudioDeviceInfo(), QnxAudioDeviceInfo::QnxAudioDeviceInfo(), QOpenSLESDeviceInfo::QOpenSLESDeviceInfo(), QPulseAudioDeviceInfo::QPulseAudioDeviceInfo(), QWasmAudioDevice::QWasmAudioDevice(), QWindowsAudioDeviceInfo::QWindowsAudioDeviceInfo(), AudioDecodingExample::decode(), QWindowsAudioUtils::mediaTypeToFormat(), and CoreAudioUtils::toQAudioFormat().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setSampleFormat()

◆ setSampleRate()

void QAudioFormat::setSampleRate ( int sampleRate)
inlineconstexprnoexcept

Sets the sample rate to samplerate in Hertz.

Definition at line 90 of file qaudioformat.h.

References sampleRate().

Referenced by QAlsaAudioDeviceInfo::QAlsaAudioDeviceInfo(), QGStreamerAudioDeviceInfo::QGStreamerAudioDeviceInfo(), QnxAudioDeviceInfo::QnxAudioDeviceInfo(), QOpenSLESDeviceInfo::QOpenSLESDeviceInfo(), QPulseAudioDeviceInfo::QPulseAudioDeviceInfo(), QWasmAudioDevice::QWasmAudioDevice(), QWindowsAudioDeviceInfo::QWindowsAudioDeviceInfo(), AudioDeviceInfo(), QFFmpeg::AudioRenderer::initResempler(), QPulseAudioInternal::sampleSpecToAudioFormat(), AudioInputExample::setup(), AudioOutputExample::setup(), and CoreAudioUtils::toQAudioFormat().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ operator!=

bool QAudioFormat::operator!= ( const QAudioFormat & a,
const QAudioFormat & b )
friend

Returns true if audio format a is not equal to b, otherwise returns false.

Definition at line 136 of file qaudioformat.h.

◆ operator==

bool QAudioFormat::operator== ( const QAudioFormat & a,
const QAudioFormat & b )
friend

Returns true if audio format a is equal to b, otherwise returns false.

Definition at line 130 of file qaudioformat.h.

Member Data Documentation

◆ NChannelPositions

constexpr int QAudioFormat::NChannelPositions = BottomFrontRight + 1
staticconstexpr

Definition at line 64 of file qaudioformat.h.

Referenced by CoreAudioUtils::toAudioChannelLayout().


The documentation for this class was generated from the following files: