IAudioPlayback#

class carb.audio.IAudioPlayback#

Bases: pybind11_object

Audio playback interface. This interface and its objects manages all audio playback operations and objects. The main operations in this interface are device discovery and context object creation. Once a context object has been created, all of the playback operations are managed through it. Note that only a limited number of playback contexts can exist in a process at any given time. It is best practice to always explicitlyset the variable holding the context object to `None` when it is no longer needed. This helps prevent other attempts to create a new context from failing while waiting for the object to be garbage collected.

Methods

`__init__`(args, *kwargs)
`create_context`(self, desc)	Creates a new audio output context object. This creates a new audio output context object.
`get_device_caps`(self[, index])	Retrieves the capabilities and information about a single audio output device. This
`get_device_count`(self)	Retrieves the current audio output device count for the system. The device count is a potentially

__init__(*args, **kwargs)#

create_context( self: carb.audio._audio.IAudioPlayback, desc: carb.audio._audio.PlaybackContextDesc = <carb.audio._audio.PlaybackContextDesc object at 0x7fdb88a8a3b0>, ) → carb.audio._audio.Context#

Creates a new audio output context object. This creates a new audio output context object.

This object is responsible for managing all access to a single instance of the audio context. Note that there will be a separate audio engine thread associated with each instance of this context object.

Upon creation, this object will be in a default state. This means that the selected device will be opened and its processing engine created. It will output at the chosen device’s default frame rate and channel count. If needed, a new device may be selected with `set_output()` on the context object. If a device that defaults to more than `Speaker.COUNT` channels is selected, the output channel mapping will be undefined and spatial audio will not function as expected. This can only be worked around using the C++ interface and its `setSpeakerDirections()` function.

Note:

If selecting a device fails during context creation, the context will still be created successfully and be valid for future operations. The caller will have to select another valid device at a later point before any audio will be output however. A caller can check if a device has been opened successfully by calling `get_context_caps()` and checking the `ContextCaps.selectedDevice.flags` member to see if it has been set to something other than `DEVICE_FLAG_NOT_OPEN`.

Args:

desc: A description of the initial settings and capabilities to use for the new: context object. Omit this parameter to use the system default playback device and its preferred settings.

Returns:

The newly created audio output context object if successful. Throws a `ContextError` exception if the operation failed. This can fail if too many playback contexts already exist in the process.

get_device_caps( self: carb.audio._audio.IAudioPlayback, index: int = 0, ) → carb.audio._audio.DeviceCaps#

Retrieves the capabilities and information about a single audio output device. This

retrieves information about a single audio output device. The information will be returned in the @p info buffer. This may fail if the device corresponding to the requested index has been removed from the system.

Args:

device_index: The index of the device to retrieve info for. This must be: between 0 and the most recent return value from `get_device_count()`. This defaults to 0 if omitted (ie: the index of the system’s default playback device).

Returns:

`AudioResult.OK` if the device info was successfully retrieved. `AudioResult.OUT_OF_RANGE` if the requested device index is out of range of the system’s current device count. Note that the system’s device count can change at any time due to user action (ie: unplugging an audio device or adding a new one). `AudioResult.NOT_SUPPORTED` if a device is found but it requires an unsupported sample format. An `AudioResult.*` error code if the requested device index was out of range or the info buffer was invalid.

get_device_count( self: carb.audio._audio.IAudioPlayback, ) → int#

Retrieves the current audio output device count for the system. The device count is a potentially

volatile value. This can change at any time without notice due to user action. For example, the user could remove an audio device from the system or add a new one at any time. Thus it is a good idea to open the device as quickly as possible after choosing the device index. There is no guarantee that the device list will even remain stable during a single device enumeration loop. The only device index that is guaranteed to be valid is the system default device index of 0.

Returns:: The number of audio output devices that are currently connected to the system. Device 0 in the list will be the system’s default or preferred device.