API reference

This page is generated from PyALSoft's public package exports, type annotations, and docstrings. Names from implementation modules and other private members are not included. The low-level pyalsoft.bindings namespace has a separate reference.

Function-oriented managed audio and low-level OpenAL Soft bindings.

pyalsoft.Effect

Effect = (
    Reverb
    | EAXReverb
    | Chorus
    | Distortion
    | Echo
    | Flanger
    | FrequencyShifter
    | VocalMorpher
    | PitchShifter
    | RingModulator
    | AutoWah
    | Compressor
    | Equalizer
    | DedicatedDialogue
    | DedicatedLowFrequencyEffect
)

A supported auxiliary EFX effect configuration.

pyalsoft.Filter

Filter = LowPassFilter | HighPassFilter | BandPassFilter

A supported direct or auxiliary EFX filter configuration.

pyalsoft.Vector3

Vector3 = tuple[float, float, float]

A Cartesian (x, y, z) vector used for spatial coordinates.

pyalsoft.Acoustics dataclass

Complete immutable acoustic settings for one playback context.

Attributes:

Name	Type	Description
distance_model	DistanceModel	Formula used for distance attenuation.
doppler_factor	float	Non-negative scale for Doppler shift; 0 disables it.
speed_of_sound	float	Propagation speed in world-units per second; at least 0.0001. The default 343.3 represents meters per second in dry air.
meters_per_unit	float	Number of meters represented by one world-space unit. This scales EFX air absorption and must be non-negative.

Raises:

Type	Description
TypeError	A field has the wrong type.
ValueError	A numeric field is non-finite or outside its supported range.

pyalsoft.AmbisonicLayout

Bases: Enum

Channel ordering for B-format buffer data.

pyalsoft.AmbisonicScaling

Bases: Enum

Coefficient normalization for B-format buffer data.

pyalsoft.AutoWah dataclass

Bases: _EffectConfig

Envelope-controlled wah effect.

Attributes:

Name	Type	Description
attack_time	float	Envelope attack, from 0.0001 through 1.0 seconds.
release_time	float	Envelope release, from 0.0001 through 1.0 seconds.
resonance	float	Filter resonance, from 2.0 through 1000.0.
peak_gain	float	Peak filter gain, from 0.00003 through 31621.0.

pyalsoft.AudioBackendError

Bases: AudioError

Raised when OpenAL rejects a managed API operation.

pyalsoft.AudioError

Bases: Exception

Base exception for the managed audio API.

pyalsoft.AudioFileError

Bases: AudioError

Raised when a file cannot be decoded by the convenience API.

pyalsoft.BandPassFilter dataclass

Bases: _FilterConfig

An EFX filter that attenuates low and high frequencies independently.

All three gain controls range from 0.0 through 1.0.

pyalsoft.BufferData dataclass

Immutable payload for an exact OpenAL buffer format.

frame_count is the decoded sample-frame count. It keeps duration, seeking, and queue accounting deterministic for compressed formats whose byte size does not reveal their decoded length.

info property

info: BufferInfo

Format and decoded-length information for this payload.

duration property

duration: float

Decoded duration in seconds.

pyalsoft.BufferFormat

Bases: Enum

Exact sample layouts accepted by managed OpenAL buffer uploads.

Unlike SampleType, these values describe both the channel layout and encoding. Most values require the OpenAL extension named by required_extensions.

native_format property

native_format: ALFormat

Low-level AL_FORMAT_* value used for upload.

required_extensions property

required_extensions: tuple[str, ...]

Alternative OpenAL extensions that can provide this format.

An empty tuple identifies a core format. Most extension formats return one item. Mono and stereo mu-law can be supplied by either of two historical extensions.

sample_type property

sample_type: SampleType | None

Decoded fixed-width sample representation, when applicable.

sample_width_bytes property

sample_width_bytes: int | None

Encoded bytes per channel frame, or None for opaque/block data.

pyalsoft.BufferInfo dataclass

Format and length information for an extension-format buffer.

duration_seconds property

duration_seconds: float

Duration in decoded source-audio seconds.

sample_type property

sample_type: SampleType | None

Fixed-width decoded sample type, or None for encoded data.

pyalsoft.CaptureDevice dataclass

A named capture device reported by the selected OpenAL runtime.

Instances returned by list_capture_devices can be passed directly to start_recording or record.

Attributes:

Name	Type	Description
name	str	Implementation-provided device specifier.
is_default	bool	Whether the runtime reported this as its default device.

Raises:

Type	Description
TypeError	name is not a string or is_default is not a boolean.
ValueError	name is empty.

pyalsoft.CaptureOpenError

Bases: AudioError

Raised when an audio capture device cannot be opened.

pyalsoft.CaptureStream

Opaque owner for bounded incremental capture.

Use start_capture_stream and consume data with read_capture_stream. If the producer outruns the consumer, the oldest frames are discarded and overrun_count records how many frames were lost.

pyalsoft.CaptureStreamStatus dataclass

Current bounded capture-buffer accounting.

Attributes:

Name	Type	Description
buffered_frames	int	Unread frames currently retained.
capacity_frames	int	Maximum unread frames retained.
overrun_count	int	Oldest frames discarded since capture started.
closed	bool	Whether native capture has stopped and the device is closed.

pyalsoft.Clip dataclass

Opaque identity for audio data uploaded to a playback session.

Do not construct instances directly. A clip belongs to the Playback that returned it and remains valid until it is passed to release or that session is closed.

info property

info: SoundInfo | BufferInfo

Format and length information for this clip.

duration_seconds property

duration_seconds: float

Duration of this clip in source-audio seconds.

frame_count property

frame_count: int

Number of sample frames in this clip.

loop_points property

loop_points: tuple[int, int] | None

Configured (start, end) loop-frame range, or None.

The start frame is inclusive and the end frame is exclusive. When this is None, a looping voice repeats the complete clip.

pyalsoft.Chorus dataclass

Bases: _EffectConfig

Chorus modulation effect.

Attributes:

Name	Type	Description
waveform	ModulationWaveform	Sinusoid or triangle modulation.
phase	int	Stereo phase difference, from -180 through 180 degrees.
rate	float	Modulation frequency, from 0.0 through 10.0 Hz.
depth	float	Modulation depth, from 0.0 through 1.0.
feedback	float	Feedback amount, from -1.0 through 1.0.
delay	float	Average delay, from 0.0 through 0.016 seconds.

pyalsoft.Compressor dataclass

Bases: _EffectConfig

Automatic gain compressor with an enable switch.

Attributes:

Name	Type	Description
enabled	bool	Whether compression is enabled.

pyalsoft.DedicatedDialogue dataclass

Bases: _EffectConfig

Route audio to the implementation's dedicated dialogue channel.

This effect requires ALC_EXT_DEDICATED. gain is a non-negative linear multiplier applied to the dedicated output.

pyalsoft.DedicatedLowFrequencyEffect dataclass

Bases: _EffectConfig

Route audio to the implementation's dedicated low-frequency channel.

This effect requires ALC_EXT_DEDICATED. gain is a non-negative linear multiplier applied to the dedicated output.

pyalsoft.DirectChannelsMode

Bases: Enum

Routing behavior for non-spatial stereo sources.

pyalsoft.DeviceEvent dataclass

One queued device-list notification from OpenAL Soft.

Unknown future native event or device values are preserved as integers.

Attributes:

Name	Type	Description
type	DeviceEventType | int	Device-list change kind.
device_kind	DeviceKind | int	Playback or capture device family.
name	str	Implementation-provided device name.

pyalsoft.DeviceEventSubscription

Bounded queue of device events delivered outside native callbacks.

Use subscribe_device_events instead of constructing this class directly. Only one managed or low-level system-event registration can own a loaded native library at a time.

closed property

closed: bool

Whether the subscription has been closed.

dropped_count property

dropped_count: int

Number of oldest queued events discarded because the queue was full.

next

next(timeout: float | None = None) -> DeviceEvent | None

Return the next event, or None after timeout or closure.

close

close() -> None

Stop native delivery and wake threads waiting for events.

pyalsoft.DeviceEventType

Bases: Enum

Kind of playback or capture device-list change.

pyalsoft.DeviceKind

Bases: Enum

Device family affected by a managed system event.

pyalsoft.DistanceModel

Bases: Enum

Distance-attenuation model used by a playback context.

NONE disables distance attenuation. The other values select the OpenAL inverse, linear, or exponential formulas, with either clamped or unclamped distance inputs.

Attributes:

Name	Type	Description
NONE		Do not attenuate sounds based on distance.
INVERSE		Use the inverse-distance formula.
INVERSE_CLAMPED		Use inverse distance clamped to the configured bounds.
LINEAR		Use the linear-distance formula.
LINEAR_CLAMPED		Use linear distance clamped to the configured bounds.
EXPONENT		Use the exponential-distance formula.
EXPONENT_CLAMPED		Use exponential distance clamped to the configured bounds.

pyalsoft.Distortion dataclass

Bases: _EffectConfig

Distortion with pre- and post-equalization controls.

Attributes:

Name	Type	Description
edge	float	Distortion edge, from 0.0 through 1.0.
gain	float	Output gain, from 0.01 through 1.0.
low_pass_cutoff	float	Low-pass cutoff, from 80 through 24000 Hz.
equalizer_center	float	Equalizer center, from 80 through 24000 Hz.
equalizer_bandwidth	float	Equalizer bandwidth, from 80 through 24000 Hz.

pyalsoft.EAXReverb dataclass

Bases: _EffectConfig

Extended EAX reverb, including pan, echo, and modulation controls.

Attributes:

Name	Type	Description
density	float	Modal density, from 0.0 through 1.0.
diffusion	float	Echo density, from 0.0 through 1.0.
gain	float	Overall wet-signal gain, from 0.0 through 1.0.
high_frequency_gain	float	High-frequency wet gain, from 0.0 through 1.0.
low_frequency_gain	float	Low-frequency wet gain, from 0.0 through 1.0.
decay_time	float	Decay time, from 0.1 through 20.0 seconds.
high_frequency_decay_ratio	float	High-frequency decay ratio, from 0.1 to 2.0.
low_frequency_decay_ratio	float	Low-frequency decay ratio, from 0.1 to 2.0.
reflections_gain	float	Early-reflections gain, from 0.0 through 3.16.
reflections_delay	float	Early-reflections delay, from 0.0 through 0.3 seconds.
reflections_pan	Vector3	Early-reflections pan vector.
late_reverb_gain	float	Late-reverberation gain, from 0.0 through 10.0.
late_reverb_delay	float	Late-reverberation delay, from 0.0 through 0.1 seconds.
late_reverb_pan	Vector3	Late-reverberation pan vector.
echo_time	float	Echo repetition time, from 0.075 through 0.25 seconds.
echo_depth	float	Echo depth, from 0.0 through 1.0.
modulation_time	float	Modulation period, from 0.04 through 4.0 seconds.
modulation_depth	float	Modulation depth, from 0.0 through 1.0.
air_absorption_high_frequency_gain	float	Per-meter high-frequency air absorption gain, from 0.892 through 1.0.
high_frequency_reference	float	High-frequency reference, from 1000 through 20000 Hz.
low_frequency_reference	float	Low-frequency reference, from 20 through 1000 Hz.
room_rolloff_factor	float	Distance-based room attenuation, from 0.0 through 10.0.
high_frequency_decay_limit	bool	Whether air absorption limits high-frequency decay time.

pyalsoft.Echo dataclass

Bases: _EffectConfig

Echo with stereo offset, damping, feedback, and spread controls.

Attributes:

Name	Type	Description
delay	float	Primary tap delay, from 0.0 through 0.207 seconds.
left_right_delay	float	Left/right tap delay, from 0.0 through 0.404 seconds.
damping	float	High-frequency damping, from 0.0 through 0.99.
feedback	float	Feedback amount, from 0.0 through 1.0.
spread	float	Stereo spread, from -1.0 through 1.0.

pyalsoft.EffectBus dataclass

Opaque identity for one reusable managed auxiliary effect bus.

Instances are created by create_effect_bus. A bus belongs to exactly one playback session and can be referenced by any number of EffectSend values in that session.

pyalsoft.EffectBusConfig dataclass

Complete immutable configuration for a reusable auxiliary effect bus.

target optionally chains this bus into another bus. Chaining requires AL_SOFT_effect_target and cycles are rejected.

pyalsoft.EffectSend dataclass

One auxiliary effect route, with an optional wet-signal filter.

Tuple order in VoiceConfig.effect_sends determines the native auxiliary-send index. The playback device limits the number of simultaneous sends.

Attributes:

Name	Type	Description
effect	Effect | None	Effect owned by this route, mutually exclusive with bus.
bus	EffectBus | None	Reusable effect bus, mutually exclusive with effect.
filter	Filter | None	Optional filter applied only to this route's wet signal.

pyalsoft.Equalizer dataclass

Bases: _EffectConfig

Four-band equalizer.

Attributes:

Name	Type	Description
low_gain	float	Low-band gain, from 0.126 through 7.943.
low_cutoff	float	Low-band cutoff, from 50 through 800 Hz.
low_mid_gain	float	Low-mid-band gain, from 0.126 through 7.943.
low_mid_center	float	Low-mid center, from 200 through 3000 Hz.
low_mid_width	float	Low-mid relative width, from 0.01 through 1.0.
high_mid_gain	float	High-mid-band gain, from 0.126 through 7.943.
high_mid_center	float	High-mid center, from 1000 through 8000 Hz.
high_mid_width	float	High-mid relative width, from 0.01 through 1.0.
high_gain	float	High-band gain, from 0.126 through 7.943.
high_cutoff	float	High-band cutoff, from 4000 through 16000 Hz.

pyalsoft.Flanger dataclass

Bases: _EffectConfig

Flanger modulation effect.

Attributes:

Name	Type	Description
waveform	ModulationWaveform	Sinusoid or triangle modulation.
phase	int	Stereo phase difference, from -180 through 180 degrees.
rate	float	Modulation frequency, from 0.0 through 10.0 Hz.
depth	float	Modulation depth, from 0.0 through 1.0.
feedback	float	Feedback amount, from -1.0 through 1.0.
delay	float	Average delay, from 0.0 through 0.004 seconds.

pyalsoft.FrequencyShiftDirection

Bases: Enum

Direction applied to a frequency-shifter channel.

pyalsoft.FrequencyShifter dataclass

Bases: _EffectConfig

Independent left- and right-channel frequency shifting.

Attributes:

Name	Type	Description
frequency	float	Shift frequency, from 0 through 24000 Hz.
left_direction	FrequencyShiftDirection	Down, up, or disabled for the left channel.
right_direction	FrequencyShiftDirection	Down, up, or disabled for the right channel.

pyalsoft.HRTFStatus

Bases: Enum

Observed HRTF state for an open playback session.

Attributes:

Name	Type	Description
UNAVAILABLE		The device does not expose ALC_SOFT_HRTF.
DISABLED		HRTF rendering is disabled.
ENABLED		HRTF rendering is enabled.
DENIED		HRTF was requested but could not be enabled.
REQUIRED		HRTF was enabled because the device requires it.
HEADPHONES_DETECTED		HRTF was enabled after headphone detection.
UNSUPPORTED_FORMAT		The output format does not support HRTF rendering.
UNKNOWN		The backend returned a status unknown to this PyALSoft version.

pyalsoft.HighPassFilter dataclass

Bases: _FilterConfig

An EFX filter that attenuates the low-frequency signal.

gain and low_frequency_gain range from 0.0 through 1.0.

pyalsoft.InvalidHandleError

Bases: AudioError

Raised when a resource is stale or belongs to another session.

pyalsoft.InvalidVoiceStateError

Bases: AudioError

Raised when an operation is not valid for a voice's current state.

pyalsoft.Listener dataclass

Complete immutable spatial state for a playback listener.

Attributes:

Name	Type	Description
position	Vector3	Listener position in world coordinates.
velocity	Vector3	Listener velocity used for Doppler shift.
forward	Vector3	Non-zero vector describing the viewing direction.
up	Vector3	Non-zero vector describing the upward direction.
gain	float	Non-negative linear gain applied to the final mix.

Raises:

Type	Description
TypeError	A field has the wrong type.
ValueError	A vector is invalid or gain is negative or non-finite.

pyalsoft.LowPassFilter dataclass

Bases: _FilterConfig

An EFX filter that attenuates the high-frequency signal.

gain and high_frequency_gain range from 0.0 through 1.0.

pyalsoft.ModulationWaveform

Bases: Enum

Waveform used by chorus and flanger modulation.

pyalsoft.PCM dataclass

Immutable, interleaved PCM sample data ready to upload.

The constructor copies any bytes-like input to immutable bytes. The byte count must contain a whole number of frames.

Attributes:

Name	Type	Description
samples	bytes	Interleaved sample bytes.
channels	int	Number of interleaved channels in a standard mono, stereo, quad, 5.1, 6.1, or 7.1 layout.
sample_rate	int	Positive number of sample frames per second.
sample_type	SampleType	Representation used by each channel sample.
frame_count	int	Number of complete sample frames.
duration	float	Duration in seconds on the source-audio timeline.
info	SoundInfo	Format and length information as a SoundInfo.

Raises:

Type	Description
TypeError	A constructor argument has the wrong type.
ValueError	The samples or format do not describe supported, complete PCM.

frame_count property

frame_count: int

Number of sample frames in this PCM value.

duration property

duration: float

Duration of this PCM value in seconds.

info property

info: SoundInfo

Format and length information for this PCM value.

pyalsoft.Playback

Opaque owner for a playback device, context, clips, voices, and streams.

Instances are returned by open_playback. Use them as context managers or pass them to close_playback for deterministic cleanup. Operations are serialized per session and across sessions sharing a native library, so a session may safely be used from multiple Python threads.

When this session's context is still current, closing restores the context that was current when the session opened. Do not construct instances directly. Closing a session invalidates every Clip, Voice, and Stream that belongs to it.

pyalsoft.OfflinePlayback

Bases: Playback

Managed playback session whose output is rendered into memory.

render_config property

render_config: RenderConfig

Immutable output format selected when this session opened.

pyalsoft.PlaybackConfig dataclass

Preferences applied while creating an OpenAL playback context.

None preserves the backend default when opening a session. When passed to reconfigure_playback, None omits that field from a patch and preserves the session's previous request. With replace=True, None returns the field to backend-selected behavior.

Attributes:

Name	Type	Description
sample_rate	int | None	Requested device sample rate in frames per second. None preserves the backend default.
refresh_rate	int | None	Requested context refresh rate in updates per second. None preserves the backend default. OpenAL Soft accepts but ignores this core OpenAL attribute.
synchronous	bool | None	Whether to request a synchronous context. None preserves the backend default. OpenAL Soft accepts but ignores this core OpenAL attribute.
mono_sources	int | None	Requested minimum number of mono, spatial source voices.
stereo_sources	int | None	Requested minimum number of stereo, non-spatial source voices.
max_auxiliary_sends	int | None	Requested maximum EFX sends per source. A request is ignored when ALC_EXT_EFX is unavailable.
hrtf	bool | None	Whether to request HRTF rendering. None leaves the backend's default unchanged. A request is ignored when the selected device does not expose ALC_SOFT_HRTF; inspect PlaybackInfo.hrtf_status for the result.
hrtf_name	str | None	Preferred HRTF profile from list_hrtf_profiles. This is a hint independent of hrtf and is ignored when ALC_SOFT_HRTF is unavailable.
output_limiter	bool | None	Whether to request the device output limiter. None preserves the backend default. A request is ignored when ALC_SOFT_output_limiter is unavailable.
output_mode	PlaybackOutputMode | None	Requested speaker or stereo-rendering layout. None preserves the backend default. A request is ignored when ALC_SOFT_output_mode is unavailable.

Raises:

Type	Description
TypeError	A field has the wrong type.
ValueError	A numeric request is outside the ALC integer range or PlaybackOutputMode.UNKNOWN is requested.

pyalsoft.PlaybackClosedError

Bases: AudioError

Raised when an operation uses a closed playback session.

pyalsoft.PlaybackDevice dataclass

A named playback device reported by the selected OpenAL runtime.

Instances returned by list_playback_devices can be passed directly to open_playback.

Attributes:

Name	Type	Description
name	str	Implementation-provided device specifier.
is_default	bool	Whether the runtime reported this as its default device.

Raises:

Type	Description
TypeError	name is not a string or is_default is not a boolean.
ValueError	name is empty.

pyalsoft.PlaybackInfo dataclass

Observed properties of an open playback session.

Attributes:

Name	Type	Description
device_name	str	Implementation-provided name of the opened device.
renderer	str	Active OpenAL renderer name.
version	str	Active OpenAL implementation version.
hrtf_status	HRTFStatus	Observed HRTF state.
hrtf_name	str | None	Active HRTF specifier, or None when none is available.
sample_rate	int | None	Active device sample rate in frames per second.
refresh_rate	int | None	Active context refresh rate in updates per second.
synchronous	bool | None	Whether the active context is synchronous.
mono_sources	int | None	Number of mono, spatial source voices available.
stereo_sources	int | None	Number of stereo, non-spatial source voices available.
max_auxiliary_sends	int | None	Active EFX send limit per source, or None when ALC_EXT_EFX is unavailable.
output_limiter	bool | None	Active output-limiter state, or None when ALC_SOFT_output_limiter is unavailable.
output_mode	PlaybackOutputMode | None	Active device output mode, or None when ALC_SOFT_output_mode is unavailable.
connected	bool | None	Whether the device remains connected, or None when ALC_EXT_disconnect is unavailable.

pyalsoft.PlaybackClock dataclass

Atomically measured audio-device clock and output latency.

device_time_seconds property

device_time_seconds: float

Audio-device clock time in seconds.

output_latency_seconds property

output_latency_seconds: float

Physical-output latency in seconds.

pyalsoft.PlaybackOpenError

Bases: AudioError

Raised when a playback device or context cannot be opened.

pyalsoft.PlaybackOutputMode

Bases: Enum

Requested or observed playback-device output layout.

ANY lets the backend select a layout. The stereo variants distinguish ordinary speaker mixing, UHJ surround encoding, and HRTF rendering. UNKNOWN is reserved for an unrecognized value reported by a newer backend and cannot be requested in PlaybackConfig.

pyalsoft.RenderChannelLayout

Bases: Enum

Channel layout produced by a managed offline rendering session.

pyalsoft.RenderConfig dataclass

Output format for a managed offline rendering session.

channel_count property

channel_count: int

Number of interleaved channels in one rendered frame.

frame_width_bytes property

frame_width_bytes: int

Number of bytes in one interleaved rendered frame.

pyalsoft.RenderSampleType

Bases: Enum

One sample representation produced by offline rendering.

byte_width property

byte_width: int

Number of bytes used by one rendered channel sample.

pyalsoft.PlayingSound dataclass

One playback instance returned by play.

The default playback runtime owns the native resources, so discarding this object does not stop the sound. Its methods are convenient delegates to the function-oriented managed API. Handles retain their final status after natural completion, an explicit stop, device loss, or runtime shutdown.

Do not construct instances directly. Use play with an audio path or PCM value.

status property

status: VoiceStatus

Current playback state and offset.

state property

state: VoiceState

Current playback state.

playing property

playing: bool

Whether the sound is playing or waiting for a scheduled start.

paused property

paused: bool

Whether the sound is currently paused.

stopped property

stopped: bool

Whether the sound is no longer playing or resumable.

done property

done: bool

Whether the sound has completed naturally or was stopped.

finished property

finished: bool

Whether playback reached the end naturally.

end_reason property

end_reason: SoundEndReason | None

Why the sound ended, or None while it remains active.

offset_seconds property

offset_seconds: float

Source-audio position, negative while consuming an initial delay.

offset_frames property

offset_frames: int

Sample-frame position, negative while consuming an initial delay.

info property

info: SoundInfo

Format and length information for the source audio.

path property

path: Path

Resolved source path for file-backed audio.

In-memory PCM audio has no source path, so querying this property for such a sound raises AudioError.

Raises:

Type	Description
AudioError	This sound was created from in-memory PCM rather than a file.

duration_seconds property

duration_seconds: float

Duration of the source audio, unaffected by pitch.

frame_count property

frame_count: int

Number of sample frames in the source audio.

channels property

channels: int

Number of interleaved audio channels.

sample_rate property

sample_rate: int

Number of sample frames per second.

sample_type property

sample_type: SampleType

PCM representation used by each channel sample.

remaining_seconds property

remaining_seconds: float

Source-audio seconds remaining in the current pass.

remaining_frames property

remaining_frames: int

Sample frames remaining in the current pass.

progress property

progress: float

Current playhead position as a value from 0.0 through 1.0.

config property

config: VoiceConfig

Current complete voice configuration.

position property writable

position: Vector3

Sound location in 3D space.

velocity property writable

velocity: Vector3

Sound velocity used for Doppler shift.

direction property writable

direction: Vector3

Direction the sound's attenuation cone points.

gain property writable

gain: float

Linear pre-attenuation amplitude multiplier.

pitch property writable

pitch: float

Playback-rate and pitch multiplier.

looping property writable

looping: bool

Whether the complete sound repeats after reaching its end.

relative property writable

relative: bool

Whether coordinates are relative to the listener.

min_gain property writable

min_gain: float

Lower clamp applied after distance and cone attenuation.

max_gain property writable

max_gain: float

Upper clamp applied after distance and cone attenuation.

reference_distance property writable

reference_distance: float

Reference point where distance attenuation has unity gain.

max_distance property writable

max_distance: float

Distance used as the outer bound by clamped distance models.

rolloff_factor property writable

rolloff_factor: float

Multiplier controlling how rapidly distance attenuation changes.

cone_inner_angle property writable

cone_inner_angle: float

Full angle in which a directional sound is unattenuated.

cone_outer_angle property writable

cone_outer_angle: float

Full angle beyond which cone_outer_gain is applied.

cone_outer_gain property writable

cone_outer_gain: float

Gain applied outside a directional sound's outer cone.

cone_outer_gain_high_frequency property writable

cone_outer_gain_high_frequency: float

High-frequency gain outside a directional sound's outer cone.

distance_model property writable

distance_model: DistanceModel | None

Per-source distance model, or None to inherit the context.

radius property writable

radius: float

Physical source radius in world units.

spatialization property writable

spatialization: SpatializationMode

Automatic, forced, or disabled spatial processing.

direct_channels property writable

direct_channels: DirectChannelsMode

Direct stereo-channel routing behavior.

stereo_angles property writable

stereo_angles: tuple[float, float] | None

Left and right virtual-speaker angles in radians.

resampler property writable

resampler: Resampler | None

Implementation-provided source resampler override.

air_absorption_factor property writable

air_absorption_factor: float

Distance-based high-frequency absorption strength.

room_rolloff_factor property writable

room_rolloff_factor: float

Distance rolloff applied to auxiliary effect paths.

direct_filter_gain_high_frequency_auto property writable

direct_filter_gain_high_frequency_auto: bool

Whether direct high-frequency filtering follows source attenuation.

auxiliary_send_filter_gain_auto property writable

auxiliary_send_filter_gain_auto: bool

Whether auxiliary-send gain follows source attenuation.

auxiliary_send_filter_gain_high_frequency_auto property writable

auxiliary_send_filter_gain_high_frequency_auto: bool

Whether wet high-frequency filtering follows source attenuation.

stereo_mode property writable

stereo_mode: StereoMode

Normal stereo or UHJ Super Stereo processing.

super_stereo_width property writable

super_stereo_width: float | None

Super Stereo soundfield width, or its implementation default.

filter property writable

filter: Filter | None

Direct EFX filter applied to the sound's dry signal.

effect_sends property writable

effect_sends: tuple[EffectSend, ...]

Ordered auxiliary EFX routes applied to this sound.

pause

pause() -> None

Pause the sound if it is currently playing.

Calling this when the sound is not currently playing is harmless.

resume

resume() -> None

Resume the sound if it is paused.

Raises:

Type	Description
InvalidVoiceStateError	The sound is not paused.

stop

stop() -> None

Stop the sound and release its playback voice.

Calling this for a terminal sound is harmless. The handle retains its status with an end reason of SoundEndReason.STOPPED.

wait

wait(
    timeout: float | None = None,
    *,
    poll_interval: float = 0.01,
) -> bool

Block until this sound ends, or a timeout expires.

Parameters:

Name	Type	Description	Default
timeout	float | None	Maximum wall-clock seconds to wait, or None for no limit.	None
poll_interval	float	Positive wall-clock seconds between status queries.	0.01

Returns:

Type	Description
bool	True when the sound is terminal, or False when the timeout
bool	expires first.

seek

seek(offset_seconds: float) -> None

Move the playhead to an offset in source-audio seconds.

Seeking a terminal sound creates a new voice in the initial state but does not start playback.

Parameters:

Name	Type	Description	Default
offset_seconds	float	Finite offset greater than or equal to zero and strictly less than the source duration.	required

Raises:

Type	Description
TypeError	offset_seconds is not numeric.
ValueError	offset_seconds is non-finite or outside the source.
InvalidVoiceStateError	The convenience runtime has been shut down.

seek_frames

seek_frames(offset_frames: int) -> None

Move the playhead to an exact sample-frame offset.

Seeking a terminal sound creates a new voice in the initial state.

Parameters:

Name	Type	Description	Default
offset_frames	int	Integer frame index greater than or equal to zero and strictly less than frame_count.	required

Raises:

Type	Description
TypeError	offset_frames is not an integer.
ValueError	offset_frames is outside the source.
InvalidVoiceStateError	The convenience runtime has been shut down.

rewind

rewind() -> None

Move the playhead to the beginning and enter the initial state.

A terminal sound receives a new voice but does not begin playing.

Raises:

Type	Description
InvalidVoiceStateError	The convenience runtime has been shut down.

restart

restart(
    *,
    delay_seconds: float = 0.0,
    delay_frames: int | None = None,
    start_time_ns: int | None = None,
) -> None

Start the sound again from its beginning, optionally with timing.

A terminal sound receives a new voice and becomes active again.

Parameters:

Name	Type	Description	Default
delay_seconds	float	Initial silence in source-audio seconds. Pitch and Doppler affect its real-time duration.	0.0
delay_frames	int | None	Exact number of silent sample frames. When provided, delay_seconds must remain 0.0.	None
start_time_ns	int | None	Absolute audio-device clock time in nanoseconds. None starts as soon as possible.	None

Raises:

Type	Description
TypeError	A timing argument has the wrong type.
ValueError	A delay or device-clock time is invalid.
InvalidVoiceStateError	The convenience runtime has been shut down.
AudioBackendError	OpenAL cannot restart the sound or the requested timing feature is unavailable.

set_config

set_config(config: VoiceConfig) -> None

Apply a complete immutable voice configuration.

For a terminal sound, the configuration is stored for a later restart.

Parameters:

Name	Type	Description	Default
config	VoiceConfig	Complete replacement configuration.	required

Raises:

Type	Description
TypeError	config is not a VoiceConfig.
InvalidVoiceStateError	The runtime was shut down while this sound was active.
AudioBackendError	OpenAL cannot apply the configuration or EFX.

update

update(
    *,
    position: Vector3 | None = None,
    velocity: Vector3 | None = None,
    direction: Vector3 | None = None,
    gain: float | None = None,
    pitch: float | None = None,
    looping: bool | None = None,
    relative: bool | None = None,
    min_gain: float | None = None,
    max_gain: float | None = None,
    reference_distance: float | None = None,
    max_distance: float | None = None,
    rolloff_factor: float | None = None,
    cone_inner_angle: float | None = None,
    cone_outer_angle: float | None = None,
    cone_outer_gain: float | None = None,
    cone_outer_gain_high_frequency: float | None = None,
    distance_model: DistanceModel
    | None = _OMITTED_DISTANCE_MODEL,
    radius: float | None = None,
    spatialization: SpatializationMode | None = None,
    direct_channels: DirectChannelsMode
    | bool
    | None = None,
    stereo_angles: tuple[float, float]
    | None = _OMITTED_STEREO_ANGLES,
    resampler: Resampler | None = _OMITTED_RESAMPLER,
    air_absorption_factor: float | None = None,
    room_rolloff_factor: float | None = None,
    direct_filter_gain_high_frequency_auto: bool
    | None = None,
    auxiliary_send_filter_gain_auto: bool | None = None,
    auxiliary_send_filter_gain_high_frequency_auto: bool
    | None = None,
    stereo_mode: StereoMode | None = None,
    super_stereo_width: float
    | None = _OMITTED_SUPER_STEREO_WIDTH,
    filter: Filter | None = _OMITTED_FILTER,
    effect_sends: tuple[EffectSend, ...]
    | list[EffectSend]
    | None = None,
) -> None

Validate and apply a batch of source-control changes.

None leaves most fields unchanged. filter is the exception: passing None removes the direct filter, while omitting it leaves the filter unchanged. Pass an empty effect_sends sequence to remove all auxiliary routes. Changes are stored for later restart when the sound is terminal.

Parameters:

Name	Type	Description	Default
position	Vector3 | None	New 3D position.	None
velocity	Vector3 | None	New velocity used for Doppler shift.	None
direction	Vector3 | None	New attenuation-cone direction.	None
gain	float | None	New non-negative linear gain.	None
pitch	float | None	New playback-rate multiplier from 0.5 through 2.0.	None
looping	bool | None	Whether the source repeats.	None
relative	bool | None	Whether coordinates are listener-relative.	None
min_gain	float | None	New lower gain clamp.	None
max_gain	float | None	New upper gain clamp.	None
reference_distance	float | None	New distance with unity attenuation.	None
max_distance	float | None	New outer distance for clamped models.	None
rolloff_factor	float | None	New distance-attenuation multiplier.	None
cone_inner_angle	float | None	New full inner cone angle in degrees.	None
cone_outer_angle	float | None	New full outer cone angle in degrees.	None
cone_outer_gain	float | None	New gain outside the outer cone.	None
distance_model	DistanceModel | None	New per-source distance model, or None to inherit the context model.	_OMITTED_DISTANCE_MODEL
radius	float | None	New physical source radius.	None
spatialization	SpatializationMode | None	New spatial processing mode.	None
direct_channels	DirectChannelsMode | bool | None	New direct stereo-channel routing mode.	None
stereo_angles	tuple[float, float] | None	New virtual-speaker angles, or None to restore the implementation defaults.	_OMITTED_STEREO_ANGLES
resampler	Resampler | None	New source resampler, or None for the implementation default.	_OMITTED_RESAMPLER
air_absorption_factor	float | None	New distance-based air absorption factor.	None
room_rolloff_factor	float | None	New auxiliary-path distance rolloff factor.	None
stereo_mode	StereoMode | None	New normal or UHJ Super Stereo processing mode.	None
super_stereo_width	float | None	New Super Stereo width, or None for the implementation default.	_OMITTED_SUPER_STEREO_WIDTH
filter	Filter | None	Replacement direct EFX filter, or None to remove it.	_OMITTED_FILTER
effect_sends	tuple[EffectSend, ...] | list[EffectSend] | None	Replacement auxiliary routes; an empty sequence removes them all.	None

Raises:

Type	Description
TypeError	A value has the wrong type.
ValueError	A value is non-finite or outside its supported range.
InvalidVoiceStateError	The runtime was shut down while this sound was active.
AudioBackendError	OpenAL cannot apply the configuration or EFX.

pyalsoft.PitchShifter dataclass

Bases: _EffectConfig

Pitch shift in semitones and cents.

Attributes:

Name	Type	Description
coarse_tuning	int	Shift from -12 through 12 semitones.
fine_tuning	int	Additional shift from -50 through 50 cents.

pyalsoft.Recording

Opaque handle for an in-memory recording in progress.

Do not construct instances directly. Pass the value returned by start_recording to stop_recording. The collector owns a background thread and capture device until it is stopped. Captured bytes accumulate in memory without a size limit.

pyalsoft.ResourceInUseError

Bases: AudioError

Raised when a resource is still referenced by another live resource.

pyalsoft.Resampler dataclass

One implementation-provided source resampler.

Values are returned by list_resamplers. Applications should select from that result rather than constructing values.

pyalsoft.Reverb dataclass

Bases: _EffectConfig

Standard EFX reverb with OpenAL's ranges and defaults.

Attach the immutable value through EffectSend. Gain values are linear. Times are measured in seconds.

Attributes:

Name	Type	Description
density	float	Modal density, from 0.0 through 1.0.
diffusion	float	Echo density, from 0.0 through 1.0.
gain	float	Overall wet-signal gain, from 0.0 through 1.0.
high_frequency_gain	float	High-frequency wet gain, from 0.0 through 1.0.
decay_time	float	Decay time, from 0.1 through 20.0 seconds.
high_frequency_decay_ratio	float	High-to-low-frequency decay ratio, from 0.1 through 2.0.
reflections_gain	float	Early-reflections gain, from 0.0 through 3.16.
reflections_delay	float	Early-reflections delay, from 0.0 through 0.3 seconds.
late_reverb_gain	float	Late-reverberation gain, from 0.0 through 10.0.
late_reverb_delay	float	Late-reverberation delay, from 0.0 through 0.1 seconds.
air_absorption_high_frequency_gain	float	Per-meter high-frequency air absorption gain, from 0.892 through 1.0.
room_rolloff_factor	float	Distance-based room attenuation, from 0.0 through 10.0.
high_frequency_decay_limit	bool	Whether air absorption limits high-frequency decay time.

pyalsoft.RingModulator dataclass

Bases: _EffectConfig

Ring modulation with a selectable carrier waveform.

Attributes:

Name	Type	Description
frequency	float	Carrier frequency, from 0 through 8000 Hz.
high_pass_cutoff	float	High-pass cutoff, from 0 through 24000 Hz.
waveform	RingModulatorWaveform	Sinusoid, sawtooth, or square carrier waveform.

pyalsoft.RingModulatorWaveform

Bases: Enum

Carrier waveform used by a ring modulator.

pyalsoft.SampleType

Bases: Enum

PCM sample representations supported by the managed API.

Attributes:

Name	Type	Description
UINT8		Unsigned 8-bit samples, with silence at 128.
INT16		Signed 16-bit samples, with silence at 0.
FLOAT32		32-bit IEEE 754 floating-point samples.
FLOAT64		64-bit IEEE 754 floating-point samples.

byte_width property

byte_width: int

Number of bytes used by one channel sample.

pyalsoft.SoundCacheInfo dataclass

Observed state of the implicit file-clip cache.

Attributes:

Name	Type	Description
max_bytes	int | None	Configured byte budget, or None when unlimited.
current_bytes	int	Bytes occupied by all cached clips, including pinned ones.
clip_count	int	Number of cached file clips.
active_clip_count	int	Number of cached clips pinned by active sounds.
pending_eviction_count	int	Pinned clips marked for eviction after playback.

pyalsoft.SoundEndReason

Bases: Enum

Why a convenience playback handle entered its terminal state.

Attributes:

Name	Type	Description
FINISHED		Playback reached the end of the source naturally.
STOPPED		The sound was stopped explicitly.
SHUTDOWN		The convenience runtime was shut down while the sound was active.
DEVICE_LOST		The backend reported that the playback device disconnected.

pyalsoft.SoundInfo dataclass

Format and length information for immutable PCM audio.

Attributes:

Name	Type	Description
channels	int	Number of interleaved channels in a standard mono, stereo, quad, 5.1, 6.1, or 7.1 layout.
sample_rate	int	Number of sample frames per second.
sample_type	SampleType	Representation used by each channel sample.
frame_count	int	Number of interleaved sample frames; always positive.
duration_seconds	float	Duration on the source-audio timeline.
sample_width_bytes	int	Number of bytes used by one channel sample.
bit_depth	int	Number of bits used by one channel sample.
frame_width_bytes	int	Number of bytes used by one interleaved frame.
byte_count	int	Total number of sample bytes.

Raises:

Type	Description
TypeError	A constructor argument has the wrong type.
ValueError	The channel count, sample rate, or frame count is unsupported.

duration_seconds property

duration_seconds: float

Duration in source-audio seconds.

sample_width_bytes property

sample_width_bytes: int

Number of bytes used by one channel sample.

bit_depth property

bit_depth: int

Number of bits used by one channel sample.

frame_width_bytes property

frame_width_bytes: int

Number of bytes used by one interleaved sample frame.

byte_count property

byte_count: int

Total number of PCM data bytes.

pyalsoft.Stream dataclass

Opaque identity for one managed streaming source.

Do not construct instances directly. A stream belongs to the Playback that returned it and remains valid until it is released or its session is closed.

pyalsoft.StreamState

Bases: Enum

Managed lifecycle state of a stream.

Attributes:

Name	Type	Description
INITIAL		Created but not yet started.
PLAYING		Started and logically playing, including during an underrun.
PAUSED		Explicitly paused.
FINISHED		End-of-input was declared and all queued audio drained.
STOPPED		Explicitly stopped; queued audio was discarded.

pyalsoft.StreamStatus dataclass

Runtime state and queue accounting for a stream.

Attributes:

Name	Type	Description
state	StreamState	Current managed lifecycle state.
input_finished	bool	Whether end-of-input has been declared.
queued_chunks	int	Chunks queued for playback, including the active chunk.
queued_seconds	float	Approximate source-audio duration remaining in the queue.
underrun_count	int	Number of distinct times a playing stream exhausted its queue before end-of-input.

pyalsoft.SpatializationMode

Bases: Enum

Per-source spatialization behavior.

AUTO follows the source format, ENABLED forces positional processing, and DISABLED bypasses position, distance, cone, and Doppler processing.

pyalsoft.StereoMode

Bases: Enum

Processing mode for ordinary stereo source data.

pyalsoft.VocalMorpher dataclass

Bases: _EffectConfig

Blend between two selected phonemes.

Attributes:

Name	Type	Description
phoneme_a	VocalMorpherPhoneme	First phoneme.
phoneme_a_coarse_tuning	int	First tuning, from -24 through 24 semitones.
phoneme_b	VocalMorpherPhoneme	Second phoneme.
phoneme_b_coarse_tuning	int	Second tuning, from -24 through 24 semitones.
waveform	VocalMorpherWaveform	Waveform used to blend the phonemes.
rate	float	Morphing frequency, from 0.0 through 10.0 Hz.

pyalsoft.VocalMorpherPhoneme

Bases: Enum

Phoneme selected for one side of a vocal-morpher transition.

pyalsoft.VocalMorpherWaveform

Bases: Enum

Waveform used to blend vocal-morpher phonemes.

pyalsoft.Voice dataclass

Opaque identity for one playback instance of a clip.

Do not construct instances directly. A voice belongs to the Playback that returned it and remains valid until it is released or its session is closed.

pyalsoft.VoiceClock dataclass

Atomically measured source position and audio-device clock time.

offset_frames_fixed preserves OpenAL's exact signed 32.32 fixed-point sample offset. The device time remains an integer nanosecond count.

offset_frames property

offset_frames: float

Source position in sample frames, including the fractional frame.

offset_seconds property

offset_seconds: float

Source position in source-audio seconds.

device_time_seconds property

device_time_seconds: float

Audio-device clock time in seconds.

pyalsoft.VoiceConfig dataclass

Complete immutable configuration for a voice or stream.

Mono audio is normally required for positional controls to have an audible effect. Gain values are linear amplitude multipliers; pitch changes playback rate and pitch together. Streaming voices reject looping=True.

Attributes:

Name	Type	Description
position	Vector3	Sound position in world or listener-relative coordinates.
velocity	Vector3	Sound velocity used for Doppler shift.
direction	Vector3	Direction of the attenuation cone; the zero vector is omnidirectional.
gain	float	Non-negative pre-attenuation linear gain.
pitch	float	Playback-rate multiplier from 0.5 through 2.0.
looping	bool	Whether static audio repeats after reaching its end.
relative	bool	Whether coordinates are relative to the listener.
min_gain	float	Lower post-attenuation gain clamp, from 0.0 through 1.0.
max_gain	float	Upper post-attenuation gain clamp, from 0.0 through 1.0 and not less than min_gain.
reference_distance	float	Non-negative distance at which attenuation has unity gain.
max_distance	float	Non-negative outer bound used by clamped distance models.
rolloff_factor	float	Non-negative multiplier for distance attenuation.
cone_inner_angle	float	Full unattenuated cone angle in degrees, from 0 to 360.
cone_outer_angle	float	Full outer cone angle in degrees, from 0 to 360.
cone_outer_gain	float	Linear gain outside the outer cone, from 0.0 through 1.0.
cone_outer_gain_high_frequency	float	High-frequency gain outside the outer cone, from 0.0 through 1.0.
distance_model	DistanceModel | None	Optional per-source distance model. None inherits the playback context's model.
radius	float	Non-negative physical source radius in world units.
spatialization	SpatializationMode	Whether spatial processing is automatic, forced, or off.
direct_channels	DirectChannelsMode	Direct stereo channel routing behavior.
stereo_angles	tuple[float, float] | None	Optional left and right virtual-speaker angles in radians.
resampler	Resampler | None	Optional implementation-provided source resampler.
air_absorption_factor	float	Distance-based high-frequency absorption strength.
room_rolloff_factor	float	Distance rolloff applied to auxiliary effect paths.
direct_filter_gain_high_frequency_auto	bool	Whether direct-path high-frequency filtering follows source gain and distance.
auxiliary_send_filter_gain_auto	bool	Whether auxiliary-send gain follows source gain and distance.
auxiliary_send_filter_gain_high_frequency_auto	bool	Whether auxiliary-send high-frequency filtering follows source gain and distance.
stereo_mode	StereoMode	Normal stereo or UHJ Super Stereo processing.
super_stereo_width	float | None	Optional Super Stereo soundfield width.
filter	Filter | None	Optional EFX filter applied directly to the dry signal.
effect_sends	tuple[EffectSend, ...]	Ordered auxiliary EFX routes applied to the wet signal.

Raises:

Type	Description
TypeError	A field has the wrong type.
ValueError	A numeric field is non-finite or outside its supported range.

pyalsoft.VoiceLatency dataclass

Atomically measured source position and physical-output latency.

offset_frames_fixed preserves OpenAL's exact unsigned 32.32 fixed-point sample offset. The convenience properties convert it to a floating-point frame count or source-audio seconds only when requested.

offset_frames property

offset_frames: float

Source position in sample frames, including the fractional frame.

offset_seconds property

offset_seconds: float

Source position in source-audio seconds.

output_latency_seconds property

output_latency_seconds: float

Physical-output latency in seconds.

pyalsoft.VoiceState

Bases: Enum

Observed playback state of a static voice.

Attributes:

Name	Type	Description
INITIAL		Ready to play from the beginning.
PLAYING		Playing, including while waiting for a scheduled start time.
PAUSED		Paused at the current playhead position.
STOPPED		Finished naturally or explicitly stopped.

pyalsoft.VoiceStatus dataclass

Runtime state observed from a static voice.

Attributes:

Name	Type	Description
state	VoiceState	Current OpenAL playback state.
offset_seconds	float	Current playhead position in source-audio seconds. This is negative while consuming an initial playback delay.
offset_frames	int	Current playhead position as an exact sample-frame index. This is negative while consuming an initial playback delay.

pyalsoft.clear_sound_cache

clear_sound_cache(path: AudioPath | None = None) -> int

Evict file clips from the convenience runtime's cache.

Clips attached to active sounds are marked for later eviction and are not included in the returned count. In-memory PCM passed to play is never part of this cache.

Parameters:

Name	Type	Description	Default
path	AudioPath | None	Specific audio-file path to evict. None targets every cached file.	None

Returns:

Type	Description
int	Number of clips evicted immediately.

Raises:

Type	Description
TypeError	path is neither path-like nor None.

pyalsoft.close_playback

close_playback(playback: Playback) -> None

Release every resource and close a playback session.

Closing an already closed session is harmless. All clips, voices, streams, and effect buses owned by the session become invalid, even when cleanup reports an error.

Parameters:

Name	Type	Description	Default
playback	Playback	Session to close.	required

Raises:

Type	Description
TypeError	playback is not a Playback.
AudioBackendError	OpenAL reports a resource or context cleanup failure.

pyalsoft.create_effect_bus

create_effect_bus(
    playback: Playback, config: EffectBusConfig
) -> EffectBus

Create a reusable auxiliary effect bus owned by playback.

pyalsoft.defer_updates

defer_updates(
    playback: Playback | None = None,
) -> Iterator[None]

Batch playback changes and make them audible together.

Pass an explicit session, or omit playback to use the convenience runtime. Audio continues rendering with its previous state inside the block; pending listener, source, effect, play, and pause changes are committed when the outermost block exits. Nested blocks are supported.

Parameters:

Name	Type	Description	Default
playback	Playback | None	Explicit session to update. None selects the convenience runtime and opens it if necessary.	None

Raises:

Type	Description
TypeError	playback is neither a Playback nor None.
PlaybackClosedError	The explicit session is closed.
PlaybackOpenError	The convenience runtime cannot open an audio session.
AudioBackendError	The backend lacks AL_SOFT_deferred_updates or cannot begin or commit the update batch.

pyalsoft.finish_stream

finish_stream(playback: Playback, stream: Stream) -> None

Declare end-of-input and allow already queued chunks to drain.

Calling this again after end-of-input is harmless. Continue calling update_stream until it reports FINISHED. If no chunks remain, the stream becomes finished immediately.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Live stream that will receive no more chunks.	required

Raises:

Type	Description
InvalidHandleError	stream is released or belongs to another session.
InvalidVoiceStateError	stream was explicitly stopped.
PlaybackClosedError	playback is closed.

pyalsoft.get_acoustics

get_acoustics(
    playback: Playback | None = None,
) -> Acoustics

Return acoustics for an explicit session or the convenience runtime.

Parameters:

Name	Type	Description	Default
playback	Playback | None	Explicit session to query. None returns the convenience runtime's current state without opening an audio device.	None

Returns:

Type	Description
Acoustics	Complete current acoustic settings.

Raises:

Type	Description
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot return valid acoustic settings.

pyalsoft.get_capture_stream_status

get_capture_stream_status(
    stream: CaptureStream,
) -> CaptureStreamStatus

Return bounded-buffer usage, loss accounting, and lifecycle state.

Raises:

Type	Description
TypeError	stream is not a CaptureStream.

pyalsoft.get_effect_bus_config

get_effect_bus_config(
    playback: Playback, bus: EffectBus
) -> EffectBusConfig

Return the current immutable configuration of a live effect bus.

pyalsoft.get_listener

get_listener(playback: Playback | None = None) -> Listener

Return the listener for an explicit session or the convenience runtime.

Parameters:

Name	Type	Description	Default
playback	Playback | None	Explicit session to query. None returns the convenience runtime's current state without opening an audio device.	None

Returns:

Type	Description
Listener	Complete current listener state.

Raises:

Type	Description
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot return a valid listener state.

pyalsoft.get_playback_config

get_playback_config(playback: Playback) -> PlaybackConfig

Return the configuration currently requested by a playback session.

This reports the request retained for future patch-style calls to reconfigure_playback. Use get_playback_info to inspect the effective values negotiated by the backend.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session to inspect.	required

Returns:

Type	Description
PlaybackConfig	The session's immutable requested configuration.

Raises:

Type	Description
PlaybackClosedError	playback is closed.

pyalsoft.get_playback_info

get_playback_info(playback: Playback) -> PlaybackInfo

Return observed device, context, renderer, and HRTF information.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session to query.	required

Returns:

Type	Description
PlaybackInfo	Properties reported by the active backend.

Raises:

Type	Description
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL rejects the query or returns incomplete data.

pyalsoft.is_playback_connected

is_playback_connected(playback: Playback) -> bool | None

Report connection state, or None when the backend cannot report it.

Raises:

Type	Description
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL rejects the connection query.

pyalsoft.get_playback_clock

get_playback_clock(playback: Playback) -> PlaybackClock

Atomically query the audio-device clock and physical-output latency.

pyalsoft.get_sound_cache_info

get_sound_cache_info() -> SoundCacheInfo

Return byte usage and activity for the convenience file cache.

Querying cache state also reaps sounds that have completed and performs any deferred or budget-driven evictions.

Returns:

Type	Description
SoundCacheInfo	Current budget, byte use, clip counts, and pending-eviction count.

pyalsoft.get_sound_info

get_sound_info(path: AudioPath) -> SoundInfo

Read decoded format and length information without opening a device.

The returned sample type and bit depth describe the decoded PCM that PyALSoft will upload, rather than a compressed bitrate.

Parameters:

Name	Type	Description	Default
path	AudioPath	Path to a supported WAV, FLAC, MP3, or Ogg Vorbis file.	required

Returns:

Type	Description
SoundInfo	Decoded channel layout, sample rate, sample type, and frame count.

Raises:

Type	Description
TypeError	path is not string or path-like.
AudioFileError	The file cannot be read, decoded, or represented by the supported static-audio layouts.

pyalsoft.load_audio

load_audio(path: AudioPath) -> PCM

Decode a supported static audio file into immutable PCM audio.

WAV, FLAC, MP3, and Ogg Vorbis files are detected from their contents and decoded completely in memory. This function performs no playback-device work. Source sample rates are retained.

Parameters:

Name	Type	Description	Default
path	AudioPath	Path to a supported audio file.	required

Returns:

Type	Description
PCM	Complete decoded PCM audio.

Raises:

Type	Description
TypeError	path is not string or path-like.
AudioFileError	The file cannot be read, decoded, or represented by the supported static-audio layouts.

pyalsoft.get_voice_status

get_voice_status(
    playback: Playback, voice: Voice
) -> VoiceStatus

Return the current state and playback offset of a live static voice.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice	Live static voice to query.	required

Returns:

Type	Description
VoiceStatus	The observed OpenAL state and source-timeline offsets.

Raises:

Type	Description
InvalidHandleError	voice is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL returns an unknown state or rejects the query.

pyalsoft.get_voice_clock

get_voice_clock(
    playback: Playback, voice: Voice | Stream
) -> VoiceClock

Atomically query a source offset and the audio-device clock.

pyalsoft.get_voice_config

get_voice_config(
    playback: Playback, voice: Voice | Stream
) -> VoiceConfig

Return the complete managed configuration for a live voice or stream.

The returned VoiceConfig is immutable and reflects the most recent managed configuration applied to the source.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Live static voice or stream to inspect.	required

Raises:

Type	Description
InvalidHandleError	The handle is released or belongs to another session.
PlaybackClosedError	playback is closed.

pyalsoft.get_voice_latency

get_voice_latency(
    playback: Playback, voice: Voice | Stream
) -> VoiceLatency

Atomically query a source offset and its physical-output latency.

pyalsoft.list_capture_devices

list_capture_devices(
    *, library: OpenALLibrary | None = None
) -> tuple[CaptureDevice, ...]

Return capture devices known to the selected OpenAL runtime.

Parameters:

Name	Type	Description	Default
library	OpenALLibrary | None	Loaded low-level library to query. By default, discover and load the platform's OpenAL implementation.	None

Returns:

Type	Description
CaptureDevice	Devices in runtime order, with duplicate names removed. The tuple may be
...	empty when the runtime reports no capture devices.

Raises:

Type	Description
CaptureOpenError	No OpenAL implementation could be loaded.
AudioBackendError	Device enumeration failed.

pyalsoft.list_hrtf_profiles

list_hrtf_profiles(
    device_name: PlaybackDevice | str | bytes | None = None,
    *,
    library: OpenALLibrary | None = None,
) -> tuple[str, ...]

Return HRTF profile names available to a playback device.

The device is opened only for enumeration and is closed before this function returns. An empty tuple means the selected device does not expose ALC_SOFT_HRTF or currently reports no profiles.

Parameters:

Name	Type	Description	Default
device_name	PlaybackDevice | str | bytes | None	Playback device object or device specifier. None selects the runtime's default playback device.	None
library	OpenALLibrary | None	Loaded low-level library to query. By default, discover and load the platform's OpenAL implementation.	None

Raises:

Type	Description
TypeError	device_name has the wrong type.
PlaybackOpenError	OpenAL could not be loaded or the device could not open.
AudioBackendError	Profile enumeration or device cleanup failed.

pyalsoft.list_playback_devices

list_playback_devices(
    *, library: OpenALLibrary | None = None
) -> tuple[PlaybackDevice, ...]

Return playback devices known to the selected OpenAL runtime.

Parameters:

Name	Type	Description	Default
library	OpenALLibrary | None	Loaded low-level library to query. By default, discover and load the platform's OpenAL implementation.	None

Returns:

Type	Description
PlaybackDevice	Devices in runtime order, with duplicate names removed. The tuple may be
...	empty when the runtime reports no playback devices.

Raises:

Type	Description
PlaybackOpenError	No OpenAL implementation could be loaded.
AudioBackendError	Device enumeration failed.

pyalsoft.list_resamplers

list_resamplers(
    playback: Playback,
) -> tuple[Resampler, ...]

Return the source resamplers provided by the active OpenAL implementation.

pyalsoft.open_playback

open_playback(
    device_name: PlaybackDevice | str | bytes | None = None,
    *,
    config: PlaybackConfig = _DEFAULT_PLAYBACK_CONFIG,
    library: OpenALLibrary | None = None,
) -> Playback

Open a managed playback session and make its context current.

The session restores the previously current context when it closes. Prefer a with statement so native resources are released deterministically.

Parameters:

Name	Type	Description	Default
device_name	PlaybackDevice | str | bytes | None	Playback device object or device specifier. None selects the runtime's default playback device. A bytes value is passed to OpenAL unchanged.	None
config	PlaybackConfig	Context-creation preferences such as HRTF.	_DEFAULT_PLAYBACK_CONFIG
library	OpenALLibrary | None	Loaded low-level library to use. By default, discover and load the platform's OpenAL implementation.	None

Returns:

Type	Description
Playback	A new, open playback session.

Raises:

Type	Description
TypeError	A device or configuration argument has the wrong type.
PlaybackOpenError	OpenAL could not be loaded or the device, context, or context activation could not be created.

pyalsoft.open_offline_playback

open_offline_playback(
    config: RenderConfig = _DEFAULT_RENDER_CONFIG,
    *,
    library: OpenALLibrary | None = None,
) -> OfflinePlayback

Open a managed playback session for deterministic offline rendering.

pyalsoft.open_stream

open_stream(
    playback: Playback,
    *,
    channels: int | None = None,
    sample_rate: int,
    sample_type: SampleType | None = None,
    format: BufferFormat | None = None,
    buffer_count: int = 4,
    block_alignment: int | None = None,
    ambisonic_order: int = 1,
    ambisonic_layout: AmbisonicLayout | None = None,
    ambisonic_scaling: AmbisonicScaling | None = None,
    config: VoiceConfig = _DEFAULT_VOICE_CONFIG,
) -> Stream

Create an unstarted source with a bounded pool of streaming buffers.

Queue at least one chunk with try_write_stream before calling start_stream. All chunks must use the format declared here. Streams cannot use VoiceConfig(looping=True).

Parameters:

Name	Type	Description	Default
playback	Playback	Open session that will own the stream.	required
channels	int | None	Interleaved channel count. Required for ordinary PCM and for WAVE or Vorbis data; otherwise inferred from format.	None
sample_rate	int	Positive number of sample frames per second.	required
sample_type	SampleType | None	PCM representation. Defaults to signed 16-bit when format is omitted and cannot be combined with format.	None
format	BufferFormat | None	Exact extension format, or None for ordinary PCM.	None
buffer_count	int	Positive maximum number of chunks that may be queued before backpressure is reported.	4
block_alignment	int | None	Optional compressed-format alignment in sample frames.	None
ambisonic_order	int	B-format ambisonic order from 1 through 14.	1
ambisonic_layout	AmbisonicLayout | None	Optional B-format channel ordering.	None
ambisonic_scaling	AmbisonicScaling | None	Optional B-format coefficient normalization.	None
config	VoiceConfig	Initial voice configuration. looping must be false.	_DEFAULT_VOICE_CONFIG

Returns:

Type	Description
Stream	An opaque stream in the StreamState.INITIAL state.

Raises:

Type	Description
TypeError	A format or configuration argument has the wrong type.
ValueError	The format or buffer count is invalid, or looping is enabled.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot allocate or configure stream resources.

pyalsoft.pause

pause(playback: Playback, voice: Voice | Stream) -> None

Pause a live voice or a logically playing stream.

Pausing a stream that is not currently playing is harmless. Static voices follow the underlying OpenAL pause semantics.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Live static voice or stream to pause.	required

Raises:

Type	Description
InvalidHandleError	The handle is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot pause the source.

pyalsoft.pause_playback_device

pause_playback_device(playback: Playback) -> None

Pause processing for a playback device without changing voice states.

pyalsoft.play

play(
    playback: Playback,
    clip: Clip,
    config: VoiceConfig | None = None,
    *,
    position: Vector3 | None = None,
    velocity: Vector3 | None = None,
    direction: Vector3 | None = None,
    gain: float | None = None,
    pitch: float | None = None,
    looping: bool | None = None,
    relative: bool | None = None,
    min_gain: float | None = None,
    max_gain: float | None = None,
    reference_distance: float | None = None,
    max_distance: float | None = None,
    rolloff_factor: float | None = None,
    cone_inner_angle: float | None = None,
    cone_outer_angle: float | None = None,
    cone_outer_gain: float | None = None,
    cone_outer_gain_high_frequency: float | None = None,
    distance_model: DistanceModel
    | None = _OMITTED_DISTANCE_MODEL,
    radius: float | None = None,
    spatialization: SpatializationMode | None = None,
    stereo_angles: tuple[float, float]
    | None = _OMITTED_STEREO_ANGLES,
    resampler: Resampler | None = _OMITTED_RESAMPLER,
    air_absorption_factor: float | None = None,
    room_rolloff_factor: float | None = None,
    direct_filter_gain_high_frequency_auto: bool
    | None = None,
    auxiliary_send_filter_gain_auto: bool | None = None,
    auxiliary_send_filter_gain_high_frequency_auto: bool
    | None = None,
    stereo_mode: StereoMode | None = None,
    super_stereo_width: float
    | None = _OMITTED_SUPER_STEREO_WIDTH,
    filter: Filter | None = None,
    effect_sends: tuple[EffectSend, ...]
    | list[EffectSend]
    | None = None,
    offset_seconds: float = 0.0,
    offset_frames: int | None = None,
    delay_seconds: float = 0.0,
    delay_frames: int | None = None,
    start_time_ns: int | None = None,
    spatialize: bool | None = None,
    direct_channels: DirectChannelsMode
    | bool
    | None = None,
) -> Voice

play(
    playback: AudioPath | PCM,
    /,
    *,
    config: VoiceConfig | None = None,
    position: Vector3 | None = None,
    velocity: Vector3 | None = None,
    direction: Vector3 | None = None,
    gain: float | None = None,
    pitch: float | None = None,
    looping: bool | None = None,
    relative: bool | None = None,
    min_gain: float | None = None,
    max_gain: float | None = None,
    reference_distance: float | None = None,
    max_distance: float | None = None,
    rolloff_factor: float | None = None,
    cone_inner_angle: float | None = None,
    cone_outer_angle: float | None = None,
    cone_outer_gain: float | None = None,
    cone_outer_gain_high_frequency: float | None = None,
    distance_model: DistanceModel
    | None = _OMITTED_DISTANCE_MODEL,
    radius: float | None = None,
    spatialization: SpatializationMode | None = None,
    stereo_angles: tuple[float, float]
    | None = _OMITTED_STEREO_ANGLES,
    resampler: Resampler | None = _OMITTED_RESAMPLER,
    air_absorption_factor: float | None = None,
    room_rolloff_factor: float | None = None,
    direct_filter_gain_high_frequency_auto: bool
    | None = None,
    auxiliary_send_filter_gain_auto: bool | None = None,
    auxiliary_send_filter_gain_high_frequency_auto: bool
    | None = None,
    stereo_mode: StereoMode | None = None,
    super_stereo_width: float
    | None = _OMITTED_SUPER_STEREO_WIDTH,
    filter: Filter | None = None,
    effect_sends: tuple[EffectSend, ...]
    | list[EffectSend]
    | None = None,
    offset_seconds: float = 0.0,
    offset_frames: int | None = None,
    delay_seconds: float = 0.0,
    delay_frames: int | None = None,
    start_time_ns: int | None = None,
    spatialize: bool | None = None,
    direct_channels: DirectChannelsMode
    | bool
    | None = None,
) -> PlayingSound

Play an explicit clip, supported audio file, or PCM value.

play(playback, clip, config) starts a clip owned by an explicit session. play(sound, config=config) starts asynchronous playback through the convenience runtime, where sound is a supported audio path or in-memory PCM value. The runtime keeps playing when the returned handle is discarded, and it caches file-backed clips by resolved path.

Individual control keywords override the corresponding field in config. filter=None explicitly removes a configured direct filter; omit filter to preserve the value from config. Use an empty effect_sends sequence to remove configured auxiliary routes. Pass spatialize=False for UI, player-attached, and other sounds that should ignore position, distance, Doppler, and directional cones. Pass direct_channels=True when the source must additionally bypass HRTF virtualization. Convenience playback duplicates mono frames into stereo; surround sources are rejected rather than implicitly downmixed, and explicit-session clips must already be stereo.

Parameters:

Name	Type	Description	Default
playback	Playback | AudioPath | PCM	Explicit playback session in the two-argument form; otherwise, a supported audio path or PCM value to play through the convenience runtime.	required
clip	Clip | None	Clip owned by playback. Valid only in the explicit-session form.	None
config	VoiceConfig | None	Base voice configuration. None uses all defaults.	None
position	Vector3 | None	Sound position in world or listener-relative coordinates.	None
velocity	Vector3 | None	Sound velocity used for Doppler shift.	None
direction	Vector3 | None	Attenuation-cone direction; the zero vector is omnidirectional.	None
gain	float | None	Non-negative pre-attenuation linear gain.	None
pitch	float | None	Playback-rate multiplier from 0.5 through 2.0.	None
looping	bool | None	Whether the complete source repeats.	None
relative	bool | None	Whether coordinates are relative to the listener.	None
min_gain	float | None	Lower post-attenuation gain clamp.	None
max_gain	float | None	Upper post-attenuation gain clamp.	None
reference_distance	float | None	Non-negative distance with unity attenuation.	None
max_distance	float | None	Non-negative outer distance for clamped distance models.	None
rolloff_factor	float | None	Non-negative distance-attenuation multiplier.	None
cone_inner_angle	float | None	Full inner cone angle in degrees, from 0 through 360.	None
cone_outer_angle	float | None	Full outer cone angle in degrees, from 0 through 360.	None
cone_outer_gain	float | None	Linear gain outside the outer cone.	None
distance_model	DistanceModel | None	Per-source attenuation formula, or None to inherit the playback context's model.	_OMITTED_DISTANCE_MODEL
radius	float | None	Non-negative physical source radius in world units.	None
spatialization	SpatializationMode | None	Automatic, forced, or disabled spatial processing.	None
stereo_angles	tuple[float, float] | None	Left and right virtual-speaker angles in radians, or None to restore the implementation defaults.	_OMITTED_STEREO_ANGLES
resampler	Resampler | None	Implementation-provided source resampler, or None for the implementation default.	_OMITTED_RESAMPLER
air_absorption_factor	float | None	Distance-based high-frequency absorption factor.	None
room_rolloff_factor	float | None	Distance rolloff for auxiliary effect paths.	None
stereo_mode	StereoMode | None	Normal stereo or UHJ Super Stereo processing.	None
super_stereo_width	float | None	Super Stereo width, or None for the implementation default.	_OMITTED_SUPER_STEREO_WIDTH
filter	Filter | None	Direct EFX filter, or None to remove the base filter.	_OMITTED_FILTER
effect_sends	tuple[EffectSend, ...] | list[EffectSend] | None	Ordered auxiliary EFX routes. An empty sequence removes all.	None
offset_seconds	float	Initial position in source-audio seconds. Must be non-negative and less than the source duration.	0.0
offset_frames	int | None	Exact initial sample-frame index. When provided, offset_seconds must remain 0.0.	None
delay_seconds	float	Initial silence in source-audio seconds. Pitch and Doppler affect its real-time duration. Cannot be combined with an initial offset.	0.0
delay_frames	int | None	Exact number of silent sample frames. When provided, delay_seconds must remain 0.0 and no initial offset may be set.	None
start_time_ns	int | None	Absolute audio-device clock time in nanoseconds. None starts as soon as possible. A past time also starts immediately.	None
spatialize	bool | None	True forces spatial rendering, False disables it, and None leaves the decision to OpenAL based on the source format.	None
direct_channels	DirectChannelsMode | bool | None	Direct stereo-channel routing mode. True selects DROP_UNMATCHED and False selects OFF. Mono file and PCM values are duplicated to stereo by convenience playback. Surround sources are rejected, and explicit clips must already be stereo.	None

Returns:

Type	Description
Voice | PlayingSound	A Voice owned by the explicit session, or a
Voice | PlayingSound	PlayingSound owned by the convenience runtime.

Raises:

Type	Description
TypeError	The call form or an argument has the wrong type.
ValueError	A configuration, initial offset, or playback timing is invalid.
AudioFileError	An audio file cannot be read or has an unsupported format.
PlaybackOpenError	The convenience runtime cannot open an audio session.
PlaybackClosedError	The explicit session is closed.
InvalidHandleError	clip is released or belongs to another session.
AudioBackendError	OpenAL cannot create, configure, or start the voice, or an explicit spatialization or direct-channel mode is requested without backend support.

pyalsoft.release

release(playback: Playback, resource: Clip) -> None

release(playback: Playback, resource: Voice) -> None

release(playback: Playback, resource: Stream) -> None

release(playback: Playback, resource: EffectBus) -> None

Release a clip, voice, stream, or effect bus before its session closes.

Releasing a voice stops it. Releasing a stream stops it and discards queued audio. A clip cannot be released while any live voice still refers to it. Every successful release permanently invalidates the handle.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns resource.	required
resource	Clip | Voice | Stream | EffectBus	Live clip, static voice, stream, or effect bus to release.	required

Raises:

Type	Description
TypeError	resource is not a supported handle.
InvalidHandleError	The handle is released or belongs to another session.
ResourceInUseError	resource is still referenced by another live managed resource.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot release the native resources.

pyalsoft.release_finished

release_finished(playback: Playback) -> int

Release all terminal voices and streams and return the count.

OpenAL reports both naturally completed and explicitly stopped voices as stopped. Streams are collected only after their managed state becomes FINISHED or STOPPED; this function never updates active streams.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session whose terminal resources should be released.	required

Returns:

Type	Description
int	Total number of released static voices and streams.

Raises:

Type	Description
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot query or release the resources.

pyalsoft.render_samples

render_samples(
    playback: OfflinePlayback, frame_count: int
) -> bytes

Render exactly frame_count output frames and return interleaved bytes.

pyalsoft.record

record(
    duration_seconds: float,
    device_name: CaptureDevice | str | bytes | None = None,
    *,
    channels: int = 1,
    sample_rate: int = 48000,
    sample_type: SampleType = INT16,
    library: OpenALLibrary | None = None,
) -> PCM

Record for a fixed duration and return the captured PCM audio.

This blocking convenience function is equivalent to starting a recording, waiting for the requested duration, and stopping it. Interrupting the wait still closes the capture device.

Parameters:

Name	Type	Description	Default
duration_seconds	float	Positive, finite wall-clock duration to record.	required
device_name	CaptureDevice | str | bytes | None	Capture device object or device specifier. None selects the runtime's default capture device.	None
channels	int	Number of interleaved channels in a standard mono, stereo, quad, 5.1, 6.1, or 7.1 layout.	1
sample_rate	int	Positive number of sample frames to capture per second.	48000
sample_type	SampleType	Representation used by each channel sample.	INT16
library	OpenALLibrary | None	Loaded low-level library to use. By default, discover and load the platform's OpenAL implementation.	None

Returns:

Type	Description
PCM	Captured frames as immutable, interleaved PCM.

Raises:

Type	Description
TypeError	A duration, format, or device argument has the wrong type.
ValueError	The duration or requested format is invalid.
CaptureOpenError	OpenAL could not be loaded or the device could not open.
AudioBackendError	Capture or cleanup failed, or the device returned no audio.

pyalsoft.read_capture_stream

read_capture_stream(
    stream: CaptureStream,
    max_frames: int | None = None,
    *,
    timeout: float | None = None,
) -> PCM | None

Read and consume available frames, waiting when the buffer is empty.

Parameters:

Name	Type	Description	Default
stream	CaptureStream	Live or closed bounded capture stream.	required
max_frames	int | None	Maximum frames to consume, or None for every frame that is currently buffered when the read completes.	None
timeout	float | None	Maximum wall-clock seconds to wait for a frame, or None for no limit.	None

Returns:

Type	Description
PCM | None	Captured PCM, or None after timeout or when a closed stream is empty.

Raises:

Type	Description
TypeError	A stream, frame count, or timeout has the wrong type.
ValueError	A frame count or timeout is invalid.
AudioBackendError	Background capture failed.

pyalsoft.reconfigure_playback

reconfigure_playback(
    playback: Playback,
    config: PlaybackConfig,
    *,
    replace: bool = False,
) -> None

Apply playback configuration changes to a live session.

None fields are omitted updates and preserve the session's previous request. Pass replace=True to instead treat config as the complete request, returning None fields to backend-selected behavior. The backend may negotiate different effective values, which can be inspected with get_playback_info. Existing clips, voices, and streams remain valid, although output may be interrupted briefly while the device resets.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session to reconfigure.	required
config	PlaybackConfig	Configuration changes to apply.	required
replace	bool	Replace the complete prior request instead of patching it.	False

Raises:

Type	Description
TypeError	config is not a PlaybackConfig or replace is not a boolean.
PlaybackClosedError	playback is closed.
AudioBackendError	Live reconfiguration is unavailable or OpenAL rejects the requested configuration.

pyalsoft.reopen_playback

reopen_playback(
    playback: Playback,
    device_name: PlaybackDevice | str | bytes | None = None,
) -> None

Move a live playback session to another output device.

Existing clips, voices, streams, and effect buses remain valid. The current playback configuration is retained, except that a named HRTF profile is cleared because profile identifiers and availability are device-specific. Pass None to move to the current default playback device, then use list_hrtf_profiles and reconfigure_playback to select a profile exposed by the new device.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session to migrate.	required
device_name	PlaybackDevice | str | bytes | None	Target output device or specifier. None selects the runtime's current default device.	None

Raises:

Type	Description
TypeError	device_name has the wrong type.
PlaybackClosedError	playback is closed.
AudioBackendError	Migration is unavailable or the backend rejects it.

pyalsoft.restart

restart(
    playback: Playback,
    voice: Voice,
    *,
    delay_seconds: float = 0.0,
    delay_frames: int | None = None,
    start_time_ns: int | None = None,
) -> None

Rewind a static voice and start it immediately or at a future time.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice	Live static voice to restart.	required
delay_seconds	float	Initial silence in source-audio seconds. Pitch and Doppler affect its real-time duration.	0.0
delay_frames	int | None	Exact number of silent sample frames. When provided, delay_seconds must remain 0.0.	None
start_time_ns	int | None	Absolute audio-device clock time in nanoseconds. None starts as soon as possible.	None

Raises:

Type	Description
TypeError	A timing argument has the wrong type.
ValueError	A delay or device-clock time is invalid.
InvalidHandleError	voice is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot rewind or play the voice, or the requested timing feature is unavailable.

pyalsoft.resume

resume(playback: Playback, voice: Voice | Stream) -> None

Resume a paused voice or stream.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Paused static voice or stream to resume.	required

Raises:

Type	Description
InvalidHandleError	The handle is released or belongs to another session.
InvalidVoiceStateError	voice is not paused.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot resume the source.

pyalsoft.resume_playback_device

resume_playback_device(playback: Playback) -> None

Resume processing for a playback device without changing voice states.

pyalsoft.rewind

rewind(playback: Playback, voice: Voice) -> None

Move a static voice to its beginning and set it to the initial state.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice	Live static voice to rewind.	required

Raises:

Type	Description
InvalidHandleError	voice is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot rewind the voice.

pyalsoft.seek

seek(
    playback: Playback, voice: Voice, offset_seconds: float
) -> None

Move a static voice's playhead to a source-audio time offset.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice	Live static voice to seek.	required
offset_seconds	float	Finite offset greater than or equal to zero and strictly less than the clip duration.	required

Raises:

Type	Description
TypeError	offset_seconds is not numeric or a handle has the wrong type.
ValueError	offset_seconds is non-finite or outside the clip.
InvalidHandleError	voice is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot move the playhead.

pyalsoft.seek_frames

seek_frames(
    playback: Playback, voice: Voice, offset_frames: int
) -> None

Move a static voice's playhead to an exact sample-frame offset.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice	Live static voice to seek.	required
offset_frames	int	Integer frame index greater than or equal to zero and strictly less than the clip's frame count.	required

Raises:

Type	Description
TypeError	offset_frames is not an integer or a handle has the wrong type.
ValueError	offset_frames is outside the clip.
InvalidHandleError	voice is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot move the playhead.

pyalsoft.set_acoustics

set_acoustics(
    playback: Playback, acoustics: Acoustics
) -> None

set_acoustics(acoustics: Acoustics) -> None

Set acoustics for an explicit session or the convenience runtime.

Call set_acoustics(acoustics) for the convenience runtime, or set_acoustics(playback, acoustics) for an explicit session. Setting the convenience state opens its playback session if necessary.

Parameters:

Name	Type	Description	Default
playback	Playback | Acoustics	Explicit session, or the acoustic settings when using the one-argument form.	required
acoustics	Acoustics | None	Complete acoustic settings for an explicit session.	None

Raises:

Type	Description
TypeError	The call form or acoustic settings are invalid.
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot apply the acoustic settings.

pyalsoft.set_listener

set_listener(
    playback: Playback, listener: Listener
) -> None

set_listener(listener: Listener) -> None

Set the listener for an explicit session or the convenience runtime.

Call set_listener(listener) for the convenience runtime, or set_listener(playback, listener) for an explicit session. Setting the convenience listener opens its playback session if necessary.

Parameters:

Name	Type	Description	Default
playback	Playback | Listener	Explicit session, or the listener when using the one-argument form.	required
listener	Listener | None	Complete listener state for an explicit session.	None

Raises:

Type	Description
TypeError	The call form or listener value is invalid.
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot apply the listener state.

pyalsoft.set_sound_cache_limit

set_sound_cache_limit(max_bytes: int | None) -> None

Set the convenience runtime's file-cache byte budget.

The default budget is 64 MiB. Reducing it immediately evicts least-recently used clips that are not attached to active sounds. Active clips remain pinned and may temporarily keep the cache over budget.

Parameters:

Name	Type	Description	Default
max_bytes	int | None	Non-negative byte budget, or None for no limit. Zero disables retention of inactive file clips.	required

Raises:

Type	Description
TypeError	max_bytes is not an integer or None.
ValueError	max_bytes is negative.

pyalsoft.set_voice_config

set_voice_config(
    playback: Playback,
    voice: Voice | Stream,
    config: VoiceConfig,
) -> None

Apply a complete immutable configuration to a live voice or stream.

Existing filters, effects, and auxiliary sends are replaced by the values in config. Stream configurations cannot enable looping.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Live static voice or stream to configure.	required
config	VoiceConfig	Complete replacement configuration.	required

Raises:

Type	Description
TypeError	config is not a VoiceConfig.
ValueError	Looping is enabled for a stream.
InvalidHandleError	The handle is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot apply the configuration or requested EFX.

pyalsoft.set_effect_bus_config

set_effect_bus_config(
    playback: Playback,
    bus: EffectBus,
    config: EffectBusConfig,
) -> None

Atomically replace the effect and routing configuration of a bus.

pyalsoft.shutdown

shutdown() -> None

Close and forget the convenience playback runtime, if it was opened.

Active PlayingSound handles become stopped with an end reason of SoundEndReason.SHUTDOWN. Calling this when no runtime exists is harmless. A later convenience call creates a fresh runtime.

pyalsoft.start_recording

start_recording(
    device_name: CaptureDevice | str | bytes | None = None,
    *,
    channels: int = 1,
    sample_rate: int = 48000,
    sample_type: SampleType = INT16,
    library: OpenALLibrary | None = None,
) -> Recording

Start collecting captured audio in memory on a background thread.

The default format is mono, 48 kHz, signed 16-bit PCM. Collection continues until stop_recording is called; there is no duration or memory limit.

Parameters:

Name	Type	Description	Default
device_name	CaptureDevice | str | bytes | None	Capture device object or device specifier. None selects the runtime's default capture device. A bytes value is passed to OpenAL unchanged.	None
channels	int	Number of interleaved channels in a standard mono, stereo, quad, 5.1, 6.1, or 7.1 layout.	1
sample_rate	int	Positive number of sample frames to capture per second.	48000
sample_type	SampleType	Representation used by each channel sample.	INT16
library	OpenALLibrary | None	Loaded low-level library to use. By default, discover and load the platform's OpenAL implementation.	None

Returns:

Type	Description
Recording	A recording handle to stop later.

Raises:

Type	Description
TypeError	A format or device argument has the wrong type.
ValueError	The channel count or sample rate is unsupported.
CaptureOpenError	OpenAL could not be loaded or the device could not open.
AudioBackendError	The backend could not start capture.

pyalsoft.start_capture_stream

start_capture_stream(
    device_name: CaptureDevice | str | bytes | None = None,
    *,
    channels: int = 1,
    sample_rate: int = 48000,
    sample_type: SampleType = INT16,
    capacity_frames: int = 48000,
    library: OpenALLibrary | None = None,
) -> CaptureStream

Start bounded incremental capture on a background collector thread.

Parameters:

Name	Type	Description	Default
device_name	CaptureDevice | str | bytes | None	Capture device object or device specifier. None selects the runtime's default capture device.	None
channels	int	Interleaved channel count.	1
sample_rate	int	Positive sample frames captured per second.	48000
sample_type	SampleType	Unsigned 8-bit, signed 16-bit, or float32 representation.	INT16
capacity_frames	int	Positive maximum number of unread frames retained in managed memory. The oldest frames are discarded after an overrun.	48000
library	OpenALLibrary | None	Loaded low-level library, or None for automatic discovery.	None

Returns:

Type	Description
CaptureStream	A bounded capture stream that has already started collecting frames.

Raises:

Type	Description
TypeError	A format, capacity, or device argument has the wrong type.
ValueError	The format or capacity is invalid.
CaptureOpenError	OpenAL cannot be loaded or the device cannot open.
AudioBackendError	The backend cannot start capture.

pyalsoft.start_stream

start_stream(
    playback: Playback,
    stream: Stream,
    *,
    delay_seconds: float = 0.0,
    delay_frames: int | None = None,
    start_time_ns: int | None = None,
) -> None

Start a primed stream immediately, after silence, or at a device time.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Initial stream with at least one queued chunk.	required
delay_seconds	float	Initial silence in source-audio seconds. Pitch and Doppler affect its real-time duration.	0.0
delay_frames	int | None	Exact number of silent sample frames. When provided, delay_seconds must remain 0.0.	None
start_time_ns	int | None	Absolute audio-device clock time in nanoseconds. None starts as soon as possible.	None

Raises:

Type	Description
TypeError	A timing argument has the wrong type.
ValueError	A delay or device-clock time is invalid.
InvalidHandleError	stream is released or belongs to another session.
InvalidVoiceStateError	The stream was already started or has no queued audio.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot start playback or the requested timing feature is unavailable.

pyalsoft.stop

stop(playback: Playback, voice: Voice | Stream) -> None

Stop a live voice or discard a stream's queued audio.

Stopping a terminal stream is harmless. The handle remains allocated until release, release_finished, or session closure.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Live static voice or stream to stop.	required

Raises:

Type	Description
InvalidHandleError	The handle is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot stop the source or discard stream buffers.

pyalsoft.stop_recording

stop_recording(recording: Recording) -> PCM

Stop a recording and return all captured audio as one PCM value.

This waits for the collector thread, drains frames already buffered by the device, and closes the device. Calling it again after a successful stop returns the same PCM object.

Parameters:

Name	Type	Description	Default
recording	Recording	Handle returned by start_recording.	required

Returns:

Type	Description
PCM	All captured frames as immutable, interleaved PCM.

Raises:

Type	Description
TypeError	recording is not a Recording.
AudioBackendError	Capture or cleanup failed, or the device returned no audio.

pyalsoft.stop_capture_stream

stop_capture_stream(stream: CaptureStream) -> None

Stop bounded capture, close its device, and wake waiting readers.

Calling this again after a successful stop is harmless. Buffered frames remain readable until consumed.

Raises:

Type	Description
TypeError	stream is not a CaptureStream.
AudioBackendError	Capture or cleanup failed.

pyalsoft.subscribe_device_events

subscribe_device_events(
    *,
    max_events: int = 256,
    library: OpenALLibrary | None = None,
) -> DeviceEventSubscription

Subscribe to a bounded queue of playback and capture device changes.

Native callbacks only enqueue immutable values. Application code receives them later by calling DeviceEventSubscription.next. This avoids running application work on OpenAL's system callback thread.

pyalsoft.try_write_stream

try_write_stream(
    playback: Playback,
    stream: Stream,
    samples: Buffer,
    *,
    frame_count: int | None = None,
) -> bool

Queue one complete PCM chunk, or report bounded-buffer backpressure.

This function copies samples before returning. Call update_stream regularly to reclaim processed buffers, then retry when this function returns False.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Live stream that has not reached end-of-input.	required
samples	Buffer	Non-empty bytes-like object in the format declared by open_stream.	required
frame_count	int | None	Decoded frame count for an encoded chunk. Fixed-width formats infer it and only accept a matching explicit value.	None

Returns:

Type	Description
bool	True when the chunk was queued, or False when every stream buffer
bool	is still in use. False does not consume or validate samples.

Raises:

Type	Description
TypeError	samples is not bytes-like or a handle has the wrong type.
ValueError	The sample bytes or decoded frame count are invalid.
InvalidHandleError	stream is released or belongs to another session.
InvalidVoiceStateError	The stream is terminal or input is already finished.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot upload or queue the chunk.

pyalsoft.update_acoustics

update_acoustics(
    playback: Playback | None = None,
    *,
    distance_model: DistanceModel | None = None,
    doppler_factor: float | None = None,
    speed_of_sound: float | None = None,
    meters_per_unit: float | None = None,
) -> Acoustics

Apply acoustic changes and return the complete new state.

Omitted fields retain their current values.

Parameters:

Name	Type	Description	Default
playback	Playback | None	Explicit session to update. None selects the convenience runtime.	None
distance_model	DistanceModel | None	New distance-attenuation formula.	None
doppler_factor	float | None	New non-negative Doppler scale.	None
speed_of_sound	float | None	New propagation speed in world-units per second.	None
meters_per_unit	float | None	New number of meters represented by one world-space unit.	None

Returns:

Type	Description
Acoustics	Validated acoustic settings after applying the changes.

Raises:

Type	Description
TypeError	A value has the wrong type.
ValueError	A numeric value is non-finite or outside its supported range.
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot query or apply the acoustic settings.

pyalsoft.update_listener

update_listener(
    playback: Playback | None = None,
    *,
    position: Vector3 | None = None,
    velocity: Vector3 | None = None,
    forward: Vector3 | None = None,
    up: Vector3 | None = None,
    gain: float | None = None,
) -> Listener

Apply a batch of listener changes and return the complete new state.

Omitted fields retain their current values.

Parameters:

Name	Type	Description	Default
playback	Playback | None	Explicit session to update. None selects the convenience runtime.	None
position	Vector3 | None	New listener position.	None
velocity	Vector3 | None	New listener velocity used for Doppler shift.	None
forward	Vector3 | None	New non-zero viewing-direction vector.	None
up	Vector3 | None	New non-zero upward vector.	None
gain	float | None	New non-negative final-mix linear gain.	None

Returns:

Type	Description
Listener	Validated listener state after applying the changes.

Raises:

Type	Description
TypeError	A value has the wrong type.
ValueError	A vector is invalid or gain is negative or non-finite.
PlaybackClosedError	The explicit session is closed.
AudioBackendError	OpenAL cannot query or apply the listener state.

pyalsoft.update_stream

update_stream(
    playback: Playback, stream: Stream
) -> StreamStatus

Reclaim processed chunks, recover underruns, and return stream status.

Call this regularly while producing audio. A logically playing stream restarts automatically when new audio follows an underrun. Once finish_stream has declared end-of-input, the state changes to FINISHED after the queue drains.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Live stream to service.	required

Returns:

Type	Description
StreamStatus	Current lifecycle state, queue depth, queued duration, and underrun count.

Raises:

Type	Description
InvalidHandleError	stream is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL reports invalid queue state or a native failure.

pyalsoft.upload

upload(
    playback: Playback,
    pcm: PCM | BufferData | AudioPath,
    *,
    loop_points: tuple[int, int] | None = None,
) -> Clip

Upload immutable audio data to a playback session.

OpenAL copies the samples into a native buffer. The returned clip may be played more than once and remains owned by playback until it is released explicitly or the session closes. Optional loop points select the sample-frame range repeated by voices that enable looping; the start frame is inclusive and the end frame is exclusive.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session that will own the clip.	required
pcm	PCM | BufferData | AudioPath	Complete PCM, exact-format buffer data, or supported audio path to decode and copy.	required
loop_points	tuple[int, int] | None	Optional (start, end) loop-frame range. None makes looping voices repeat the complete clip.	None

Returns:

Type	Description
Clip	An opaque clip identity for the uploaded audio.

Raises:

Type	Description
TypeError	pcm is not PCM, BufferData, or a path, or loop points are not integers.
ValueError	The loop-point range is empty or outside the clip.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot allocate or populate the buffer, or loop points were requested without AL_SOFT_loop_points support.

pyalsoft.wait

wait(
    playback: Playback,
    voice: Voice | Stream,
    *,
    timeout: float | None = None,
    poll_interval: float = 0.01,
) -> bool

Block until a voice or stream becomes terminal, or a timeout expires.

This portable wait uses ordinary managed status queries and therefore does not require an optional OpenAL event extension. For streams it also reclaims processed buffers and advances the managed stream lifecycle.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns voice.	required
voice	Voice | Stream	Static voice or stream to observe.	required
timeout	float | None	Maximum wall-clock seconds to wait, or None for no limit.	None
poll_interval	float	Positive wall-clock seconds between status queries.	0.01

Returns:

Type	Description
bool	True when the resource is terminal, or False when the timeout
bool	expires first.

Raises:

Type	Description
TypeError	A handle or timing argument has the wrong type.
ValueError	A timing argument is invalid.
InvalidHandleError	The handle is released or belongs to another session.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot query the resource.

pyalsoft.write_stream

write_stream(
    playback: Playback,
    stream: Stream,
    samples: Buffer,
    *,
    frame_count: int | None = None,
    timeout: float | None = None,
    poll_interval: float = 0.01,
) -> bool

Queue one chunk, waiting for bounded-buffer capacity when necessary.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Live stream that will receive the chunk.	required
samples	Buffer	Complete bytes-like encoded or PCM chunk.	required
frame_count	int | None	Decoded frame count for an encoded chunk.	None
timeout	float | None	Maximum wall-clock seconds to wait, or None for no limit.	None
poll_interval	float	Positive wall-clock seconds between capacity checks.	0.01

Returns:

Type	Description
bool	True when the chunk is queued, or False when the timeout expires.

Raises:

Type	Description
TypeError	A handle, sample buffer, or timing argument has the wrong type.
ValueError	A chunk or timing argument is invalid.
InvalidHandleError	The stream is released or belongs to another session.
InvalidVoiceStateError	The stream no longer accepts input.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot reclaim or queue a buffer.

Note

Capacity cannot become available before an initial stream has started. Do not block while filling all initial buffers; start the stream first or provide a finite timeout.