IAudioData

class carb.audio.IAudioData

Bases: pybind11_object

Sound Data management interface. This allows sounds to be loaded from disk or a blob in memory and to create sound data objects out of those resources. Each operation here will return a new sound data object that can perform its own operations on the loaded data. The sound data objects can also be passed to `Context.play_sound()` to play. Note that this interface is completely different from its C++ counterpart. This has been done to simplify the interface and interactions with it. Most of the operations found in the C++ interface are actually part of the sound data object in the Python API.

Methods

__init__(*args, **kwargs)
create_empty_sound(self, format, channels, ...)	Create a SoundData object with an empty buffer that can be written to.
create_sound_from_blob(self, blob, ...)	Create a SoundData object from a data blob in memory
create_sound_from_file(self, fileName, ...)	Create a SoundData object from a file on disk.
create_sound_from_float_pcm(self, pcm, ...)	Create a SoundData object from raw 32 bit float PCM data.
create_sound_from_int16_pcm(self, pcm, ...)	Create a SoundData object from raw 16 bit signed integer PCM data.
create_sound_from_int32_pcm(self, pcm, ...)	Create a SoundData object from raw 32 bit signed integer PCM data.
create_sound_from_uint8_pcm(self, pcm, ...)	Create a SoundData object from raw 8 bit unsigned integer PCM data.

__init__(*args, **kwargs)

create_empty_sound(

self: carb.audio._audio.IAudioData,

format: carb.audio._audio.SampleFormat,

channels: int,

frame_rate: int,

buffer_length: int,

units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>,

name: str = None,

channel_mask: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object with an empty buffer that can be written to.

After creating a SoundData object with this, you will need to call one of the write_buffer_*() functions to load your data into the object, then you will need to call set_valid_length() to indicate how much of the sound now contains valid data.

Parameters:

• decodedFormat – The format for the SoundData object’s buffer. Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This defaults to SampleFormat.DEFAULT, which will use float for the buffer.

• channels – The number of channels of data in each frame of the audio data.

• frame_rate – 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).

• buffer_length – How long you want the buffer to be.

• units – How buffer_length will be interpreted. This defaults to UnitType.FRAMES.

• name – An optional name that can be given to the SoundData object to make it easier to track. This can be None if it is not needed. This defaults to `None`.

• channel_mask – 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. The channel mapping will be set to the defaults if set to `SPEAKER_MODE_DEFAULT`, which is the default value for this parameter.

Returns:

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_blob(

self: carb.audio._audio.IAudioData,

blob: bytes,

decodedFormat: carb.audio._audio.SampleFormat = <SampleFormat.DEFAULT: 11>,

flags: int = 0,

streaming: bool = False,

autoStream: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from a data blob in memory

Args:

blob A bytes object which contains the raw data for an audio

file which has some sort of header. Raw PCM data will not work with this function. Note that due to the way python works, these bytes will be copied into the SoundData object’s internal buffer if the sound is streaming.

decodedFormat The format you want the audio to be decoded into.

Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This is only important if you aren’t creating a decoded sound. This defaults to SampleFormat.DEFAULT, which will decode the sound to float for now.

flags Optional flags to change the behavior. This can be any

of: DATA_FLAG_SKIP_METADATA, DATA_FLAG_SKIP_EVENT_POINTS or DATA_FLAG_CALC_PEAKS.

streaming Set to True to create a streaming sound. Streaming

sounds aren’t loaded into memory; the audio data remains in its encoded form in memory and are decoded in chunks as needed. This is mainly useful for compressed formats which will expand when decoded. This defaults to False.

autoStream The threshold in bytes at which the new sound data

object will decide to stream instead of decode into memory. If the decoded size of the sound will be larger than this value, it will be streamed from its original source instead of decoded. Set this to 0 to disable auto-streaming. This defaults to 0.

Returns:

The new sound data if successfully created and loaded.

An exception is thrown if the sound could not be loaded. This could happen if the blob is an unsupported audio format, the blob is corrupt or some other error during decoding.

create_sound_from_file(

self: carb.audio._audio.IAudioData,

fileName: str,

decodedFormat: carb.audio._audio.SampleFormat = <SampleFormat.DEFAULT: 11>,

flags: int = 0,

streaming: bool = False,

autoStream: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from a file on disk.

Args:

filename The name of the file on disk to create the new sound

data object from.

decodedFormat The format you want the audio to be decoded into.

Although you can retrieve the sound’s data through python in any format, the data will be internally stored as this format. This is only important if you aren’t creating a decoded sound. This defaults to SampleFormat.DEFAULT, which will decode the sound to float for now.

flags Optional flags to change the behavior. This can be any

of: DATA_FLAG_SKIP_METADATA, DATA_FLAG_SKIP_EVENT_POINTS or DATA_FLAG_CALC_PEAKS.

streaming Set to True to create a streaming sound. Streaming

sounds aren’t loaded into memory; they remain on disk and are decoded in chunks as needed. This defaults to False.

autoStream The threshold in bytes at which the new sound data

object will decide to stream instead of decode into memory. If the decoded size of the sound will be larger than this value, it will be streamed from its original source instead of decoded. Set this to 0 to disable auto-streaming. This defaults to 0.

Returns:

The new sound data if successfully created and loaded.

An exception is thrown if the sound could not be loaded. This could happen if the file does not exist, the file is not a supported type, the file is corrupt or some other error occurred during decode.

create_sound_from_float_pcm(

self: carb.audio._audio.IAudioData,

pcm: List[float],

channels: int,

frame_rate: int,

channel_mask: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from raw 32 bit float PCM data.

Args:

pcm The audio data to load into the SoundData object.

This will be copied to an internal buffer in the object.

channels The number of channels of data in each frame of the audio

data.

frame_rate 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).

channel_mask 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. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns:

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_int16_pcm(

self: carb.audio._audio.IAudioData,

pcm: List[int],

channels: int,

frame_rate: int,

channel_mask: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from raw 16 bit signed integer PCM data.

Args:

pcm The audio data to load into the SoundData object.

This will be copied to an internal buffer in the object.

channels The number of channels of data in each frame of the audio

data.

frame_rate 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).

channel_mask 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. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns:

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_int32_pcm(

self: carb.audio._audio.IAudioData,

pcm: List[int],

channels: int,

frame_rate: int,

channel_mask: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from raw 32 bit signed integer PCM data.

Args:

pcm The audio data to load into the SoundData object.

This will be copied to an internal buffer in the object.

channels The number of channels of data in each frame of the audio

data.

frame_rate 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).

channel_mask 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. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns:

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.

create_sound_from_uint8_pcm(

self: carb.audio._audio.IAudioData,

pcm: List[int],

channels: int,

frame_rate: int,

channel_mask: int = 0,

) → carb.audio._audio.SoundData

Create a SoundData object from raw 8 bit unsigned integer PCM data.

Args:

pcm The audio data to load into the SoundData object.

This will be copied to an internal buffer in the object.

channels The number of channels of data in each frame of the audio

data.

frame_rate 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).

channel_mask 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. The channel mapping will be set to the defaults if set to SPEAKER_MODE_DEFAULT, which is the default value for this parameter.

Returns:

The new sound data if successfully created and loaded.

An exception may be thrown if an out-of-memory situation occurs or some other error occurs while creating the object.