carb::audio::SampleFormat

Defined in carb/audio/AudioTypes.h

enum class carb::audio::SampleFormat : uint32_t

the data type for a single sample of raw audio data.

This describes how each sample in the data buffer should be interpreted. In general, audio data can only be uncompressed Pulse Code Modulation (PCM) data, or encoded in some kind of compressed format.

Values:

enumerator ePcm8

8 bits per sample unsigned integer PCM data.

Sample values will range from 0 to 255 with a value of 128 being ‘silence’.

enumerator ePcm16

16 bits per sample signed integer PCM data.

Sample values will range from -32768 to 32767 with a value of 0 being ‘silence’.

enumerator ePcm24

24 bits per sample signed integer PCM data.

Sample values will range from -16777216 to 16777215 with a value of 0 being ‘silence’.

enumerator ePcm32

32 bits per sample signed integer PCM data.

Sample values will range from -2147483648 to 2147483647 with a value of 0 being ‘silence’.

enumerator ePcmFloat

32 bits per sample floating point PCM data.

Sample values will range from -1.0 to 1.0 with a value of 0.0 being ‘silence’. Note that floating point samples can extend out of their range (-1.0 to 1.0) without a problem during mixing. However, once the data reaches the device, any samples beyond the range from -1.0 to 1.0 will clip and cause distortion artifacts.

enumerator ePcmCount

the total number of PCM formats.

This is not a valid format and is only used internally to determine how many PCM formats are available.

enumerator eVorbis

The Vorbis codec.

Vorbis is a lossy compressed codec that is capable of producing high quality audio that is difficult to differentiate from lossless codecs. Vorbis is suitable for music and other applications that require minimal quality loss. Vorbis is stored in Ogg file containers (.ogg or .oga). Vorbis has a variable block size, with a maximum of 8192 frames per block, which makes it non-optimal for low latency audio transfer (e.g. voice chat); additionally, the Ogg container combines Vorbis blocks into chunks that can be seconds long. libvorbis will accept frame rates of 1Hz - 200KHz (Note that IAudioPlayback does not supports framerates below kMinFrameRate). Vorbis is able to handle up to 255 channels, but sounds with more than 8 channels have no official ordering. (Note that does not support more than kMaxChannels)

Vorbis has a defined channel mapping for audio with 1-8 channels. Channel counts 3 and 5 have an incompatible speaker layout with the default layouts in this plugin. A 3 channel layout uses kSpeakerModeThreePointZero, A 5 channel layout uses kSpeakerModeFivePointZero For streams with more than 8 channels, the mapping is undefined and must be determined by the application.

These are the results of decoding speed tests run on Vorbis; they are shown as the decoding time relative to decoding a 16 bit uncompressed WAVE file to SampleFormat::ePcm32. Clip 1 and 2 are stereo music. Clip 3 is a mono voice recording. Clip 1 has low inter-channel correlation; Clip 2 has high inter-channel correlation. Note that the bitrates listed here are approximate, since Vorbis is variable bitrate.

  • clip 1, 0.0 quality (64kb/s): 668%

  • clip 1, 0.4 quality (128kb/s): 856%

  • clip 1, 0.9 quality (320kb/s): 1333%

  • clip 2, 0.0 quality (64kb/s): 660%

  • clip 2, 0.4 quality (128kb/s): 806%

  • clip 2, 0.9 quality (320kb/s): 1286%

  • clip 3, 0.0 quality (64kb/s): 682%

  • clip 3, 0.4 quality (128kb/s): 841%

  • clip 3, 0.9 quality (320kb/s): 1074%

These are the file sizes from the previous tests:

  • clip 1, uncompressed: 32.7MiB

  • clip 1, 0.0 quality (64kb/s): 1.5MiB

  • clip 1, 0.4 quality (128kb/s): 3.0MiB

  • clip 1, 0.9 quality (320kb/s): 7.5MiB

  • clip 2, uncompressed: 49.6MiB

  • clip 2, 0.0 quality (64kb/s): 2.0MiB

  • clip 2, 0.4 quality (128kb/s): 4.0MiB

  • clip 2, 0.9 quality (320kb/s): 10.4MiB

  • clip 3, uncompressed: 9.0MiB

  • clip 3, 0.0 quality (64kb/s): 0.9MiB

  • clip 3, 0.4 quality (128kb/s): 1.4MiB

  • clip 3, 0.9 quality (320kb/s): 2.5MiB

enumerator eFlac

The Free Lossless Audio Codec.

This is a codec capable of moderate compression with a perfect reproduction of the original uncompressed signal. This encodes and decodes reasonable fast, but the file size is much larger than the size of a high quality lossy codec. This is suitable in applications where audio data will be repeatedly encoded, such as an audio editor. Unlike a lossy codec, repeatedly encoding the file with FLAC will not degrade the quality. FLAC is very fast to encode and decode compared to other compressed codecs. Note that FLAC only stores integer data, so audio of type SampleFormat::ePcmFloat will lose precision when stored as FLAC. Additionally, the FLAC encoder used only supports up to 24 bit, so SampleFormat::ePcm32 will lose some precision when being stored if there are more than 24 valid bits per sample. FLAC supports frame rates from 1Hz - 655350Hz (Note that IAudioPlayback only support framerates of kMinFrameRate to kMaxFrameRate). FLAC supports up to 8 channels.

These are the results of decoding speed tests run on FLAC; they are shown as the decoding time relative to decoding a 16 bit uncompressed WAVE file to SampleFormat::ePcm32. These are the same clips as used in the decoding speed test for SampleFormat::eVorbis. has high inter-channel correlation.

  • clip 1, compression level 0: 446%

  • clip 1, compression level 5: 512%

  • clip 1, compression level 8: 541%

  • clip 2, compression level 0: 321%

  • clip 2, compression level 5: 354%

  • clip 2, compression level 8: 388%

  • clip 3, compression level 0: 262%

  • clip 3, compression level 5: 303%

  • clip 3, compression level 8: 338%

These are the file sizes from the previous tests:

  • clip 1, uncompressed: 32.7MiB

  • clip 1, compression level 0: 25.7MiB

  • clip 1, compression level 5: 23.7MiB

  • clip 1, compression level 8: 23.4MiB

  • clip 2, uncompressed: 49.6MiB

  • clip 2, compression level 0: 33.1MiB

  • clip 2, compression level 5: 26.8MiB

  • clip 2, compression level 8: 26.3MiB

  • clip 3, uncompressed: 9.0MiB

  • clip 3, compression level 0: 6.2MiB

  • clip 3, compression level 5: 6.1MiB

  • clip 3, compression level 8: 6.0MiB

Note

Before encoding FLAC sounds with unusual framerates, please read the documentation for FlacEncoderSettings::streamableSubset.

enumerator eOpus

The Opus codec.

This is a lossy codec that is designed to be suitable for almost any application. Opus can encode very high quality lossy audio, similarly to SampleFormat::eVorbis. Opus can encode very low bitrate audio at a much higher quality than SampleFormat::eVorbis. Opus also offers much lower bitrates than SampleFormat::eVorbis. Opus is designed for low latency usage, with a minimum latency of 5ms and a block size configurable between 2.5ms and 60ms. Opus also offers forward error correction to handle packet loss during transmission.

Opus is stored in Ogg file containers (.ogg or .oga), but in use cases such as network transmission, Ogg containers are not necessary. Opus only supports sample rates of 48000Hz, 24000Hz, 16000Hz, 12000Hz and 8000Hz. Passing unsupported frame rates below 48KHz to the encoder will result in the input audio being resampled to the next highest supported frame rate. Passing frame rates above 48KHz to the encoder will result in the input audio being resampled down to 48KHz. The ‘Opus Custom’ format, which removes this frame rate restriction, is not supported.

Opus has a defined channel mapping for audio with 1-8 channels. The channel mapping is identical to that of SampleFormat::eVorbis. For streams with more than 8 channels, the mapping is undefined and must be determined by the application. Up to 255 audio channels are supported.

Opus has three modes of operation: a linear predictive coding (LPC) mode, a modified discrete cosine transform (MCDT) mode and a hybrid mode which combines both the LPC and MCDT mode. The LPC mode is optimized to encode voice data at low bitrates and has the ability to use forward error correction and packet loss compensation. The MCDT mode is suitable for general purpose audio and is optimized for minimal latency.

Because Opus uses a fixed number of frames per block, additional padding will be added when encoding with a CodecState, unless the frame size is specified in advance with OpusEncoderSettings::frames.

These are the results of decoding speed tests run on Opus; they are shown as the decoding time relative to decoding a 16 bit uncompressed WAVE file to SampleFormat::ePcm32. Clip 1 and 2 are stereo music. Clip 3 is a mono voice recording. Clip 1 has low inter-channel correlation; Clip 2 has high inter-channel correlation. Note that the bitrates listed here are approximate, since Opus is variable bitrate.

  • clip 1, 64kb/s: 975%

  • clip 1, 128kb/s: 1181%

  • clip 1, 320kb/s: 2293%

  • clip 2, 64kb/s: 780%

  • clip 2, 128kb/s: 1092%

  • clip 2, 320kb/s: 2376%

  • clip 3, 64kb/s: 850%

  • clip 3, 128kb/s: 997%

  • clip 3, 320kb/s: 1820%

These are the file sizes from the previous tests:

  • clip 1, uncompressed: 32.7MiB

  • clip 1, 64kb/s: 1.5MiB

  • clip 1, 128kb/s: 3.0MiB

  • clip 1, 320kb/s: 7.5MiB

  • clip 2, uncompressed: 49.6MiB

  • clip 2, 64kb/s: 2.3MiB

  • clip 2, 128kb/s: 4.6MiB

  • clip 2, 320kb/s: 11.3MiB

  • clip 3, uncompressed: 9.0MiB

  • clip 3, 64kb/s: 1.7MiB

  • clip 3, 128kb/s: 3.3MiB

  • clip 3, 320kb/s: 6.7MiB

enumerator eMp3

MPEG audio layer 3 audio encoding.

This is currently supported for decoding only; to compress audio with a lossy algorithm, SampleFormat::eVorbis or SampleFormat::eOpus should be used.

The MP3 decoder currently only has experimental support for seeking; files encoded by LAME seem to seek with frame-accurate precision, but results may vary on other encoders. It is recommended to load the file with fDataFlagDecode, if you intend to use frame-accurate loops.

MP3 is faster to decode than SampleFormat::eVorbis and SampleFormat::eOpus. This is particularly noticeable because MP3’s decoding speed is not affected as significantly by increasing bitrates as SampleFormat::eVorbis and SampleFormat::eOpus. The quality degradation of MP3 with low bitrates is much more severe than with SampleFormat::eVorbis and SampleFormat::eOpus, so this difference in performance is not as severe as it may appear. The following are the times needed to decode a sample file that is about 10 minutes long:

encoding:

time (seconds):

45kb/s MP3

0.780

64kb/s MP3

0.777

128kb/s MP3

0.904

320kb/s MP3

1.033

45kb/s Vorbis

1.096

64kb/s Vorbis

1.162

128kb/s Vorbis

1.355

320kb/s Vorbis

2.059

45kb/s Opus

1.478

64kb/s Opus

1.647

128kb/s Opus

2.124

320kb/s Opus

2.766

enumerator eRaw

the data is in an unspecified compressed format.

Being able to interpret the data in the sound requires extra information on the caller’s part.

enumerator eDefault

the default or preferred sample format for a device.

This format name is only valid when selecting a device or decoding data.

enumerator eCount

the number of supported sample formats.

This is not a valid format and is only used internally to determine how many formats are available.