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 than outer or either of them is outside of the [0, 360] interval.

Note

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 than maxdist 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 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.

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 than maxgain 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 to None 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.

Note

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, and orientation.

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 the AL_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 and filter.

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), or None (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.

Resource Caching Environmental Effects