Context#

class carb.audio.Context#

Bases: pybind11_object

The Context object for the audio system. Each individual Context represents an instance of the IAudioPlayback interface, as well as an individual connection to the system audio mixer/device. Only a small number of these can be opened for a given process.

Methods

`__init__`(args, *kwargs)
`get_caps`(self)	Retrieves the current capabilities and settings for a context object.
`get_parameters`(self, paramsToGet)	Retrieves one or more parameters for a context.
`play_sound`(self, sound, flags, valid_params, ...)	Schedules a sound to be played on a voice.
`set_bus_count`(self, count)	Change the maximum number of voices that have their output mixed to the audio device.
`set_output`(self[, desc])	Opens a requested audio output device and begins output. This sets the index of the
`set_parameters`(self, paramsToSet, params)	Sets one or more parameters on a context.
`update`(self)	Performs required frequent updates for the audio context. This performs common update

__init__(*args, **kwargs)#

get_caps( self: carb.audio._audio.Context, ) → carb.audio._audio.ContextCaps#

Retrieves the current capabilities and settings for a context object.

This retrieves the current capabilities and settings for a context object. Some of these settings may change depending on whether the context has opened an output device or not.

Parameters:: arguments. (No)
Returns:: the context’s current capabilities and settings. This includes the speaker mode, speaker positions, maximum bus count, and information about the output device that is opened (if any).

get_parameters( self: carb.audio._audio.Context, paramsToGet: int, ) → carb.audio._audio.ContextParams#

Retrieves one or more parameters for a context.

This retrieves the current values of one or more of a context’s parameters. Only the parameter values listed in paramsToGet flags will be guaranteed to be valid upon return.

Parameters:: ParamsToGet – Flags indicating which parameter values need to be retrieved. This should be a combination of the CONTEXT_PARAM_* bitflags.
Returns:: The requested parameters in a ContextParams struct. Everything else is default-initialized.

play_sound( self: carb.audio._audio.Context, sound: carb::audio::PythonSoundData, flags: int = 0, valid_params: int = 0, params: carb.audio._audio.VoiceParams = None, loop_point: carb.audio._audio.EventPoint = None, play_start: int = 0, play_end: int = 0, play_units: carb.audio._audio.UnitType = <UnitType.FRAMES: 1>, ) → carb::audio::PythonVoice#

Schedules a sound to be played on a voice.

This schedules a sound object to be played on a voice. The sounds current settings (ie: volume, pitch, playback frame rate, pan, etc) will be assigned to the voice as ‘defaults’ before playing. Further changes can be made to the voice’s state at a later time without affecting the sound’s default settings.

Once the sound finishes playing, it will be implicitly unassigned from the voice. If the sound or voice have a callback set, a notification will be received for the sound having ended.

If the playback of this sound needs to be stopped, it must be explicitly stopped from the returned voice object using stopVoice(). This can be called on a single voice or a voice group.

Parameters:

sound – The sound to schedule.
flags – Flags that alter playback behavior. Must be a combination of PLAY_FLAG_* constants.
valid_params – Which parameters in the params argument to use.
params – The starting parameters for the voice. This conditionally used based on valid_params.
loop_point – A descriptor for how to repeatedly play the sound. This can be None to only play once.
play_start – The start offset to begin playing the sound at. This is measured in play_units.
play_end – The stop offset to finish playing the sound at. This is measured in play_units.
play_units –
The units in which play_start and play_stop are measured.

Returns:
A new voice handle representing the playing sound. Note that if no buses are currently available to play on or the voice’s initial parameters indicated that it is not currently audible, the voice will be virtual and will not be played. The voice handle will still be valid in this case and can be operated on, but no sound will be heard from it until it is determined that it should be converted to a real voice. This can only occur when the update() function is called. This voice handle does not need to be closed or destroyed. If the voice finishes its play task, any future calls attempting to modify the voice will simply fail.

None if the requested sound is already at or above its instance limit and the PLAY_FLAG_MAX_INSTANCES_SIMULATE flag is not used.

None if the play task was invalid or could not be started properly. This can most often occur in the case of streaming sounds if the sound’s original data could not be opened or decoded properly.

set_bus_count( self: carb.audio._audio.Context, count: int, ) → bool#

Change the maximum number of voices that have their output mixed to the audio device.

Notes

This call needs to stop the audio engine, so this will block for 10-20ms if any voices are still playing actively.
This should be called infrequently and only in cases where destroying the context is not an option.
To use this function without introducing audio artifacts, this function can only be called after all voices playing on buses have become silent or have stopped. The easiest way to ensure this is to set the master volume on the context to 0.0. At least 10ms must elapse between the volume reduction and this call to ensure that the changes have taken effect. If voices are being stopped, 20ms must occur between the last stopped voice and this call.

Parameters:: count – The new number of buses to select. This will be clamped to 64 if. This cannot be set to 0.
Returns:: `True` if the max bus count was successfully changed. `False` if any voices are still playing on buses. `False` if the operation failed for any other reason (e.g. out of memory).

set_output( self: carb.audio._audio.Context, desc: carb.audio._audio.OutputDesc = None, ) → carb.audio._audio.AudioResult#

Opens a requested audio output device and begins output. This sets the index of the

audio output device that will be opened and attempts to open it. An index of 0 will open the system’s default audio output device. Note that the device index value is volatile and could change at any time due to user activity. It is suggested that the device index be chosen as closely as possible to when the device will be opened.

This allows an existing audio context object to switch to using a different audio device for its output after creation without having to destroy and recreate the current state of the context. Once a new device is selected, it will be available to start processing and outputting audio. Note that switching audio devices dynamically may cause an audible pop to occur on both the old device and new device depending on the current state of the context. To avoid this, all active voices could be muted or paused briefly during the device switch, then resumed or un-muted after it completes.

Note:

If selecting the new device fails, the context will be left without a device to play its output on. Upon failure, an attempt to open the system’s default device may be made by the caller to restore the playback. Note that even choosing the system default device may fail for various reasons (ie: the speaker mode of the new device cannot be mapped properly, the device is no longer available in the system, etc). In this case, all audio processing will still continue but the final audio data will just be dropped until a valid output target is connected.

Args:

context: The context object that will have its device index set. This is: returned from a previous call to `create_context()`. This must not be `None`.
desc: The descriptor of the output to open. This may be `None` or omitted: to use the default system output device.

Returns:

`AudioResult.OK` if the requested device is successfully opened. `AudioResult.OUT_OF_RANGE` if the device index is invalid. An `AudioResult.*` error code if the operation fails for any other reason. See the notes above for more information on failures.

set_parameters( self: carb.audio._audio.Context, paramsToSet: int, params: carb.audio._audio.ContextParams, ) → None#

Sets one or more parameters on a context.

This sets one or more context parameters in a single call. Only parameters that have their corresponding flag set in paramsToSet will be modified. If a change is to be relative to the context’s current parameter value, the current value should be retrieved first, modified, then set.

Parameters:

paramsToSet – The set of flags to indicate which parameters in the parameter block params are valid and should be set on the context. This may be zero or more of the CONTEXT_PARAM_* bitflags. If this is 0, the call will be treated as a no-op.
params – The parameter(s) to be set on the context. The flags indicating which parameters need to be set are given in paramsToSet. Undefined behavior may occur if a flag is set but its corresponding value(s) have not been properly initialized. This may not be None.

Returns:

No return value.

update( self: carb.audio._audio.Context, ) → carb.audio._audio.AudioResult#

Performs required frequent updates for the audio context. This performs common update

tasks. Updates need to be performed frequently. This will perform any pending callbacks and will ensure that all pending parameter changes have been updated in the engine context. This should still be called periodically even if no object parameter changes occur.

All non-realtime voice callbacks will be performed during this call. All device change callbacks on the context will also be performed here. Failing to call this periodically may cause events to be lost.

Returns:: AudioResult.OK if the update is performed successfully. AudioResult.DEVICE_DISCONNECTED or AudioResult.DEVICE_LOST if the currently selected device has been removed from the system. AudioResult.DEVICE_NOT_OPEN if no device has been opened. AudioResult.INVALID_PARAMETER if an invalid context is passed in. An AudioResult.* error code if the update fails for any other reason.