ContextParams
- class carb.audio.ContextParams
Bases:
pybind11_objectContext 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
Defines the default playback mode flags for the context.
The global Doppler limit value for this context.
The global Doppler scale value for this context.
Flags to control the behavior of the context.
Attributes of the listener.
full volume).
The global frequency ratio to apply to all active non-spatial voices.
full volume).
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).
full volume).
move from air into water).
meters for distance, seconds for time).
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.