34 KiB

Raw Blame History

Reference¶

Pythonic Audio Library and Codecs Environment

palace.device_names¶

Dictionary of available device names corresponding to each type.

Type: Dict[str, List[str]]

palace.device_name_default¶

Dictionary of the default device name corresponding to each type.

Type: Dict[str, str]

palace.query_extension¶

Return if a non-device-specific ALC extension exists.

See also

Device.query_extension: Query device-specific ALC extension

palace.use_context¶

Make the specified context current for OpenAL operations.

See also

Context: Audio environment container

class palace.Device¶

Audio mix output, which is either a system audio output stream or an actual audio port.

This can be used as a context manager that call close upon completion of the block, even if an error occurs.

Parameters

name (str, optional) – The name of the playback device.
fail_safe (bool, optional) – On failure, fallback to the default device if this is True, otherwise RuntimeError is raised. Default to False.

Raises

RuntimeError – If device creation fails.

Warns

RuntimeWarning – If fail_safe is True and the device of given name cannot be opened.

See also

device_names: Available device names
device_name_default: Default device names

alc_version¶: ALC version supported by this device.

close¶: Close and free the device. All previously-created contexts must first be destroyed.

current_hrtf¶

Name of the HRTF currently being used by this device.

If HRTF is not currently enabled, this will be None.

efx_version¶

EFX version supported by this device.

If the ALC_EXT_EFX extension is unsupported, this will be (0, 0).

frequency¶: Playback frequency in hertz.

hrtf_enabled¶

Whether HRTF is enabled on the device.

If the ALC_SOFT_HRTF extension is unavailable, this will return False although there could still be HRTF applied at a lower hardware level.

hrtf_names¶

List of available HRTF names, sorted as OpenAL gives them, such that the index of a given name is the ID to use with ALC_HRTF_ID_SOFT.

If the ALC_SOFT_HRTF extension is unavailable, this will be an empty list.

max_auxiliary_sends¶

Maximum number of auxiliary source sends.

If ALC_EXT_EFX is unsupported, this will be 0.

name¶: A dictionary of device name corresponding to each type.

pause_dsp¶

Pause device processing, stopping updates for its contexts. Multiple calls are allowed but it is not reference counted, so the device will resume after one resume_dsp call.

This requires the ALC_SOFT_pause_device extension.

query_extension¶

Return if an ALC extension exists on this device.

See also

query_extension: Query non-device-specific ALC extension

reset¶

Reset the device, using the specified attributes.

If the ALC_SOFT_HRTF extension is unavailable, this will be a no-op.

resume_dsp¶: Resume device processing, restarting updates for its contexts. Multiple calls are allowed and will no-op.

class palace.Context¶

Container maintaining the entire audio environment, its settings and components such as sources, buffers and effects.

This can be used as a context manager, e.g.

with context:
    ...

is equivalent to

use_context(context)
try:
    ...
finally:
    use_context(None)
    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

Raises: RuntimeError – If context creation fails.

destroy¶: Destroy the context. The context must not be current when this is called.

update¶: Update the context and all sources belonging to this context.

class palace.Buffer¶

Buffer of preloaded PCM samples coming from a Decoder.

Cached buffers must be freed using destroy before destroying context. Alternatively, this can be used as a context manager that call destroy upon completion of the block, even if an error occurs.

Parameters

context (Context) – The context from which the buffer is to be created and cached.
name (str) – Audio file or resource name. Multiple calls with the same name will return the same buffer.

Raises

RuntimeError – If the buffer can’t be loaded.

channel_config_name¶: Buffer’s sample configuration name.

destroy¶: Free the buffer’s cache, invalidating all other Buffer objects with the same name.

frequency¶: Buffer’s frequency in hertz.

length¶: Length of the buffer in sample frames.

play¶

Play source using the buffer. The same buffer may be played from multiple sources simultaneously.

If source is None, create a new one.

Return the source used for playing.

sample_type_name¶: Buffer’s sample type name.

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 (Context) – The context from which the source is to be created.

air_absorption_factor¶: Multiplier for the amount of atmospheric high-frequency absorption, 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.

The inner angle is the area within which the listener will hear the source with no extra attenuation, while the listener being outside of the outer angle will hear the source attenuated according to the outer cone gains. The area follows 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¶: Destroy the source, stop playback and release resources.

distance_range¶

Reference and maximum distance the source will use for the current distance model. For Clamped distance models, the source’s calculated distance is clamped to the specified range before applying distance-related attenuation.

For all distance models, the reference distance is the distance at which the source’s volume will not have any extra attenuation (an effective gain multiplier of 1).

doppler_factor¶: The doppler factor for the doppler effect’s pitch shift. This effectively scales the source and listener velocities for the doppler calculation.

gain¶: Base linear volume gain, default to 1.0.

gain_auto¶: Whether the direct path’s high frequency gain, send paths’ gain and send paths’ high-frequency gain are automatically adjusted. The default is True for all.

gain_range¶: Minimum and maximum gain. The source’s gain is clamped to this range after distance attenuation and cone attenuation are applied to the gain base, although before the filter gain adjustements.

looping¶: Whether the source should loop on the Buffer or Decoder object’s loop points.

offset¶: Source offset in sample frames. For streaming sources this will be the offset based on the decoder’s read position.

orientation¶

3D orientation, using at and up vectors, which are respectively relative position and direction.

Notes

Unlike the AL_EXT_BFORMAT extension this property comes from, this also affects the facing direction.

outer_cone_gains¶

Linear gain and gainhf multiplier when the listener is outside of the source’s outer cone area.

Parameters

gain (float) – Linear gain applying to all frequencies.
gainhf (float) – Linear gainhf applying extra attenuation to high frequencies creating a low-pass effect. It has no effect without the ALC_EXT_EFX extension.

pause¶: Pause the source if it is playing.

paused¶: Whether the source is currently paused.

pending¶: Whether the source is waiting to play a future buffer.

pitch¶: Linear pitch shift base, default to 1.0.

playing¶: Whether the source is currently playing.

playing_or_pending¶: Whether the source is currently playing or waiting to play in a future buffer.

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. This causes the source to behave as if every point within the spherical area emits sound.

This has no effect without the AL_EXT_SOURCE_RADIUS extension.

relative¶: Whether the source’s position, velocity, and orientation are relative to the listener.

resampler_index¶

Index of the resampler to use for this source. The index is from the resamplers returned by Context.get_available_resamplers, and must be nonnegative.

This has no effect without the AL_SOFT_source_resampler extension.

resume¶: Resume the source if it is paused.

rolloff_factors¶

Rolloff factor and room factor for the direct and send paths.

This is effectively a distance scaling relative to the reference distance.

Note: to disable distance attenuation for send paths, set room factor to 0. The reverb engine will, by default, apply a more realistic room decay based on the reverb decay time and distance.

spatialize¶

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 the AL_SOFT_source_spatialize extension.

stereo_angles¶

Left and right channel angles, in radians, when playing a stereo buffer or stream. The angles go counter-clockwise, with 0 being in front and positive values going left.

This has no effect without the AL_EXT_STEREO_ANGLES extension.

stop¶: Stop playback, releasing the buffer or decoder reference. Any pending playback from a future buffer is canceled.

velocity¶: 3D velocity in units per second. As with OpenAL, this does not actually alter the source’s osition, and instead just alters the pitch as determined by the doppler effect.

class palace.Decoder¶

Audio decoder interface.

Parameters

context (Context) – The context from which the decoder is to be created.
name (str) – Audio file or resource name.

See also

Buffer: Preloaded PCM samples coming from a Decoder

channel_config_name¶: Name of the channel configuration of the audio being decoded.

frequency¶: Sample frequency, in hertz, of the audio being decoded.

length¶: Total length of the audio, in sample frames, falling-back to 0. Note that if the length is 0, the decoder may not be used to load a Buffer.

play¶

Play source by asynchronously streaming audio from the decoder. The decoder must NOT have its read or seek called from elsewhere while in use.

Return the source used for playing.

Parameters

chunk_len (int) – The number of sample frames to read for each chunk update. Smaller values will require more frequent updates and larger values will handle more data with each chunk.
queue_size (int) – The number of chunks to keep queued during playback. Smaller values use less memory while larger values improve protection against underruns.
source (Source, optional) – The source object to play audio. If this is None, a new one will be created.

sample_type_name¶: Name of the sample type of the audio being decoded.

palace

Navigation

Contents:

Reference

34 KiB Raw Blame History Unescape Escape

Reference¶

palace

Navigation

Related Topics

Quick search

34 KiB

Raw Blame History