36 KiB
Table of Contents
Quick Navigation
Quick search
Sources & Source Groups¶
Sources¶
-
class
palace.
Source
¶ Sound source for playing audio.
There is no practical limit to the number of sources one may create.
When the source is no longer needed,
destroy
must be called, unless the context manager is used, which guarantees the source’s destructioni upon completion of the block, even if an error occurs.- Parameters
context (Optional[Context], optional) – The context from which the source is to be created. By default
current_context()
is used.- Raises
RuntimeError – If there is neither any context specified nor current.
-
air_absorption_factor
¶ Multiplier for atmospheric high-frequency absorption
Its value ranging from 0 to 10. A factor of 1 results in a nominal -0.05 dB per meter, with higher values simulating foggy air and lower values simulating dryer air; default to 0.
-
cone_angles
¶ Cone inner and outer angles in degrees.
- Returns
inner (float) – The area within which the listener will hear the source without extra attenuation, default to 360.
outer (float) – The area outside of which the listener will hear the source attenuated according to
outer_cone_gains
, default to 360.
- Raises
ValueError – If set to a value where
inner
is greater thanouter
or either of them is outside of the [0, 360] interval.
Notes
The areas follow the facing direction, so for example an inner angle of 180 means the entire front face of the source is in the inner cone.
-
destroy
() → None¶ Destroy the source, stop playback and release resources.
-
distance_range
¶ Reference and maximum distance for current distance model.
For Clamped distance models, the source’s calculated distance is clamped to the specified range before applying distance-related attenuation.
- Returns
refdist (float) – The distance at which the source’s volume will not have any extra attenuation (an effective gain multiplier of 1), default to 0.
maxdist (float) – The maximum distance, default to FLT_MAX, which is the maximum value of a single-precision floating-point variable (2**128 - 2**104).
- Raises
ValueError – If set to a value where
refdist
is greater thanmaxdist
or either of them is outside of the [0, FLT_MAX] interval.
-
doppler_factor
¶ The doppler factor for the doppler effect’s pitch shift.
This effectively scales the source and listener velocities for the doppler calculation.
- Raises
ValueError – If set to a value outside of the [0, 1] interval.
-
fade_out_to_stop
(gain: float, ms: int) → None¶ Fade the source to
gain
overms
milliseconds.gain
is in addition to the base gain and must be within the [0, 1] interval.ms
must be positive.The fading is logarithmic. As a result, the initial drop-off may happen faster than expected but the fading is more perceptually consistant over the given duration. It will take just as much time to go from -6 dB to -12 dB as it will to go from -40 dB to -46 dB, for example.
Fading is updated during calls to
Context.update
, which should be called regularly (30 to 50 times per second) for the fading to be smooth.
-
property
filter
¶ Linear gains on the direct path signal, clamped to [0, 1].
- Parameters
gain (float) – Linear gain applying to all frequencies, default to 1.
gain_hf (float) – Linear gain applying to high frequencies, default to 1.
gain_lf (float) – Linear gain applying to low frequencies, default to 1.
-
gain
¶ Base linear volume gain, default to 1.0.
- Raises
ValueError – If set to a negative value.
-
gain_auto
¶ Whether automatically adjust gains.
- Returns
direct_hf (bool) – Direct path’s high frequency gain, default to
True
.send (bool) – Send paths’ gain, default to
True
.send_hf (bool) – Send paths’ high-frequency, default to
True
.
-
gain_range
¶ The range which the source’s gain is clamped to.
This is used after distance and cone attenuation are applied to the gain base and before the adjustments of the filter gain.
- Returns
mingain (float) – Minimum gain, default to 0.
maxgain (float) – Maximum gain, default to 1.
- Raises
ValueError – If set to a value where
mingain
is greater thanmaxgain
or either of them is outside of the [0, 1] interval.
-
group
¶ Parent group of this source.
The parent group influences all sources that belong to it. A source may only be the child of one
SourceGroup
at a time, although that source group may belong to another source group.This is
None
when the source does not belong to any group. On the other hand, setting it toNone
removes the source from its current group.See also
SourceGroup
A group of
Source
references
-
property
latency
¶ Source latency in nanoseconds.
If
AL_SOFT_source_latency
extension is unsupported, this will be 0.
-
property
latency_seconds
¶ Source latency in seconds.
If
AL_SOFT_source_latency
extension is unsupported, this will be 0.
-
looping
¶ Whether the source should loop.
The loop points are determined by the playing buffer or decoder.
-
offset
¶ Source offset in sample frames.
For streaming sources, this will be based on decoder’s read position.
-
property
offset_seconds
¶ Source offset in seconds.
For streaming sources, this will be based on the decoder’s read position.
-
orientation
¶ 3D orientation of the source.
- Returns
at (Tuple[float, float, float]) – Relative position.
up (Tuple[float, float, float]) – Relative direction.
Notes
Unlike
AL_EXT_BFORMAT
extension this property comes from, this also affects the facing direction.
-
outer_cone_gains
¶ Gain when listener is out of the source’s outer cone area.
- Returns
gain (float) – Linear gain applying to all frequencies, default to 1.
gain_hf (float) – Linear gain applying extra attenuation to high frequencies creating a low-pass effect, default to 1. It has no effect without the
ALC_EXT_EFX
extension.
- Raises
ValueError – If either of the gains is set to a value outside of the [0, 1] interval.
-
pause
() → None¶ Pause the source if it is playing.
-
property
paused
¶ Whether the source is currently paused.
-
pitch
¶ Linear pitch shift base, default to 1.0.
- Raises
ValueError – If set to a nonpositive value.
-
property
playing
¶ Whether the source is currently playing.
-
position
¶ 3D position of the source.
-
priority
¶ Playback priority (natural number).
The lowest priority sources will be forcefully stopped when no more mixing sources are available and higher priority sources are played.
-
radius
¶ Radius of the source, as if it is a sound-emitting sphere.
This has no effect without
AL_EXT_SOURCE_RADIUS
extension.- Raises
ValueError – If set to a negative value.
-
relative
¶ Whether the source’s 3D parameters are relative to listener.
The affected parameters includes
position
,velocity
, andorientation
.
-
resampler_index
¶ Index of the resampler to use for this source.
The index must be nonnegative, from the resamplers returned by
Context.get_available_resamplers
, and has no effect without theAL_SOFT_source_resampler
extension.
-
resume
() → None¶ Resume the source if it is paused.
-
rolloff_factors
¶ Rolloff factors for the direct and send paths.
This is effectively a distance scaling relative to the reference distance.
- Returns
factor (float) – Rolloff factor.
room_factor (float) – Room rolloff factor, default to 0 which disables distance attenuation for send paths. This is because the reverb engine will, by default, apply a more realistic room decay based on the reverb decay time and distance.
- Raises
ValueError – If either of rolloff factors is set to a negative value.
-
property
sends
¶ Collection of send path signals.
Send paths can be retrieved using a nonnegative index, which has no effect if not less than the device’s
max_auxiliary_sends
.Each send path has two write-only descriptors,
effect
andfilter
.Examples
>>> source.sends[0].effect = effect >>> source.sends[1].filter = 1, 0.6, 0.9
-
spatialize
¶ Whether to enable 3D spatialization.
Either
True
(the source always has 3D spatialization features),False
(never has 3D spatialization features), orNone
(spatialization is enabled based on playing a mono sound or not, default).This has no effect without
AL_SOFT_source_spatialize
extension.
-
stereo_angles
¶ Left and right channel angles, in radians.
The angles go counter-clockwise, with 0 being in front and positive values going left.
This is only used for stereo playback and has no effect without
AL_EXT_STEREO_ANGLES
extension.
-
stop
() → None¶ Stop playback, releasing the buffer or decoder reference.
-
velocity
¶ 3D velocity in units per second.
As with OpenAL, this does not actually alter the source’s position, and instead just alters the pitch as determined by the doppler effect.
Source Groups¶
-
class
palace.
SourceGroup
¶ A group of
Source
references.For instance, setting
SourceGroup.gain
to 0.5 will halve the gain of all sources in the group.This can be used as a context manager that calls
destroy
upon completion of the block, even if an error occurs.- Parameters
context (Optional[Context], optional) – The context from which the source group is to be created. By default
current_context()
is used.- Raises
RuntimeError – If there is neither any context specified nor current.
-
destroy
() → None¶ Destroy the source group, remove and free all sources.
-
gain
¶ Source group gain.
This accumulates with its sources’ and sub-groups’ gain.
-
parent_group
¶ The parent source group of this source group.
- Raises
RuntimeException – If this group is being added to its sub-group (i.e. it would create a circular sub-group chain).
-
pause_all
() → None¶ Pause all currently-playing sources under this group.
This is done recursively, including sub-groups.
-
pitch
¶ Source group pitch.
This accumulates with its sources’ and sub-groups’ pitch.
-
resume_all
() → None¶ Resume all currently-playing sources under this group.
This is done recursively, including sub-groups.
-
property
sources
¶ Sources under this group.
-
stop_all
() → None¶ Stop all currently-playing sources under this group.
This is done recursively, including sub-groups.
-
property
sub_groups
¶ Source groups under this group.