Voice

class carb.audio.Voice

Bases: pybind11_object

Represents a single instance of a playing sound. A single sound object may be playing on multiple voices at the same time, however each voice may only be playing a single sound at any given time.

Methods

__init__(*args, **kwargs)
get_parameters(self[, params_to_get])	Retrieves one or more parameters for a voice.
get_play_cursor(self, type)	Retrieves the current play cursor position of a voice.
is_playing(self)	Checks the playing state of a voice.
set_balance(self, pan, fade)	Non-spatial sound positioning.
set_doppler_scale(self, scale)	Sets the doppler scale value for the voice.
set_frequency_ratio(self, ratio)	Set The frequency ratio for a voice.
set_loop_point(self, point)	Sets a new loop point as current on a voice.
set_matrix(self, matrix)	Set the channel mixing matrix to use for this voice.
set_mute(self, mute)	Sets the mute state for a voice.
set_occlusion(self, direct, reverb)	Sets the occlusion factors for a voice.
set_parameters(self, params_to_set, params)	Sets one or more parameters on a voice.
set_playback_mode(self, playback_mode)	Set flags to indicate how a sound is to be played back.
set_position(self, position)	Set the voice's position.
set_priority(self, priority)	Set the playback priority of this voice.
set_rolloff_curve(self, type, near_distance, ...)	Set custom rolloff curves on the voice.
set_spatial_mix_level(self, level)	Sets the spatial mix level for the voice.
set_velocity(self, velocity)	Set the voice's velocity.
set_volume(self, volume)	The volume level for the voice.
stop(self)	Stops playback on a voice.

__init__(*args, **kwargs)

get_parameters(

self: carb.audio._audio.Voice,

params_to_get: int = 4294967295,

) → carb.audio._audio.VoiceParams

Retrieves one or more parameters for a voice.

This retrieves the current values of one or more of a voice’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.

Returns:

The requested parameters in a VoiceParams struct. Everything else is default-initialized.

get_play_cursor(

self: carb.audio._audio.Voice,

type: carb.audio._audio.UnitType,

) → int

Retrieves the current play cursor position of a voice.

This retrieves the current play position for a voice. This is not necessarily the position in the buffer being played, but rather the position in the sound data object’s stream. For streaming sounds, this will be the offset from the start of the stream. For non-streaming sounds, this will be the offset from the beginning of the sound data object’s buffer.

If the loop point for the voice changes during playback, the results of this call can be unexpected. Once the loop point changes, there is no longer a consistent time base for the voice and the results will reflect the current position based off of the original loop’s time base. As long as the voice’s original loop point remains (ie: setLoopPoint() is never called on the voice), the calculated position should be correct.

It is the caller’s responsibility to ensure that this is not called at the same time as changing the loop point on the voice or stopping the voice.

Parameters:

type – The units to retrieve the current position in.

Returns:

The current position of the voice in the requested units.

0 if the voice has stopped playing.

The last play cursor position if the voice is paused.

is_playing(self: carb.audio._audio.Voice) → bool

Checks the playing state of a voice.

This checks if a voice is currently playing. A voice is considered playing if it has a currently active sound data object assigned to it and it is not paused.

Parameters:

Voice – The voice to check the playing state for.

Returns:

True if the requested voice is playing. False if the requested voice is not playing or is paused. False if the given voice handle is no longer valid.

set_balance(

self: carb.audio._audio.Voice,

pan: float,

fade: float,

) → None

Non-spatial sound positioning. These provide pan and fade values for the voice to give the impression that the sound is located closer to one of the quadrants of the acoustic space versus the others. These values are ignored for spatial sounds.

Parameters:

• pan –

  The non-spatial panning value for a voice. This is 0.0 to have the sound “centered” in all speakers. This is -1.0 to have the sound balanced to the left side. This is 1.0 to have the sound balanced to the right side. The way the sound is balanced depends on the number of channels. For example, a mono sound will be balanced between the left and right sides according to the panning value, but a stereo sound will just have the left or right channels’ volumes turned down according to the panning value. This value is ignored for spatial sounds. The default value is 0.0.

  Note that panning on non-spatial sounds should only be used for mono or stereo sounds. When it is applied to sounds with more channels, the results are often undefined or may sound odd.

• fade –

  The non-spatial fade value for a voice. This is 0.0 to have the sound “centered” in all speakers. This is -1.0 to have the sound balanced to the back side. This is 1.0 to have the sound balanced to the front side. The way the sound is balanced depends on the number of channels. For example, a mono sound will be balanced between the front and back speakers according to the fade value, but a 5.1 sound will just have the front or back channels’ volumes turned down according to the fade value. This value is ignored for spatial sounds. The default value is 0.0.

  Note that using fade on non-spatial sounds should only be used for mono or stereo sounds. When it is applied to sounds with more channels, the results are often undefined or may sound odd.

Returns:

None

set_doppler_scale(

self: carb.audio._audio.Voice,

scale: float,

) → None

Sets the doppler scale value for the voice. This allows the result of internal doppler calculations to be scaled to emulate a time warping effect.

Parameters:

scale – This should be near 0.0 to greatly reduce the effect of the doppler calculations, and up to 5.0 to exaggerate the doppler effect. A value of 1.0 will leave the calculated doppler factors unmodified. The default value is 1.0.

Returns:

None

set_frequency_ratio(

self: carb.audio._audio.Voice,

ratio: float,

) → None

Set The frequency ratio for a voice.

Parameters:

ratio –

This will be 1.0 to play back a sound at its normal rate, a value less than 1.0 to lower the pitch and play it back more slowly, and a value higher than 1.0 to increase the pitch and play it back faster. For example, a pitch scale of 0.5 will play back at half the pitch (ie: lower frequency, takes twice the time to play versus normal), and a pitch scale of 2.0 will play back at double the pitch (ie: higher frequency, takes half the time to play versus normal). The default value is 1.0.

On some platforms, the frequency ratio may be silently clamped to an acceptable range internally. For example, a value of 0.0 is not allowed. This will be clamped to the minimum supported value instead.

Note that the even though the frequency ratio can be set to any value in the range from 1/1024 to 1024, this very large range should only be used in cases where it is well known that the particular sound being operated on will still sound valid after the change. In the real world, some of these extreme frequency ratios may make sense, but in the digital world, extreme frequency ratios can result in audio corruption or even silence. This happens because the new frequency falls outside of the range that is faithfully representable by either the audio device or sound data itself. For example, a 4KHz tone being played at a frequency ratio larger than 6.0 will be above the maximum representable frequency for a 48KHz device or sound file. This case will result in a form of corruption known as aliasing, where the frequency components above the maximum representable frequency will become audio artifacts. Similarly, an 800Hz tone being played at a frequency ratio smaller than 1/40 will be inaudible because it falls below the frequency range of the human ear.

In general, most use cases will find that the frequency ratio range of [0.1, 10] is more than sufficient for their needs. Further, for many cases, the range from [0.2, 4] would suffice. Care should be taken to appropriately cap the used range for this value.

Returns:

None

set_loop_point(

self: carb.audio._audio.Voice,

point: carb.audio._audio.LoopPointDesc,

) → bool

Sets a new loop point as current on a voice.

This sets a new loop point for a playing voice. This allows for behavior such as sound atlases or sound playlists to be played out on a single voice.

When desc is None or the contents of the descriptor do not specify a new loop point, this will immediately break the loop that is currently playing on the voice. This will have the effect of setting the voice’s current loop count to zero. The sound on the voice will continue to play out its current loop iteration, but will not loop again when it reaches its end. This is useful for stopping a voice that is playing an infinite loop or to prematurely stop a voice that was set to loop a specific number of times. This call will effectively be ignored if passed in a voice that is not currently looping.

For streaming voices, updating a loop point will have a delay due to buffering the decoded data. The sound will loop an extra time if the loop point is changed after the buffering has started to consume another loop. The default buffer time for streaming sounds is currently 200 milliseconds, so this is the minimum slack time that needs to be given for a loop change.

Parameters:

• voice – the voice to set the loop point on. This may not be nullptr.

• point – descriptor of the new loop point to set. This may contain a loop or event point from the sound itself or an explicitly specified loop point. This may be nullptr to indicate that the current loop point should be removed and the current loop broken. Similarly, an empty loop point descriptor could be passed in to remove the current loop point.

Returns:

True if the new loop point is successfully set.

False if the voice handle is invalid or the voice has already stopped on its own.

False if the new loop point is invalid, not found in the sound data object, or specifies a starting point or length that is outside the range of the sound data object’s buffer.

set_matrix(

self: carb.audio._audio.Voice,

matrix: List[float],

) → None

Set the channel mixing matrix to use for this voice.

Parameters:

matrix –

The matrix to set. The rows of this matrix represent each output channel from this voice and the columns of this matrix represent the input channels of this voice (e.g. this is a inputChannels x outputChannels matrix). Note that setting the matrix to be smaller than needed will result in undefined behavior. The output channel count will always be the number of audio channels set on the context. Each cell in the matrix should be a value from 0.0-1.0 to specify the volume that this input channel should be mixed into the output channel. Setting negative values will invert the signal. Setting values above 1.0 will amplify the signal past unity gain when being mixed.

This setting is mutually exclusive with balance; setting one will disable the other. This setting is only available for spatial sounds if PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX if set in the playback mode parameter. Multi-channel spatial audio is interpreted as multiple emitters existing at the same point in space, so a purely spatial voice cannot have an output matrix specified.

Setting this to None will reset the matrix to the default for the given channel count. The following table shows the speaker modes that are used for the default output matrices. Voices with a speaker mode that is not in the following table will use the default output matrix for the speaker mode in the following table that has the same number of channels. If there is no default matrix for the channel count of the @ref Voice, the output matrix will have 1.0 in the any cell (i, j) where i == j and 0.0 in all other cells.

Returns:

None

set_mute(self: carb.audio._audio.Voice, mute: bool) → None

Sets the mute state for a voice.

Parameters:

mute – When this is set to true, the voice’s output will be muted. When this is set to false, the voice’s volume will be restored to its previous level. This is useful for temporarily silencing a voice without having to clobber its current volume level or affect its emitter attributes.

Returns:

None

set_occlusion(

self: carb.audio._audio.Voice,

direct: float,

reverb: float,

) → None

Sets the occlusion factors for a voice. These values control automatic low pass filters that get applied to the Sets spatial sounds to simulate object occlusion between the emitter and listener positions.

Parameters:

• direct – The occlusion factor for the direct path of the sound. This is the path directly from the emitter to the listener. This factor describes how occluded the sound’s path actually is. A value of 1.0 means that the sound is fully occluded by an object between the voice and the listener. A value of 0.0 means that the sound is not occluded by any object at all. This defaults to 0.0. This factor multiplies by `EntityCone.low_pass_filter`, if a cone with a non 1.0 lowPassFilter value is specified. Setting this to a value outside of [0.0, 1.0] will result in an undefined low pass filter value being used.

• reverb – The occlusion factor for the reverb path of the sound. This is the path taken for sounds reflecting back to the listener after hitting a wall or other object. A value of 1.0 means that the sound is fully occluded by an object between the listener and the object that the sound reflected off of. A value of 0.0 means that the sound is not occluded by any object at all. This defaults to 1.0.

Returns:

None

set_parameters(

self: carb.audio._audio.Voice,

params_to_set: int,

params: carb.audio._audio.VoiceParams,

) → None

Sets one or more parameters on a voice.

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

Parameters:

• paramsToSet – Flags to indicate which of the parameters need to be updated. This may be one or more of the fVoiceParam* flags. If this is 0, this will simply be a no-op.

• params – The parameter(s) to be set on the voice. The flags indicating which parameters need to be set must be set in paramToSet by the caller. 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.

set_playback_mode(

self: carb.audio._audio.Voice,

playback_mode: int,

) → None

Set flags to indicate how a sound is to be played back. This controls whether the sound is played as a spatial or non-spatial sound and how the emitter’s attributes will be interpreted (ie: either world coordinates or listener relative).

PLAYBACK_MODE_MUTED and PLAYBACK_MODE_PAUSED are ignored here; you’ll need to use voice.set_mute() or voice.pause() to mute or pause the voice.

Parameters:

playback_mode – The playback mode flag set to set.

Returns:

None

set_position(

self: carb.audio._audio.Voice,

position: carb._carb.Float3,

) → None

Set the voice’s position.

Parameters:

position – The current position of the voice in world units. This should only be expressed in meters if the world units scale is set to 1.0 for this context.

Returns:

None

set_priority(

self: carb.audio._audio.Voice,

priority: int,

) → None

Set the playback priority of this voice.

Parameters:

priority – This is an arbitrary value whose scale is defined by the host app. A value of 0 is the default priority. Negative values indicate lower priorities and positive values indicate higher priorities. This priority value helps to determine which voices are the most important to be audible at any given time. When all buses are busy, this value will be used to compare against other playing voices to see if it should steal a bus from another lower priority sound or if it can wait until another bus finishes first. Higher priority sounds will be ensured a bus to play on over lower priority sounds. If multiple sounds have the same priority levels, the louder sound(s) will take priority. When a higher priority sound is queued, it will try to steal a bus from the quietest sound with lower or equal priority.

Returns:

None

set_rolloff_curve(

self: carb.audio._audio.Voice,

type: carb.audio._audio.RolloffType,

near_distance: float,

far_distance: float,

volume: List[carb.audio._audio.Float2] = [],

low_frequency: List[carb.audio._audio.Float2] = [],

low_pass_direct: List[carb.audio._audio.Float2] = [],

low_pass_reverb: List[carb.audio._audio.Float2] = [],

reverb: List[carb.audio._audio.Float2] = [],

) → None

Set custom rolloff curves on the voice.

Parameters:

• type – The default type of rolloff calculation to use for all DSP values that are not overridden by a custom curve.

• near_distance – The near distance range for the sound. This is specified in arbitrary world units. When a custom curve is used, this near distance will map to a distance of 0.0 on the curve. This must be less than the far_distance distance. The near distance is the closest distance that the emitter’s attributes start to rolloff at. At distances closer than this value, the calculated DSP values will always be the same as if they were at the near distance.

• far_distance – The far distance range for the sound. This is specified in arbitrary world units. When a custom curve is used, this far distance will map to a distance of 1.0 on the curve. This must be greater than the @ref nearDistance distance. The far distance is the furthest distance that the emitters attributes will rolloff at. At distances further than this value, the calculated DSP values will always be the same as if they were at the far distance (usually silence). Emitters further than this distance will often become inactive in the scene since they cannot be heard any more.

• volume – The custom curve used to calculate volume attenuation over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating volume attenuation. If this is an empty array, the parameter will be ignored.

• low_frequency – The custom curve used to calculate low frequency effect volume over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low frequency effect volume. If this is an empty array, the parameter will be ignored.

• low_pass_direct – The custom curve used to calculate low pass filter parameter on the direct path over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.

• low_pass_reverb – The custom curve used to calculate low pass filter parameter on the reverb path over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the far_distance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.

• reverb – The custom curve used to calculate reverb mix level over distance. This must be a normalized curve such that a distance of 0.0 maps to the near_distance distance and a distance of 1.0 maps to the @ref farDistance distance. When specified, this overrides the rolloff calculation specified by type when calculating the low pass filter parameter. If this is an empty array, the parameter will be ignored.

Returns:

None

set_spatial_mix_level(

self: carb.audio._audio.Voice,

level: float,

) → None

Sets the spatial mix level for the voice.

Parameters:

level –

The mix between the results of a voice’s spatial sound calculations and its non-spatial calculations. When this is set to 1.0, only the spatial sound calculations will affect the voice’s playback. This is the default when state. When set to 0.0, only the non-spatial sound calculations will affect the voice’s playback. When set to a value between 0.0 and 1.0, the results of the spatial and non-spatial sound calculations will be mixed with the weighting according to this value. This value will be ignored if PLAYBACK_MODE_SPATIAL is not set. The default value is 1.0. Values above 1.0 will be treated as 1.0. Values below 0.0 will be treated as 0.0.

PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX affects the non-spatial mixing behavior of this parameter for multi-channel voices. By default, a multi-channel spatial voice’s non-spatial component will treat each channel as a separate mono voice. With the PLAYBACK_MODE_SPATIAL_MIX_LEVEL_MATRIX flag set, the non-spatial component will be set with the specified output matrix or the default output matrix.

Returns:

None

set_velocity(

self: carb.audio._audio.Voice,

velocity: carb._carb.Float3,

) → None

Set the voice’s velocity.

Parameters:

velocity – The current velocity of the voice in world units per second. This should only be expressed in meters per second if the world units scale is set to 1.0 with for the context. The magnitude of this vector will be taken as the listener’s current speed and the vector’s direction will indicate the listener’s current direction. This vector should not be normalized unless the listener’s speed is actually 1.0 units per second. This may be a zero vector if the listener is not moving.

Returns:

None

set_volume(self: carb.audio._audio.Voice, volume: float) → None

The volume level for the voice.

Parameters:

volume – The volume to set. This should be 0.0 for silence or 1.0 for normal volume. A negative value may be used to invert the signal. A value greater than 1.0 will amplify the signal. The volume level can be interpreted as a linear scale where a value of 0.5 is half volume and 2.0 is double volume. Any volume values in decibels must first be converted to a linear volume scale before setting this value.

Returns:

None

stop(self: carb.audio._audio.Voice) → None

Stops playback on a voice.

This stops a voice from playing its current sound. This will be silently ignored for any voice that is already stopped or for an invalid voice handle. Once stopped, the voice will be returned to a ‘free’ state and its sound data object unassigned from it. The voice will be immediately available to be assigned a new sound object to play from.

This will only schedule the voice to be stopped. Its volume will be implicitly set to silence to avoid a popping artifact on stop. The voice will continue to play for one more engine cycle until the volume level reaches zero, then the voice will be fully stopped and recycled. At most, 1ms of additional audio will be played from the voice’s sound.

Parameters:

Arguments. (No)

Returns:

No return value.