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

  • device (Device) – The device on which the context is to be created.

  • attrs (Dict[int, int]) – Attributes specified for the context to be created.

device

The device this context was created from.

Type

Device

listener

The listener instance of this context.

Type

Listener

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 for ALC_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 a SourceGroup (or sub-group thereof) that had its SourceGroup.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 by thread_local.

If thread is True, make the context current for OpenAL operations on the calling thread only. This requires the non-device-specific as well as the context’s device ALC_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 to True, return the thread-specific context used for OpenAL operations. This requires the non-device-specific as well as the context’s device ALC_EXT_thread_local_context extension to be available.

In case thread is not specified, fallback to preference made by thread_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 for current_context and use_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 or X71).

palace.SAMPLE_TYPE: int

Context creation key to specify the sample type (either [UNSIGNED_]{BYTE,SHORT,INT} or FLOAT).

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 or DONT_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 or DONT_CARE).

palace.distance_models: Tuple[str, …]

Names of available distance models.

Audio Devices Resource Caching