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.Filter

Filter = LowPassFilter | HighPassFilter

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.

Raises:

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

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.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.Clip dataclass

Opaque identity for PCM 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

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.

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.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 device limits the number of simultaneous sends.

Attributes:

Name	Type	Description
effect	Reverb	Reverb applied to this route.
filter	Filter | None	Optional low-pass or high-pass filter applied only to this route.

Raises:

Type	Description
TypeError	effect or filter is not a supported configuration.

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

An EFX filter that attenuates the low-frequency signal.

Attributes:

Name	Type	Description
gain	float	Overall linear gain, from 0.0 through 1.0.
low_frequency_gain	float	Additional low-frequency gain, from 0.0 through 1.0.

Raises:

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

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

An EFX filter that attenuates the high-frequency signal.

Attributes:

Name	Type	Description
gain	float	Overall linear gain, from 0.0 through 1.0.
high_frequency_gain	float	Additional high-frequency gain, from 0.0 through 1.0.

Raises:

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

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 channels, either 1 (mono) or 2 (stereo).
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.PlaybackConfig dataclass

Preferences applied while creating an OpenAL playback context.

Attributes:

Name	Type	Description
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.

Raises:

Type	Description
TypeError	hrtf is neither a boolean nor None.

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.

pyalsoft.PlaybackOpenError

Bases: AudioError

Raised when a playback device or context cannot be opened.

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 a WAV 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 currently playing.

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

Current playhead position in seconds of source audio.

offset_frames property

offset_frames: int

Current playhead position as an exact sample-frame offset.

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.

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.

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() -> None

Start the sound again from its beginning.

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

Raises:

Type	Description
InvalidVoiceStateError	The convenience runtime has been shut down.

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,
    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
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.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.Reverb dataclass

Immutable standard EFX reverb parameters.

Values use the OpenAL EFX standard-reverb ranges and defaults. Attach a reverb to a voice through EffectSend.

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 linear 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	Reverberation decay time in seconds, from 0.1 through 20.0.
high_frequency_decay_ratio	float	High-frequency 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 in seconds, from 0.0 through 0.3.
late_reverb_gain	float	Late-reverberation gain, from 0.0 through 10.0.
late_reverb_delay	float	Late-reverberation delay in seconds, from 0.0 through 0.1.
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 factor, from 0.0 through 10.0.
high_frequency_decay_limit	bool	Whether air absorption limits high-frequency decay time.

Raises:

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

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.

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, either 1 (mono) or 2 (stereo).
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.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.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.
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.VoiceState

Bases: Enum

Observed playback state of a static voice.

Attributes:

Name	Type	Description
INITIAL		Ready to play from the beginning.
PLAYING		Currently advancing through the clip.
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.
offset_frames	int	Current playhead position as an exact sample-frame index.

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 WAV 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, and streams 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.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_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_info

get_playback_info(playback: Playback) -> PlaybackInfo

Return observed device, renderer, version, 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.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 WAV format and length information without opening an audio device.

The managed file API accepts uncompressed mono or stereo WAV files containing unsigned 8-bit or signed 16-bit PCM and at least one complete frame.

Parameters:

Name	Type	Description	Default
path	AudioPath	Path to the WAV file. User-directory markers are expanded and the path is resolved before reading.	required

Returns:

Type	Description
SoundInfo	Validated channel layout, sample rate, sample type, and length.

Raises:

Type	Description
TypeError	path is not string or path-like.
AudioFileError	The file cannot be read or uses an unsupported WAV format.

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.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_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.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_stream

open_stream(
    playback: Playback,
    *,
    channels: int,
    sample_rate: int,
    sample_type: SampleType = INT16,
    buffer_count: int = 4,
    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	Number of interleaved channels, either 1 or 2.	required
sample_rate	int	Positive number of sample frames per second.	required
sample_type	SampleType	Representation used by each channel sample.	INT16
buffer_count	int	Positive maximum number of chunks that may be queued before backpressure is reported.	4
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.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,
    filter: Filter | None = None,
    effect_sends: tuple[EffectSend, ...]
    | list[EffectSend]
    | None = None,
    offset_seconds: float = 0.0,
    offset_frames: int | 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,
    filter: Filter | None = None,
    effect_sends: tuple[EffectSend, ...]
    | list[EffectSend]
    | None = None,
    offset_seconds: float = 0.0,
    offset_frames: int | None = None,
) -> PlayingSound

Play an explicit clip, WAV 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 WAV 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.

Parameters:

Name	Type	Description	Default
playback	Playback | AudioPath | PCM	Explicit playback session in the two-argument form; otherwise, a WAV 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
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

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 or initial offset is invalid.
AudioFileError	A WAV 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.

pyalsoft.release

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

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

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

Release a clip, voice, or stream before its playback 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	Live clip, static voice, or stream 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 a clip attached to a live voice.
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.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, either 1 or 2.	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.restart

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

Rewind a static voice and immediately start it playing.

Parameters:

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

Raises:

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

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.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.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, either 1 or 2.	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_stream

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

Start a primed stream for the first and only time.

Parameters:

Name	Type	Description	Default
playback	Playback	Session that owns stream.	required
stream	Stream	Initial stream with at least one queued chunk.	required

Raises:

Type	Description
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.

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.try_write_stream

try_write_stream(
    playback: Playback, stream: Stream, samples: Buffer
) -> 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 containing a whole number of frames in the format declared by open_stream.	required

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	samples is empty or ends with a partial frame.
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,
) -> 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

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) -> Clip

Upload immutable PCM 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.

Parameters:

Name	Type	Description	Default
playback	Playback	Open session that will own the clip.	required
pcm	PCM	Complete PCM sample data to copy.	required

Returns:

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

Raises:

Type	Description
TypeError	pcm is not a PCM.
PlaybackClosedError	playback is closed.
AudioBackendError	OpenAL cannot allocate or populate the buffer.