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.
context (Optional[Context], optional) – The context from which the source is to be created.
By default current_context() is used.
RuntimeError – If there is neither any context specified nor current.
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 inner and outer angles in degrees.
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.
ValueError – If set to a value where inner is greater than outer
or either of them is outside of the [0, 360] interval.
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 the source, stop playback and release resources.
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
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).
ValueError – If set to a value where refdist is greater than maxdist
or either of them is outside of the [0, FLT_MAX] interval.
The doppler factor for the doppler effect’s pitch shift.
This effectively scales the source and listener velocities
for the doppler calculation.
ValueError – If set to a value outside of the [0, 1] interval.
Fade the source to gain over ms 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.
Linear gains on the direct path signal, clamped to [0, 1].
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.
Base linear volume gain, default to 1.0.
ValueError – If set to a negative value.
Whether automatically adjust gains.
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.
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.
mingain (float) – Minimum gain, default to 0.
maxgain (float) – Maximum gain, default to 1.
ValueError – If set to a value where mingain is greater than maxgain
or either of them is outside of the [0, 1] interval.
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 to None removes the source
from its current group.
A group of Source references
Source latency in nanoseconds.
If AL_SOFT_source_latency extension is unsupported,
this will be 0.
Source latency in seconds.
Whether the source should loop.
The loop points are determined by the playing buffer or decoder.
Source offset in sample frames.
For streaming sources, this will be
based on decoder’s read position.
Source offset in seconds.
For streaming sources, this will be based on
the decoder’s read position.
3D orientation of the source.
at (Tuple[float, float, float]) – Relative position.
up (Tuple[float, float, float]) – Relative direction.
Unlike AL_EXT_BFORMAT extension this property
comes from, this also affects the facing direction.
Gain when listener is out of the source’s outer cone area.
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.
ValueError – If either of the gains is set to a value
outside of the [0, 1] interval.
Pause the source if it is playing.
Whether the source is currently paused.
Linear pitch shift base, default to 1.0.
ValueError – If set to a nonpositive value.
Whether the source is currently playing.
3D position of the source.
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 of the source, as if it is a sound-emitting sphere.
This has no effect without AL_EXT_SOURCE_RADIUS extension.
Whether the source’s 3D parameters are relative to listener.
The affected parameters includes position, velocity,
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 the AL_SOFT_source_resampler extension.
Resume the source if it is paused.
Rolloff factors for the direct and send paths.
This is effectively a distance scaling relative to
the reference distance.
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.
ValueError – If either of rolloff factors is set to a negative value.
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 and filter.
>>> source.sends.effect = effect
>>> source.sends.filter = 1, 0.6, 0.9
Whether to enable 3D spatialization.
Either True (the source always has 3D spatialization
features), False (never has 3D spatialization features),
or None (spatialization is enabled based on playing
a mono sound or not, default).
This has no effect without
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 playback, releasing the buffer or decoder reference.
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.
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.
context (Optional[Context], optional) – The context from which the source group is to be created.
By default current_context() is used.
Destroy the source group, remove and free all sources.
Source group gain.
This accumulates with its sources’ and sub-groups’ gain.
The parent source group of this source group.
RuntimeException – If this group is being added to its sub-group
(i.e. it would create a circular sub-group chain).
Pause all currently-playing sources under this group.
This is done recursively, including sub-groups.
Source group pitch.
This accumulates with its sources’ and sub-groups’ pitch.
Resume all currently-playing sources under this group.
Sources under this group.
Stop all currently-playing sources under this group.
Source groups under this group.