SampleFormat

class carb.audio.SampleFormat

Bases: pybind11_object

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.

Members:

PCM8 : 8 bits per sample unsigned integer PCM data. Sample values will range from 0 to 255 with a value of 128 being ‘silence’.

PCM16 : 16 bits per sample signed integer PCM data. Sample values will range from -32768 to 32767 with a value of 0 being ‘silence’.

PCM24 : 24 bits per sample signed integer PCM data. Sample values will range from -16777216 to 16777215 with a value of 0 being ‘silence’.

PCM32 : 32 bits per sample signed integer PCM data. Sample values will range from -2147483648 to 2147483647 with a value of 0 being ‘silence’.

PCM_FLOAT : 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.

PCM_COUNT : 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.

VORBISThe 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. The `libvorbis` library will accept frame rates of 1Hz - 200KHz (Note that `IAudioPlayback` does not supports framerates below 1KHz). Vorbis is able to handle up to 255 channels, but sounds with more than 8 channels have no official ordering. (Note that `IAudioPlayback` does not support more than 64 channels).

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 `carb.audio`. A 3 channel layout uses a 3.0 standard layout (front left and right, plus front center). A 5 channel layout uses a 5.0 standard layout (front left and right, side left and right, plus front center). For streams with more than 8 channels, the mapping is undefined and must be determined by the application.

FLACThe 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 reasonably 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 `PCM_FLOAT` will lose precision when stored as FLAC. Additionally, the FLAC encoder used only supports up to 24 bit, so `PCM32` 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 1KHz to 200KHz). FLAC supports up to 8 channels.

OPUSThe 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 `VORBIS`. Opus can encode very low bitrate audio at a much higher quality than `VORBIS`. Opus also offers much lower bitrates than `VORBIS`. 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 `VORBIS`. 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.

MP3MPEG audio layer 3 audio encoding. This is currently supported for decoding only. To compress

audio with a lossy algorithm, `VORBIS` or `OPUS` 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 `DATA_FLAG_DECODE` if you intend to use frame-accurate loops.

MP3 is faster to decode than `VORBIS` and `OPUS`. This is particularly noticeable because MP3’s decoding speed is not affected as significantly by increasing bitrates as with `VORBIS` or `OPUS`. The quality degradation of MP3 with low bitrates is much more severe than with `VORBIS` and `OPUS`, so this difference in performance is not as severe as it may appear.

RAW : 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.

DEFAULT : The default or preferred sample format for a device. This format name is only valid when selecting a device or decoding data.

COUNT : The number of supported sample formats. This is not a valid format and is only used internally to determine how many formats are available.

Methods

__init__(self, value)

Attributes

COUNT
DEFAULT
FLAC
MP3
OPUS
PCM16
PCM24
PCM32
PCM8
PCM_COUNT
PCM_FLOAT
RAW
VORBIS
name
value

__init__(

self: carb.audio._audio.SampleFormat,

value: int,

) → None

property name