VoiceParams#
- class carb.audio.VoiceParams#
Bases:
pybind11_objectVoice parameters block. This can potentially contain all of a voice’s parameters and their current values. This is used to both set and retrieve one or more of a voice’s parameters in a single call. The VOICE_PARAM_* flags that are passed to set_voice_parameters() or get_voice_parameters() determine which values in this block are guaranteed to be valid. The matrix parameter isn’t available from this struct due to limitations in python; use voice.set_matrix() instead.
Methods
__init__(self)Attributes
Non-spatial sound positioning parameters.
The Doppler scale value.
The attributes of the emitter related for this voice.
The frequency ratio for a voice.
The occlusion factors for a voice.
either world coordinates or listener relative).
The playback priority of this voice.
The spatial mix level.
The volume level for the voice.
- __init__(self: carb.audio._audio.VoiceParams) None#
- property balance#
Non-spatial sound positioning parameters. 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.
- property doppler_scale#
The Doppler scale value. This is valid when the @ref fVoiceParamDopplerScale flag is used. This allows the result of internal Doppler calculations to be scaled to emulate a time warping effect. 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.
- property emitter#
The attributes of the emitter related for this voice. This is only valid when the `VOICE_PARAM_EMITTER` flag is used. This includes the emitter’s position, orientation, velocity, cone, and rolloff curves. The default values for these attributes are noted in the `EmitterAttributes` object. This will be ignored for non-spatial sounds.
- property frequency_ratio#
The frequency ratio for a voice. This is valid when the `VOICE_PARAM_FREQUENCY_RATIO` flag is used. 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.
- property occlusion#
The occlusion factors for a voice. This is valid when the `VOICE_PARAM_OCCLUSION_FACTOR` flag is used. These values control automatic low pass filters that get applied to the spatial sounds to simulate object occlusion between the emitter and listener positions.
- property playback_mode#
either world coordinates or listener relative).
- Type:
Flags to indicate how a sound is to be played back. This value is valid only when the `VOICE_PARAM_PLAYBACK_MODE`, `VOICE_PARAM_MUTE`, or `VOICE_PARAM_PAUSE` flags are used. This controls whether the sound is played as a spatial or non-spatial sound and how the emitter’s attributes will be interpreted (ie
- property priority#
The playback priority of this voice. This is valid when the `VOICE_PARAM_PRIORITY` flag is used. 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.
- property spatial_mix_level#
The spatial mix level. This is valid when `VOICE_PARAM_SPATIAL_MIX_LEVEL` flag is used. This controls 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.
- property volume#
The volume level for the voice. This is valid when the `VOICE_PARAM_VOLUME` flag is used. 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. The default value is 1.0.