Describes an audio format including sample type, rate, and channel count. More...

#include <audiodesc.h>

Classes
struct	Format
	Descriptor for a specific audio sample format. More...

Public Types
enum	DataType { Invalid = 0 , PCMI_Float32LE , PCMI_Float32BE , PCMI_S8 , PCMI_U8 , PCMI_S16LE , PCMI_U16LE , PCMI_S16BE , PCMI_U16BE , PCMI_S24LE , PCMI_U24LE , PCMI_S24BE , PCMI_U24BE , PCMI_S32LE , PCMI_U32LE , PCMI_S32BE , PCMI_U32BE }
	Enumeration of supported audio sample data types. More...

using	Ptr = SharedPtr< AudioDesc >
	Shared pointer type for AudioDesc.

Public Member Functions
	AudioDesc ()
	Constructs an invalid (default) audio description.

	AudioDesc (float sr, unsigned int ch)
	Constructs an audio description with the native float format.

	AudioDesc (DataType dt, float sr, unsigned int ch)
	Constructs an audio description with the specified data type, sample rate, and channels.

bool	formatEquals (const AudioDesc &other) const
	Returns true if both audio descriptions have equal format (type, rate, channels).

bool	operator== (const AudioDesc &other) const
	Returns true if both audio descriptions are fully equal, including metadata.

bool	isValid () const
	Returns true if this audio description has a valid data type, sample rate, and channel count.

bool	isNative () const
	Returns true if the data type is the platform's native float format.

AudioDesc	workingDesc () const
	Returns a new AudioDesc with the same sample rate and channels but using the native float format.

String	toString () const
	Returns a human-readable string representation of this audio description.

JsonObject	toJson () const
	Serializes this audio description to a JSON object.

size_t	bytesPerSample () const
	Returns the number of bytes per single sample.

size_t	bytesPerSampleStride () const
	Returns the byte stride between consecutive samples of the same channel.

size_t	channelBufferOffset (unsigned int chan, size_t bufferSamples) const
	Returns the byte offset to a specific channel within a sample buffer.

size_t	bufferSize (size_t samples) const
	Returns the total buffer size in bytes needed to store the given number of samples.

DataType	dataType () const
	Returns the data type of this audio description.

void	setDataType (DataType val)
	Sets the data type.

float	sampleRate () const
	Returns the sample rate in Hz.

void	setSampleRate (float val)
	Sets the sample rate.

unsigned int	channels () const
	Returns the number of audio channels.

void	setChannels (unsigned int val)
	Sets the number of audio channels.

const Metadata &	metadata () const
	Returns a const reference to the metadata.

Metadata &	metadata ()
	Returns a mutable reference to the metadata.

void	samplesToFloat (float out, const uint8_t in, size_t samples) const
	Converts samples from this description's format to normalized floats.

void	floatToSamples (uint8_t out, const float in, size_t samples) const
	Converts normalized floats to samples in this description's format.

Static Public Member Functions
template<typename IntegerType , IntegerType Min, IntegerType Max>
static float	integerToFloat (IntegerType value)
	Converts an integer sample value to a normalized float in [-1, 1].

template<typename IntegerType >
static float	integerToFloat (IntegerType value)
	Converts an integer sample value to a normalized float using the type's full range.

template<typename IntegerType , IntegerType Min, IntegerType Max>
static IntegerType	floatToInteger (float value)
	Converts a normalized float in [-1, 1] to an integer sample value.

template<typename IntegerType >
static IntegerType	floatToInteger (float value)
	Converts a normalized float to an integer sample using the type's full range.

template<typename IntegerType , bool InputIsBigEndian>
static void	samplesToFloat (float out, const uint8_t inbuf, size_t samples)
	Converts a buffer of integer samples to normalized floats.

template<typename IntegerType , bool OutputIsBigEndian>
static void	floatToSamples (uint8_t outbuf, const float in, size_t samples)
	Converts a buffer of normalized floats to integer samples.

static const Format *	lookupFormat (int id)
	Looks up a Format descriptor by its DataType id.

static DataType	stringToDataType (const String &val)
	Converts a string name to its corresponding DataType enum value.

static AudioDesc	fromJson (const JsonObject &json, Error *err=nullptr)
	Constructs an AudioDesc from a JSON object.

Static Public Attributes
static const int32_t	MinS24 = -8388608
	Minimum value of a signed 24-bit integer.

static const int32_t	MaxS24 = 8388607
	Maximum value of a signed 24-bit integer.

static const int32_t	MinU24 = 0
	Minimum value of an unsigned 24-bit integer.

static const int32_t	MaxU24 = 16777215
	Maximum value of an unsigned 24-bit integer.

static constexpr DataType	NativeType = System::isLittleEndian() ? PCMI_Float32LE : PCMI_Float32BE
	The native float format for the current platform's endianness.

Detailed Description

Describes an audio format including sample type, rate, and channel count.

AudioDesc encapsulates the complete description of an audio format: the sample data type (e.g. PCM signed 16-bit little-endian), sample rate, and number of channels. It also provides static utility methods for converting between integer sample representations and normalized floating-point values in the range [-1, 1].

Member Enumeration Documentation

◆ DataType

enum AudioDesc::DataType

Enumeration of supported audio sample data types.

PCMI = PCM audio with interleaved channels. PCMP = PCM audio with planar channels.

Enumerator
Invalid	Invalid / unset format.
PCMI_Float32LE	32-bit float, little-endian, interleaved.
PCMI_Float32BE	32-bit float, big-endian, interleaved.
PCMI_S8	Signed 8-bit integer, interleaved.
PCMI_U8	Unsigned 8-bit integer, interleaved.
PCMI_S16LE	Signed 16-bit integer, little-endian, interleaved.
PCMI_U16LE	Unsigned 16-bit integer, little-endian, interleaved.
PCMI_S16BE	Signed 16-bit integer, big-endian, interleaved.
PCMI_U16BE	Unsigned 16-bit integer, big-endian, interleaved.
PCMI_S24LE	Signed 24-bit integer, little-endian, interleaved.
PCMI_U24LE	Unsigned 24-bit integer, little-endian, interleaved.
PCMI_S24BE	Signed 24-bit integer, big-endian, interleaved.
PCMI_U24BE	Unsigned 24-bit integer, big-endian, interleaved.
PCMI_S32LE	Signed 32-bit integer, little-endian, interleaved.
PCMI_U32LE	Unsigned 32-bit integer, little-endian, interleaved.
PCMI_S32BE	Signed 32-bit integer, big-endian, interleaved.
PCMI_U32BE	Unsigned 32-bit integer, big-endian, interleaved.

Constructor & Destructor Documentation

◆ AudioDesc() [1/2]

AudioDesc::AudioDesc	(	float	sr,
		unsigned int	ch
	)

inline

Constructs an audio description with the native float format.

If the resulting description is not valid, all fields are reset to invalid.

Parameters

sr	Sample rate in Hz.
ch	Number of audio channels.

◆ AudioDesc() [2/2]

AudioDesc::AudioDesc	(	DataType	dt,
		float	sr,
		unsigned int	ch
	)

inline

Constructs an audio description with the specified data type, sample rate, and channels.

If the resulting description is not valid, all fields are reset to invalid.

Parameters

dt	Data type (sample format).
sr	Sample rate in Hz.
ch	Number of audio channels.

Member Function Documentation

◆ bufferSize()

size_t AudioDesc::bufferSize ( size_t samples ) const

inline

Returns the total buffer size in bytes needed to store the given number of samples.

Parameters

samples Number of samples per channel.

Returns: Total size in bytes (bytesPerSample * channels * samples).

◆ bytesPerSample()

size_t AudioDesc::bytesPerSample ( ) const

inline

Returns the number of bytes per single sample.

Returns: Bytes per sample.

◆ bytesPerSampleStride()

size_t AudioDesc::bytesPerSampleStride ( ) const

inline

Returns the byte stride between consecutive samples of the same channel.

For planar formats this is the single sample size; for interleaved formats it is the sample size multiplied by the number of channels.

Returns: Byte stride per sample.

◆ channelBufferOffset()

size_t AudioDesc::channelBufferOffset	(	unsigned int	chan,
		size_t	bufferSamples
	)		const

inline

Returns the byte offset to a specific channel within a sample buffer.

For planar formats, the offset is channel * bytesPerSample * bufferSamples. For interleaved formats, it is channel * bytesPerSample.

Parameters

chan	The channel index (zero-based).
bufferSamples	Total number of samples per channel in the buffer.

Returns: Byte offset to the start of the requested channel's data.

◆ channels()

unsigned int AudioDesc::channels ( ) const

inline

Returns the number of audio channels.

Returns: The channel count.

◆ dataType()

DataType AudioDesc::dataType ( ) const

inline

Returns the data type of this audio description.

Returns: The DataType enum value.

◆ floatToInteger() [1/2]

template<typename IntegerType , IntegerType Min, IntegerType Max>

static IntegerType AudioDesc::floatToInteger ( float value )

inlinestatic

Converts a normalized float in [-1, 1] to an integer sample value.

Maps the float range [-1.0, 1.0] linearly onto the integer range [Min, Max]. Values outside [-1, 1] are clamped.

Template Parameters

IntegerType	The integer sample type.
Min	The minimum value of the integer range.
Max	The maximum value of the integer range.

Parameters

value The normalized float sample to convert.

Returns: The corresponding integer sample value, clamped to [Min, Max].

◆ floatToInteger() [2/2]

template<typename IntegerType >

static IntegerType AudioDesc::floatToInteger ( float value )

inlinestatic

Converts a normalized float to an integer sample using the type's full range.

Template Parameters

IntegerType The integer sample type whose numeric_limits define the range.

Parameters

value The normalized float sample to convert.

Returns: The corresponding integer sample value, clamped to the type's range.

◆ floatToSamples() [1/2]

void AudioDesc::floatToSamples	(	uint8_t *	out,
		const float *	in,
		size_t	samples
	)		const

inline

Converts normalized floats to samples in this description's format.

Parameters

out	Destination buffer for raw sample bytes.
in	Source buffer of float samples.
samples	Number of samples per channel to convert.

◆ floatToSamples() [2/2]

template<typename IntegerType , bool OutputIsBigEndian>

static void AudioDesc::floatToSamples	(	uint8_t *	outbuf,
		const float *	in,
		size_t	samples
	)

inlinestatic

Converts a buffer of normalized floats to integer samples.

Handles endian conversion if the output byte order differs from the host.

Template Parameters

IntegerType	The integer sample type.
OutputIsBigEndian	True if the output buffer should be big-endian.

Parameters

outbuf	Destination buffer for raw integer sample bytes.
in	Source buffer of float samples.
samples	Number of samples to convert.

◆ formatEquals()

bool AudioDesc::formatEquals ( const AudioDesc & other ) const

inline

Returns true if both audio descriptions have equal format (type, rate, channels).

Parameters

other The AudioDesc to compare against.

Returns: true if the audio format matches, ignoring metadata.

◆ fromJson()

static AudioDesc AudioDesc::fromJson	(	const JsonObject &	json,
		Error *	err = `nullptr`
	)

static

Constructs an AudioDesc from a JSON object.

Parameters

json	The JSON object containing "DataType", "SampleRate", "Channels", and optional "Metadata".
err	Optional error output.

Returns: The deserialized AudioDesc, or an invalid AudioDesc on failure.

◆ integerToFloat() [1/2]

template<typename IntegerType , IntegerType Min, IntegerType Max>

static float AudioDesc::integerToFloat ( IntegerType value )

inlinestatic

Converts an integer sample value to a normalized float in [-1, 1].

Maps the integer range [Min, Max] linearly onto the float range [-1.0, 1.0].

Template Parameters

IntegerType	The integer sample type.
Min	The minimum value of the integer range.
Max	The maximum value of the integer range.

Parameters

value The integer sample to convert.

Returns: The corresponding normalized float value.

◆ integerToFloat() [2/2]

template<typename IntegerType >

static float AudioDesc::integerToFloat ( IntegerType value )

inlinestatic

Converts an integer sample value to a normalized float using the type's full range.

Template Parameters

IntegerType The integer sample type whose numeric_limits define the range.

Parameters

value The integer sample to convert.

Returns: The corresponding normalized float value.

◆ isNative()

bool AudioDesc::isNative ( ) const

inline

Returns true if the data type is the platform's native float format.

Returns: true if the data type equals NativeType.

◆ isValid()

bool AudioDesc::isValid ( ) const

inline

Returns true if this audio description has a valid data type, sample rate, and channel count.

Returns: true if valid.

◆ lookupFormat()

static const Format * AudioDesc::lookupFormat ( int id )

static

Looks up a Format descriptor by its DataType id.

Parameters

id	The DataType enum value to look up.

Returns: A pointer to the matching Format, or the Invalid format descriptor.

◆ operator==()

bool AudioDesc::operator== ( const AudioDesc & other ) const

inline

Returns true if both audio descriptions are fully equal, including metadata.

Parameters

other The AudioDesc to compare against.

Returns: true if equal.

◆ sampleRate()

float AudioDesc::sampleRate ( ) const

inline

Returns the sample rate in Hz.

Returns: The sample rate.

◆ samplesToFloat() [1/2]

void AudioDesc::samplesToFloat	(	float *	out,
		const uint8_t *	in,
		size_t	samples
	)		const

inline

Converts samples from this description's format to normalized floats.

Parameters

out	Destination buffer for float samples.
in	Source buffer of raw sample bytes.
samples	Number of samples per channel to convert.

◆ samplesToFloat() [2/2]

template<typename IntegerType , bool InputIsBigEndian>

static void AudioDesc::samplesToFloat	(	float *	out,
		const uint8_t *	inbuf,
		size_t	samples
	)

inlinestatic

Converts a buffer of integer samples to normalized floats.

Handles endian conversion if the input byte order differs from the host.

Template Parameters

IntegerType	The integer sample type.
InputIsBigEndian	True if the input buffer is big-endian.

Parameters

out	Destination buffer for float samples.
inbuf	Source buffer of raw integer sample bytes.
samples	Number of samples to convert.

◆ setChannels()

void AudioDesc::setChannels ( unsigned int val )

inline

Sets the number of audio channels.

Parameters

val	The new channel count.

◆ setDataType()

void AudioDesc::setDataType ( DataType val )

inline

Sets the data type.

Parameters

val	The new DataType value.

◆ setSampleRate()

void AudioDesc::setSampleRate ( float val )

inline

Sets the sample rate.

Parameters

val	The new sample rate in Hz.

◆ stringToDataType()

static DataType AudioDesc::stringToDataType ( const String & val )

static

Converts a string name to its corresponding DataType enum value.

Parameters

val	The format name string (e.g. "PCMI_S16LE").

Returns: The matching DataType, or Invalid if the string is not recognized.

◆ toJson()

JsonObject AudioDesc::toJson ( ) const

inline

Serializes this audio description to a JSON object.

Returns: A JsonObject containing "DataType", "SampleRate", "Channels", and optional "Metadata".

◆ toString()

String AudioDesc::toString ( ) const

inline

Returns a human-readable string representation of this audio description.

Returns: A String in the format "[FormatName SampleRateHz Channelsc]".

◆ workingDesc()

AudioDesc AudioDesc::workingDesc ( ) const

inline

Returns a new AudioDesc with the same sample rate and channels but using the native float format.

Returns: An AudioDesc suitable for internal processing.

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

include/promeki/proav/audiodesc.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ DataType

Constructor & Destructor Documentation

◆ AudioDesc() [1/2]

◆ AudioDesc() [2/2]

Member Function Documentation

◆ bufferSize()

◆ bytesPerSample()

◆ bytesPerSampleStride()

◆ channelBufferOffset()

◆ channels()

◆ dataType()

◆ floatToInteger() [1/2]

◆ floatToInteger() [2/2]

◆ floatToSamples() [1/2]

◆ floatToSamples() [2/2]

◆ formatEquals()

◆ fromJson()

◆ integerToFloat() [1/2]

◆ integerToFloat() [2/2]

◆ isNative()

◆ isValid()

◆ lookupFormat()

◆ operator==()

◆ sampleRate()

◆ samplesToFloat() [1/2]

◆ samplesToFloat() [2/2]

◆ setChannels()

◆ setDataType()

◆ setSampleRate()

◆ stringToDataType()

◆ toJson()

◆ toString()

◆ workingDesc()