SoundData

class carb.audio.SoundData

Bases: pybind11_object

Sound data object. This provides storage for a single sound asset. The asset’s data, metadata (if any), and various properties about its format are stored and can be retrieved as needed. There are also helper functions to allow new data to be written to the object’s internal data buffers.

Methods

`__init__`(args, *kwargs)
`clear_event_points`(self)	Removes all event points from a SoundData object.
`get_buffer_as_float`(self, length, offset, units)	Retrieve a buffer of audio from the SoundData object in 32 bit float PCM.
`get_buffer_as_int16`(self, length, offset, units)	Retrieve a buffer of audio from the SoundData object in signed 16 bit integer PCM.
`get_buffer_as_int32`(self, length, offset, units)	Retrieve a buffer of audio from the SoundData object in signed 32 bit integer PCM.
`get_buffer_as_uint8`(self, length, offset, units)	Retrieve a buffer of audio from the SoundData object in unsigned 8 bit integer PCM.
`get_event_point_by_id`(self, id)	Retrieves a single event point object by its identifier.
`get_event_point_by_index`(self, index)	Retrieves a single event point object by its index.
`get_event_point_by_play_index`(self, index)	Retrieves a single event point object by its playlist index.
`get_event_point_max_play_index`(self)	Retrieve the maximum play index value for the sound.
`get_event_points`(self)	Retrieves embedded event point information from a sound data object.
`get_format`(self)	Query the SoundData object's format.
`get_length`(self, units)	Query the SoundData object's buffer length.
`get_max_instances`(self)	Query the SoundData object's max instance count.
`get_memory_used`(self)	Query the amount of memory that's in use by a SoundData object.
`get_metadata`(self, tag_name)	Retrieve a metadata value from a SoundData object by its tag name.
`get_metadata_by_index`(self, index)	Retrieve a metadata tag from a SoundData object by its index.
`get_name`(self)	Retrieve the name of a SoundData object.
`get_peak_level`(self)	Retrieves or calculates the peak volume levels for a sound if possible.
`get_valid_length`(self, units)	Query the SoundData object's buffer length.
`is_decoded`(self)	Query if the SoundData object is decoded or streaming.
`save_to_file`(self, file_name, format, flags)	Save a SoundData object to disk as a playable audio file.
`set_event_points`(self, eventPoints)	Modifies, adds or removes event points in a SoundData object.
`set_max_instances`(self, limit)	Set the SoundData object's max instance count.
`set_metadata`(self, tag_name, tag_value)	Add a metadata tag to a SoundData object.
`set_valid_length`(self, length, units)	Set the length of the valid portion of the SoundData object's buffer.
`write_buffer_with_float`(self, data, offset, ...)	Write a buffer of audio to the SoundData object with 32 bit float PCM data.
`write_buffer_with_int16`(self, data, offset, ...)	Write a buffer of audio to the SoundData object with signed 16 bit PCM data.
`write_buffer_with_int32`(self, data, offset, ...)	Write a buffer of audio to the SoundData object with signed 32 bit PCM data.
`write_buffer_with_uint8`(self, data, offset, ...)	Write a buffer of audio to the SoundData object with unsigned 8 bit PCM data.

__init__(*args, **kwargs)

clear_event_points(self: carb.audio._audio.SoundData) → None

Removes all event points from a SoundData object.

Returns:
No return value.

get_buffer_as_float(self: carb.audio._audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → List[float]

Retrieve a buffer of audio from the SoundData object in 32 bit float PCM.

Parameters

length – The length of the buffer you want to retrieve. This will be clamped if the SoundData object does not have this much data available.
offset – The offset in the SoundData object to start reading from.
units – How length and offset will be interpreted. This defaults to `UnitType.FRAMES`.

Returns

A buffer of audio data from the SoundData object in signed 32 bit integer format. The format is a list containing integer data with values in the range [-1.0, 1.0].

get_buffer_as_int16(self: carb.audio._audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in signed 16 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in signed 16 bit integer format. The format is a list containing integer data with values in the range [-32768, 32767].

get_buffer_as_int32(self: carb.audio._audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in signed 32 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in signed 32 bit integer format. The format is a list containing integer data with values in the range [-2147483648, 2147483647].

get_buffer_as_uint8(self: carb.audio._audio.SoundData, length: int = 0, offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → List[int]

Retrieve a buffer of audio from the SoundData object in unsigned 8 bit integer PCM.

Parameters

retrieve. (length The length of the buffer you want to) – This will be clamped if the SoundData object does not have this much data available.
from. (offset The offset in the SoundData object to start reading) –
to (units How length and offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

A buffer of audio data from the SoundData object in unsigned 8 bit integer format. The format is a list containing integer data with values in the range [0, 255].

get_event_point_by_id(self: carb.audio._audio.SoundData, id: int) → carb.audio._audio.EventPoint

Retrieves a single event point object by its identifier.

Args:
id The ID of the event point to retrieve.

Returns:
The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_by_index(self: carb.audio._audio.SoundData, index: int) → carb.audio._audio.EventPoint

Retrieves a single event point object by its index.

Event point indices are contiguous, so this can be used to enumerate event points alternatively.

Args:
index The index of the event point to retrieve.

Returns:
The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_by_play_index(self: carb.audio._audio.SoundData, index: int) → carb.audio._audio.EventPoint

Retrieves a single event point object by its playlist index.

Event point playlist indices are contiguous, so this can be used to enumerate the playlist.

Args:
index The playlist index of the event point to retrieve.

Returns:
The event point is retrieved if it exists.

None is returned if there was no event point found.

get_event_point_max_play_index(self: carb.audio._audio.SoundData) → int

Retrieve the maximum play index value for the sound.

Returns:
This returns the max play index for this SoundData object. This will be 0 if no event points have a play index. This is also the number of event points with playlist indexes, since the playlist index range is contiguous.

get_event_points(self: carb.audio._audio.SoundData) → List[carb.audio._audio.EventPoint]

Retrieves embedded event point information from a sound data object.

This retrieves event point information that was embedded in the sound file that was used to create a sound data object. The event points are optional in the data file and may not be present. If they are parsed from the file, they will also be saved out to any destination file that the same sound data object is written to, provided the destination format supports embedded event point information.

Returns:
The list of event points that are embedded in this SoundData object.

get_format(self: carb.audio._audio.SoundData) → carb.audio._audio.SoundFormat

Query the SoundData object’s format.

Returns:
For a sound that was decoded on load, this represents the format of the audio data in the SoundData object’s buffer.

For a streaming sound, this returns the format of the underlying sound asset that is being streamed.

get_length(self: carb.audio._audio.SoundData, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → int

Query the SoundData object’s buffer length.

Args:
units The unit type that will be returned. This defaults to UnitType.FRAMES.

Returns:
The length of the SoundData object’s buffer.

get_max_instances(self: carb.audio._audio.SoundData) → int

Query the SoundData object’s max instance count.

This retrieves the current maximum instance count for a sound. This limit is used to prevent too many instances of a sound from being played simultaneously. With the limit set to unlimited, playing too many instances can result in serious performance penalties and serious clipping artifacts caused by too much constructive interference.

Returns:
The SoundData object’s max instance count.

get_memory_used(self: carb.audio._audio.SoundData) → int

Query the amount of memory that’s in use by a SoundData object.

This retrieves the amount of memory used by a single sound data object. This will include all memory required to store the audio data itself, to store the object and all its parameters, and the original filename (if any). This information is useful for profiling purposes to investigate how much memory the audio system is using for a particular scene.

Returns:
The amount of memory in use by this sound, in bytes.

get_metadata(self: carb.audio._audio.SoundData, tag_name: str) → str

Retrieve a metadata value from a SoundData object by its tag name.

Args:
tag_name The metadata tag’s name.

Returns:
This returns the metadata tag value for tag_name.

This returns None if there is no tag under tag_name.

get_metadata_by_index(self: carb.audio._audio.SoundData, index: int) → Tuple[str, str]

Retrieve a metadata tag from a SoundData object by its index.

Args:
index The index of the metadata tag.

Returns:
This returns a tuple: (metadata tag name, metadata tag value).

This returns (None, None) if there was no tag at the specified index.

get_name(self: carb.audio._audio.SoundData) → str

Retrieve the name of a SoundData object.

Returns:
The name that was given to the object.

This will return None if the object has no name.

get_peak_level(self: carb.audio._audio.SoundData) → carb.audio._audio.PeakVolumes

Retrieves or calculates the peak volume levels for a sound if possible.

This retrieves the peak volume level information for a sound. This information is either loaded from the sound’s original source file or is calculated if the sound is decoded into memory at load time. This information will not be calculated if the sound is streamed from disk or memory.

Returns:
The peak level information from the SoundData object.

This will throw if peak level information is not embedded in the sound.

get_valid_length(self: carb.audio._audio.SoundData, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → int

Query the SoundData object’s buffer length.

Args:

units The unit type that will be returned. This defaults to
UnitType.FRAMES.

Returns:
The length of the SoundData object’s buffer.

is_decoded(self: carb.audio._audio.SoundData) → bool

Query if the SoundData object is decoded or streaming.

Returns:
True if the object is decoded. False if the object is streaming.

save_to_file(self: carb.audio._audio.SoundData, file_name: str, format: carb.audio._audio.SampleFormat = <SampleFormat.DEFAULT: 11>, flags: int = 0) → bool

Save a SoundData object to disk as a playable audio file.

Args:
file_name: The path to save this file as. format: The audio format to use when saving this file. PCM formats will save as a WAVE file (.wav). flags: Flags to alter the behavior of this function. This is a bitmask of `SAVE_FLAG_*` flags.

Returns:
True if the SoundData object was saved to disk successfully. False if saving to disk failed.

set_event_points(self: carb.audio._audio.SoundData, eventPoints: List[carb.audio._audio.EventPoint]) → bool

Modifies, adds or removes event points in a SoundData object.

This modifies, adds or removed one or more event points in a sound data object. An event point will be modified if one with the same ID already exists. A new event point will be added if it has an ID that is not already present in the sound data object and its frame offset is valid. An event point will be removed if it has an ID that is present in the sound data object but the frame offset for it is set to EVENT_POINT_INVALID_FRAME. Any other event points with invalid frame offsets (ie: out of the bounds of the stream) will be skipped and cause the function to fail.

If an event point is modified or removed such that the playlist indexes of the event points are no longer contiguous, this function will adjust the play indexes of all event points to prevent any gaps.

Args:

eventPoints: The event point(s) to be modified or added. The
operation that is performed for each event point in the table depends on whether an event point with the same ID already exists in the sound data object. The event points in this table do not need to be sorted in any order.

Returns:
True if all of the event points in the table are updated successfully. False if not all event points could be updated. This includes a failure to allocate memory or an event point with an invalid frame offset. Note that this failing doesn’t mean that all the event points failed. This just means that at least failed to be set properly. The new set of event points may be retrieved and compared to the list set here to determine which one failed to be updated.

set_max_instances(self: carb.audio._audio.SoundData, limit: int) → None

Set the SoundData object’s max instance count.

This sets the new maximum playing instance count for a sound. This limit will prevent the sound from being played until another instance of it finishes playing or simply cause the play request to be ignored completely. This should be used to limit the use of frequently played sounds so that they do not cause too much of a processing burden in a scene or cause too much constructive interference that could lead to clipping artifacts. This is especially useful for short sounds that are played often (ie: gun shots, foot steps, etc). At some [small] number of instances, most users will not be able to tell if a new copy of the sound played or not.

Args:
limit The max instance count to set.

set_metadata(self: carb.audio._audio.SoundData, tag_name: str, tag_value: str) → bool

Add a metadata tag to a SoundData object.

Metadata tag names are not case sensitive.

It is not guaranteed that a given file type will be able to store arbitrary key-value pairs. RIFF files (.wav), for example, store metadata tags under 4 character codes, so only metadata tags that are known to this plugin, such as META_DATA_TAG_ARTIST or tags that are 4 characters in length can be stored. Note this means that storing 4 character tags beginning with ‘I’ runs the risk of colliding with the known tag names (e.g. ‘IART’ will collide with META_DATA_TAG_ARTIST when writing a RIFF file).

tag_name must not contain the character ‘=’ when the output format encodes its metadata in the Vorbis Comment format (SampleFormat.VORBIS and SampleFormat.FLAC do this). ‘=’ will be replaced with ‘_’ when encoding these formats to avoid the metadata being encoded incorrectly. Additionally, the Vorbis Comment standard states that tag names must only contain characters from 0x20 to 0x7D (excluding ‘=’) when encoding these formats.

Args:
tag_name: The metadata tag’s name. tag_value: The metadata tag’s value.

Returns:
No return value.

set_valid_length(self: carb.audio._audio.SoundData, length: int, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → None

Set the length of the valid portion of the SoundData object’s buffer.

Args:
length The new valid length to be set. units How length will be interpreted. This defaults to UnitType.FRAMES.

Returns:
The length of the SoundData object’s buffer.

write_buffer_with_float(self: carb.audio._audio.SoundData, data: List[float], offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with 32 bit float PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as float.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_int16(self: carb.audio._audio.SoundData, data: List[int], offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with signed 16 bit PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as int16_t.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_int32(self: carb.audio._audio.SoundData, data: List[int], offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with signed 32 bit PCM data.

Parameters

object. (data The buffer of data to write to the SoundData) – This must be a list of integer values representable as int32_t.
from. (offset The offset in the SoundData object to start reading) –
to (units How offset will be interpreted. This defaults) – UnitType.FRAMES.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.

write_buffer_with_uint8(self: carb.audio._audio.SoundData, data: List[int], offset: int = 0, units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>) → None

Write a buffer of audio to the SoundData object with unsigned 8 bit PCM data.

Parameters

data – The buffer of data to write to the SoundData object. This must be a list of integer values representable as uint8_t.
offset – The offset in the SoundData object to start reading from.
units – How offset will be interpreted. This defaults to `UnitType.FRAMES`.

Returns

No return value.

This will throw an exception if this is not a writable sound object. Only sounds that were created empty or from raw PCM data are writable.