ContextParams

class carb.audio.ContextParams

Bases: pybind11_object

Context parameters block. This can potentially contain all of a context’s parameters and their current values. This is used to both set and retrieve one or more of a context’s parameters in a single call. The set of `CONTEXT_PARAM_*` flags that are passed to the `get_parameter()` or `set_parameter()` functions on the Context object indicates which values in the block are guaranteed to be valid.

Methods

__init__(self)

Attributes

default_playback_mode	Defines the default playback mode flags for the context.
doppler_limit	The global Doppler limit value for this context.
doppler_scale	The global Doppler scale value for this context.
flags	Flags to control the behavior of the context.
listener	Attributes of the listener.
master_volume	full volume).
non_spatial_frequency_ratio	The global frequency ratio to apply to all active non-spatial voices.
non_spatial_volume	full volume).
spatial_frequency_ratio	record a sound at a high frequency to save on storage space and load time, but then always play it back at a reduced pitch).
spatial_volume	full volume).
speed_of_sound	move from air into water).
units_per_meter	meters for distance, seconds for time).
virtualization_threshold	The effective volume level at which a voice will become virtual.

__init__(self: carb.audio._audio.ContextParams) → None

property default_playback_mode

Defines the default playback mode flags for the context. These will provide ‘default’ behavior for new voices. Any new voice that uses the `PLAYBACK_MODE_DEFAULT_*` flags in its voice parameters block will inherit the default playback mode behavior from this value. Note that only specific playback modes are supported in these defaults. This also provides a means to either ‘force on’ or ‘force off’ certain features for each voice. This value is a collection of zero or more of the `PLAYBACK_MODE_DEFAULT_*` flags, and flags that have been returned from either `get_force_off_playback_mode_flags()` or `get_force_on_playback_mode_flags()`. This may not include any of the other `PLAYBACK_MODE_*` flags that are not part of the `PLAYBACK_MODE_DEFAULT_*` set. If the other playback mode flags are used, the results will be undefined. This defaults to 0.

property doppler_limit

The global Doppler limit value for this context. This will cap the calculated Doppler factor at the high end. This is to avoid excessive aliasing effects for very fast moving emitters or listener. When the relative velocity between the listener and an emitter is nearing the speed of sound, the calculated Doppler factor can approach ~11 million. Accurately simulating this would require a very large scale anti-aliasing or filtering pass on all resampling operations on the emitter. That is unfortunately not possible in general. Clamping the Doppler factor to something relatively small like 16 will still result in the effect being heard but will reduce the resampling artifacts related to high frequency ratios. A Doppler factor of 16 represents a relative velocity of ~94% the speed of sound so there shouldn’t be too much of a loss in the frequency change simulation. This defaults to 16. This should not be negative or zero.

property doppler_scale

The global Doppler scale value for this context. This is applied to all calculated Doppler factors to enhance or diminish the effect of the Doppler factor. A value of 1.0 will leave the calculated Doppler levels unmodified. A value lower than 1.0 will have the result of diminishing the Doppler effect. A value higher than 1.0 will have the effect of enhancing the Doppler effect. This is useful for handling global time warping effects. This parameter is a unitless scaling factor. This defaults to 1.0.

property flags

Flags to control the behavior of the context. This is zero or more of the `CONTEXT_PARAM_*` flags. This defaults to 0.

property listener

Attributes of the listener. This is valid when the `CONTEXT_PARAM_LISTENER` flag is used. Only the values that have their corresponding `ENTITY_FLAG_*` flags set will be updated on a set operation. Any values that do not have their corresponding flag set will just be ignored and the previous value will remain current. This can be used to (for example) only update the position for the listener but leave its orientation and velocity unchanged. The flags would also indicate whether the orientation vectors need to be normalized or made perpendicular before continuing. Fixing up these orientation vectors should only be left up to this call if it is well known that the vectors are not already correct.

It is the caller’s responsibility to decide on the listener’s appropriate position and orientation for any given situation. For example, if the listener is represented by a third person character, it would make the most sense to set the position to the character’s head position, but to keep the orientation relative to the camera’s forward and up vectors (possibly have the camera’s forward vector projected onto the character’s forward vector). If the character’s orientation were used instead, the audio may jump from one speaker to another as the character rotates relative to the camera.

property master_volume

full volume). This should not be set beyond 1.0.

Type:

The global master volume for this context. This will only affect the volume level of the final mixed output signal. It will not directly affect the relative volumes of each voice being played. No individual voice will be able to produce a signal louder than this volume level. This is set to 0.0 to silence all output. This defaults to 1.0 (ie

property non_spatial_frequency_ratio

The global frequency ratio to apply to all active non-spatial voices. This can be used to perform a pitch change (and as a result play time change) on all non-spatial voices, or it can be used to simulate a time dilation effect on all non-spatial voices. This will not affect any spatial voices. This defaults to 1.0.

property non_spatial_volume

full volume). This should not be set beyond 1.0. This volume is independent of the `master_volume` value but will effectively be multiplied by it for the final output.

Type:

The relative volume of all non-spatial voices. This will be the initial volume level of any new non-spatial voice. The volume specified in that voice’s parameters will be multiplied by this volume. This does not affect the volume level of spatial voices. This is set to 0.0 to silence all non-spatial voices. This defaults to 1.0 (ie

property spatial_frequency_ratio

record a sound at a high frequency to save on storage space and load time, but then always play it back at a reduced pitch). If this is used for pitch changes, it will interfere with distance delay calculations and possibly lead to other undesirable behavior. This will not affect any non-spatial voices. This defaults to 1.0.

Type:

The global frequency ratio to apply to all active spatial voices. This should only be used to handle time dilation effects on the voices, not to deal with pitch changes (ie

property spatial_volume

full volume). This should not be set beyond 1.0. This volume is independent of the `master_volume` value but will effectively be multiplied by it for the final output.

Type:

The relative volume of all spatial voices. This will be the initial volume level of any new spatial voice. The volume specified in that voice’s parameters will be multiplied by this volume. This does not affect the volume level of non-spatial voices. This is set to 0.0 to silence all spatial voices. This defaults to 1.0 (ie

property speed_of_sound

move from air into water).

Type:

The speed of sound for the context. This is valid when the `CONTEXT_PARAM_SPEED_OF_SOUND` flag is used. This is measured in meters per second. This will affect the calculation of Doppler shift factors and interaural time difference for spatial voices. The default value is `DEFAULT_SPEED_OF_SOUND` m/s. This value can be changed at any time to affect Doppler calculations globally. This should only change when the sound environment itself changes (ie

property units_per_meter

meters for distance, seconds for time). This provides a conversion factor from arbitrary world distance units to SI units. This conversion factor will affect all audio distance and velocity calculations. This defaults to 1.0, indicating that the world units are assumed to be measured in meters. This must not be 0.0 or negative.

Type:

The number of arbitrary world units per meter. This is valid when the `CONTEXT_PARAM_WORLD_UNIT_SCALE` flag is used. World units are arbitrary and often determined by the level/world designers. For example, if the world units are in feet, this value would need to be set to 3.28. All spatial audio calculations are performed in SI units (ie

property virtualization_threshold

The effective volume level at which a voice will become virtual. A virtual voice will not decode any data and will perform only minimal update tasks when needed. This is expressed as a linear volume value from 0.0 (silence) to 1.0 (full volume). The default volume is 0.0.