carb::audio::SoundFormat

struct SoundFormat

provides information about the format of a sound.

This is used both when creating the sound and when retrieving information about its format. When a sound is loaded from a file, its format will be implicitly set on load. The actual format can then be retrieved later with getSoundFormat().

Public Members

size_t channels: the number of channels of data in each frame of the audio data.

size_t bitsPerSample

the number of bits per sample of the audio data.

This is also encoded in the format value, but it is given here as well for ease of use in calculations. This represents the number of bits in the decoded samples of the sound stream. This will be 0 for variable bitrate compressed formats.

size_t frameSize

the size in bytes of each frame of data in the format.

A frame consists of one sample per channel. This represents the size of a single frame of decoded data from the sound stream. This will be 0 for variable bitrate compressed formats.

size_t blockSize

The size in bytes of a single ‘block’ of encoded data.

For PCM data, this is the same as a frame. For formats with a fixed bitrate, this is the size of a single unit of data that can be decoded. For formats with a variable bitrate, this will be 0. Note that certain codecs can be fixed or variable bitrate depending on the encoder settings.

size_t framesPerBlock

The number of frames that will be decoded from a single block of data.

For PCM formats, this will be 1. For formats with a fixed number of frames per block, this will be number of frames of data that will be produced when decoding a single block of data. Note that variable bitrate formats can have a fixed number of frames per block. For formats with a variable number of frames per block, this will be 0. Note that certain codecs can have a fixed or variable number of frames per block depending on the encoder settings.

size_t frameRate: the number of frames per second that must be played back for the audio data to sound ‘normal’ (ie: the way it was recorded or produced).

SpeakerMode channelMask

the channel mask for the audio data.

This specifies which speakers the stream is intended for and will be a combination of one or more of the Speaker names or a SpeakerMode name. This may be calculated from the number of channels present in the original audio data or it may be explicitly specified in the original audio data on load.

size_t validBitsPerSample

the number of bits of valid data that are present in the audio data.

This may be used to specify that (for example) a stream of 24-bit sample data is being processed in 32-bit containers. Each sample will actually consist of 32-bit data in the buffer, using the full 32-bit range, but only the top 24 bits of each sample will be valid useful data. This represents the valid number of bits per sample in the decoded data for the sound stream.

SampleFormat format = SampleFormat::eDefault 

the format of each sample of audio data.

This is given as a symbolic name so that the data can be interpreted properly. The size of each sample in bits is also given in the bitsPerSample value.