Audio Library Contexts¶
Context and Auxiliary Classes¶
-
class
palace.
Context
¶ Container maintaining the audio environment.
Context contains the environment’s settings and components such as sources, buffers and effects.
This can be used as a context manager, e.g.
with context: ...
is equivalent to
previous = current_context() use_context(context) try: ... finally: use_context(previous) context.destroy()
- Parameters
- Raises
RuntimeError – If context creation fails.
-
async_wake_interval
¶ Current interval used for waking up the background thread.
-
property
available_resamplers
¶ The list of resamplers supported by the context.
If
AL_SOFT_source_resampler
extension is unsupported, this will be an empty list. Otherwise there would be at least one entry.This method require the context to be current.
-
property
default_resampler_index
¶ The context’s default resampler index.
If
AL_SOFT_source_resampler
extension is unsupported, this will return 0.If you try to access the resampler list with this index without extension, undefined behavior will occur (accessing an out of bounds array index).
This method require the context to be current.
-
destroy
() → None¶ Destroy the context.
The context must not be current when this is called.
-
property
distance_model
¶ The model for source attenuation based on distance.
The default, ‘inverse clamped’, provides a realistic l/r reduction in volume (that is, every doubling of distance cause the gain to reduce by half).
The clamped distance models restrict the source distance for the purpose of distance attenuation, so a source won’t sound closer than its reference distance or farther than its max distance.
- Raises
ValueError – If set to a preset cannot be found in
distance_models
.
-
property
doppler_factor
¶ Factor to apply to all source’s doppler calculations.
-
end_batch
() → None¶ Continue processing the context and end batching.
-
is_supported
(channel_config: str, sample_type: str) → bool¶ Return if the channel config and sample type is supported.
This method require the context to be current.
See also
sample_types
Set of sample types
channel_configs
Set of channel configurations
-
message_handler
¶ Handler of some certain events.
-
property
speed_of_sound
¶ The speed of sound propagation in units per second.
It is used to calculate the doppler effect along with other distance-related time effects.
The default is 343.3 units per second (a realistic speed assuming 1 meter per unit). If this is adjusted for a different unit scale,
Listener.meters_per_unit
should also be adjusted.
-
start_batch
() → None¶ Suspend the context to start batching.
-
update
() → None¶ Update the context and all sources belonging to this context.
-
class
palace.
Listener
¶ Listener instance of the given context.
It is recommended that applications access the listener via
Context.listener
, which avoid the overhead caused by the creation of the wrapper object.- Parameters
context (Optional[Context], optional) – The context on which the listener instance is to be created. By default
current_context()
is used.- Raises
RuntimeError – If there is neither any context specified nor current.
-
property
gain
¶ Master gain for all context output.
-
property
meters_per_unit
¶ Number of meters per unit.
This is used for various effects relying on the distance in meters including air absorption and initial reverb decay. If this is changed, so should the speed of sound (e.g.
context.speed_of_sound = 343.3 / meters_per_unit
to maintain a realistic 343.3 m/s for sound propagation).
-
property
orientation
¶ 3D orientation of the listener.
- Parameters
at (Tuple[float, float, float]) – Relative position.
up (Tuple[float, float, float]) – Relative direction.
-
property
position
¶ 3D position of the listener.
-
property
velocity
¶ 3D velocity of the listener, in units per second.
As with OpenAL, this does not actually alter the listener’s position, and instead just alters the pitch as determined by the doppler effect.
-
class
palace.
MessageHandler
¶ Message handler interface.
Applications may derive from this and set an instance on a context to receive messages. The base methods are no-ops, so subclasses only need to implement methods for relevant messages.
Exceptions raised from
MessageHandler
instances are ignored.-
buffer_loading
(name: str, channel_config: str, sample_type: str, sample_rate: int, data: Sequence[int]) → None¶ Handle messages from Buffer initialization.
This is called when a new buffer is about to be created and loaded. which may be called asynchronously for buffers being loaded asynchronously.
- Parameters
name (str) – Resource name passed to
Buffer
.channel_config (str) – Channel configuration of the given audio data.
sample_type (str) – Sample type of the given audio data.
sample_rate (int) – Sample rate of the given audio data.
data (MutableSequence[int]) –
The audio data that is about to be fed to the OpenAL buffer.
It is a mutable memory array of signed 8-bit integers, following Python buffer protocol.
-
device_disconnected
(device: palace.Device) → None¶ Handle disconnected device messages.
This is called when the given device has been disconnected and is no longer usable for output. As per
ALC_EXT_disconnect
specification, disconnected devices remain valid, however all playing sources are automatically stopped, any sources that are attempted to play will immediately stop, and new contexts may not be created on the device.Note
Connection status is checked during
Context.update
calls, so method must be called regularly to be notified when a device is disconnected. This method may not be called if the device lacks support forALC_EXT_disconnect
extension.
-
resource_not_found
(name: str) → str¶ Return the fallback resource for the one of the given name.
This is called when
name
is not found, allowing substitution of a different resource until the returned string either points to a valid resource or is empty (default).For buffers being cached, the original name will still be used for the cache entry so one does not have to keep track of substituted resource names.
-
source_force_stopped
(source: palace.Source) → None¶ Handle forcefully stopped sources.
This is called when the given source was forced to stop, because of one of the following reasons:
There were no more mixing sources and a higher-priority source preempted it.
source
is part of aSourceGroup
(or sub-group thereof) that had itsSourceGroup.stop_all
method called.source
was playing a buffer that’s getting removed.
-
source_stopped
(source: palace.Source) → None¶ Handle end-of-buffer/stream messages.
This is called when the given source reaches the end of buffer or stream, which is detected upon a call to
Context.update
.
-
Using Contexts¶
-
palace.
use_context
(context: Optional[palace.Context], thread: Optional[bool] = None) → None¶ Make the specified context current for OpenAL operations.
This fails silently if the given context has been destroyed. In case
thread
is not specified, fallback to preference made bythread_local
.If
thread
isTrue
, make the context current for OpenAL operations on the calling thread only. This requires the non-device-specific as well as the context’s deviceALC_EXT_thread_local_context
extension to be available.
-
palace.
current_context
(thread: Optional[bool] = None) → Optional[palace.Context]¶ Return the context that is currently used.
If
thread
is set toTrue
, return the thread-specific context used for OpenAL operations. This requires the non-device-specific as well as the context’s deviceALC_EXT_thread_local_context
extension to be available.In case
thread
is not specified, fallback to preference made bythread_local
.
-
palace.
thread_local
(state: bool) → Iterator[None]¶ Return a context manager controlling preference of local thread.
Effectively, it sets fallback value for
thread
argument forcurrent_context
anduse_context
.Initially, globally current
Context
is preferred.
Context Creation Attributes¶
-
palace.
CHANNEL_CONFIG
: int¶ Context creation key to specify the channel configuration (either
MONO
,STEREO
,QUAD
,X51
,X61
orX71
).
-
palace.
SAMPLE_TYPE
: int¶ Context creation key to specify the sample type (either
[UNSIGNED_]{BYTE,SHORT,INT}
orFLOAT
).
-
palace.
FREQUENCY
: int¶ Context creation key to specify the frequency in hertz.
-
palace.
MONO_SOURCES
: int¶ Context creation key to specify the number of mono (3D) sources.
-
palace.
STEREO_SOURCES
: int¶ Context creation key to specify the number of stereo sources.
-
palace.
MAX_AUXILIARY_SENDS
: int¶ Context creation key to specify the maximum number of auxiliary source sends.
-
palace.
HRTF
: int¶ Context creation key to specify whether to enable HRTF (either
FALSE
,TRUE
orDONT_CARE
).
-
palace.
HRTF_ID
: int¶ Context creation key to specify the HRTF to be used.
-
palace.
OUTPUT_LIMITER
: int¶ Context creation key to specify whether to use a gain limiter (either
FALSE
,TRUE
orDONT_CARE
).
-
palace.
distance_models
: Tuple[str, …]¶ Names of available distance models.