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 22 of file qaudioformat.h.

Member Enumeration Documentation

◆ AudioChannelPosition

enum QAudioFormat::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 35 of file qaudioformat.h.

◆ ChannelConfig

enum QAudioFormat::ChannelConfig : quint32

\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 64 of file qaudioformat.h.

◆ SampleFormat

enum QAudioFormat::SampleFormat : quint16

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 25 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().

Here is the call 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().

Here is the call 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 112 of file qaudioformat.h.

References bytesPerSample(), and channelCount().

Referenced by bytesForDuration(), bytesForFrames(), QWindowsAudioUtils::formatToMediaType(), and framesForBytes().

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 113 of file qaudioformat.h.

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

Referenced by QOpenSLESEngine::audioFormatToSLFormatPCM(), bytesPerFrame(), and QWindowsAudioUtils::formatToWaveFormatExtensible().

Here is the caller graph for this function:

◆ channelConfig() [1/2]

ChannelConfig QAudioFormat::channelConfig ( ) const

inlineconstexprnoexcept

Returns the current channel configuration.

Definition at line 92 of file qaudioformat.h.

Referenced by QAmbisonicDecoder::QAmbisonicDecoder(), and QPulseAudioInternal::channelMapForAudioFormat().

Here is the caller graph for this function:

◆ channelConfig() [2/2]

template<typename... Args>

static constexpr ChannelConfig QAudioFormat::channelConfig ( Args... channels )

inlinestaticconstexpr

Returns the current channel configuration for the given channels.

Definition at line 78 of file qaudioformat.h.

◆ channelCount()

int QAudioFormat::channelCount ( ) const

inlineconstexprnoexcept

Returns the current channel count value.

Definition at line 95 of file qaudioformat.h.

Referenced by QAmbisonicDecoder::QAmbisonicDecoder(), QPulseAudioInternal::audioFormatToSampleSpec(), QOpenSLESEngine::audioFormatToSLFormatPCM(), bytesPerFrame(), QWindowsAudioUtils::formatToWaveFormatExtensible(), QOpenSLESEngine::getDefaultBufferSize(), and operator<<().

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.

◆ 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, ChannelConfig2Dot1, ChannelConfigMono, ChannelConfigStereo, ChannelConfigSurround5Dot0, ChannelConfigSurround5Dot1, ChannelConfigSurround7Dot0, ChannelConfigSurround7Dot1, ChannelConfigUnknown, FrontLeft, and FrontRight.

◆ 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 isValid().

Here is the call 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().

Here is the call 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().

Here is the call 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().

Here is the call graph for this function:

◆ isValid()

bool QAudioFormat::isValid ( ) const

inlineconstexprnoexcept

Returns true if all of the parameters are valid.

Definition at line 83 of file qaudioformat.h.

References Unknown.

Referenced by QFFmpegResampler::QFFmpegResampler(), durationForBytes(), durationForFrames(), QWindowsAudioUtils::formatToMediaType(), QWindowsAudioUtils::formatToWaveFormatExtensible(), framesForDuration(), QOpenSLESEngine::getDefaultBufferSize(), and makeQAudioDevicePrivate().

Here is the caller graph for this function:

◆ 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, NSampleFormats, and Unknown.

◆ sampleFormat()

SampleFormat QAudioFormat::sampleFormat ( ) const

inlineconstexprnoexcept

Returns the current sample format.

See also: setSampleFormat()

Definition at line 100 of file qaudioformat.h.

Referenced by QPulseAudioInternal::audioFormatToSampleSpec(), QOpenSLESEngine::audioFormatToSLFormatPCM(), QWindowsAudioUtils::formatToMediaType(), QWindowsAudioUtils::formatToWaveFormatExtensible(), QOpenSLESEngine::getDefaultBufferSize(), makeQAudioDevicePrivate(), and operator<<().

Here is the caller graph for this function:

◆ sampleRate()

int QAudioFormat::sampleRate ( ) const

inlineconstexprnoexcept

Returns the current sample rate in Hertz.

Definition at line 89 of file qaudioformat.h.

Referenced by QFFmpeg::AVAudioFormat::AVAudioFormat(), QAmbisonicDecoder::QAmbisonicDecoder(), QPulseAudioInternal::audioFormatToSampleSpec(), QOpenSLESEngine::audioFormatToSLFormatPCM(), durationForFrames(), QWindowsAudioUtils::formatToMediaType(), QWindowsAudioUtils::formatToWaveFormatExtensible(), QOpenSLESEngine::getDefaultBufferSize(), and operator<<().

Here is the caller graph for this function:

◆ 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 ChannelConfigUnknown.

Referenced by QAudioOutputStream::startOutput().

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 94 of file qaudioformat.h.

References ChannelConfigUnknown.

Referenced by makeQAudioDevicePrivate(), QWindowsAudioUtils::mediaTypeToFormat(), QPulseAudioInternal::sampleSpecToAudioFormat(), QAudioOutputStream::startOutput(), and QWindowsAudioUtils::waveFormatExToFormat().

Here is the caller graph for this function:

◆ setSampleFormat()

void QAudioFormat::setSampleFormat ( SampleFormat format )

inlineconstexprnoexcept

Sets the sample format to format.

See also: QAudioFormat::SampleFormat

Definition at line 99 of file qaudioformat.h.

Referenced by makeQAudioDevicePrivate(), QWindowsAudioUtils::mediaTypeToFormat(), QPulseAudioInternal::sampleSpecToAudioFormat(), QAudioOutputStream::startOutput(), and QWindowsAudioUtils::waveFormatExToFormat().

Here is the caller graph for this function:

◆ setSampleRate()

void QAudioFormat::setSampleRate ( int sampleRate )

inlineconstexprnoexcept

Sets the sample rate to samplerate in Hertz.

Definition at line 88 of file qaudioformat.h.

Referenced by makeQAudioDevicePrivate(), QWindowsAudioUtils::mediaTypeToFormat(), QPulseAudioInternal::sampleSpecToAudioFormat(), QAudioOutputStream::startOutput(), and QWindowsAudioUtils::waveFormatExToFormat().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ operator!=

bool 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 134 of file qaudioformat.h.

References operator==.

◆ operator==

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

friend

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

Definition at line 128 of file qaudioformat.h.

Referenced by operator!=.

Member Data Documentation

◆ NChannelPositions

int QAudioFormat::NChannelPositions = BottomFrontRight + 1

staticconstexpr

Definition at line 62 of file qaudioformat.h.

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

qtmultimedia/src/multimedia/audio/qaudioformat.h (31ae997c65240e772f63362b8ed34ef7e8d854b5)
qtmultimedia/src/multimedia/audio/qaudioformat.cpp (f364fd4c2f308745e7046bde58f7c109cb68baa4)

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ AudioChannelPosition

◆ ChannelConfig

◆ SampleFormat

Member Function Documentation

◆ bytesForDuration()

◆ bytesForFrames()

◆ bytesPerFrame()

◆ bytesPerSample()

◆ channelConfig() [1/2]

◆ channelConfig() [2/2]

◆ channelCount()

◆ channelOffset()

◆ defaultChannelConfigForChannelCount()

◆ durationForBytes()

◆ durationForFrames()

◆ framesForBytes()

◆ framesForDuration()

◆ isValid()

◆ normalizedSampleValue()

◆ sampleFormat()

◆ sampleRate()

◆ setChannelConfig()

◆ setChannelCount()

◆ setSampleFormat()

◆ setSampleRate()

Friends And Related Symbol Documentation

◆ operator!=

◆ operator==

Member Data Documentation

◆ NChannelPositions