Owned backend API reference¶

This page documents the hand-written lifetime and extension layer in pyalsoft.bindings. The generated AL/ALC command wrappers, typed objects, constants, enums, and registry metadata remain in the low-level bindings reference. See owned backend handles for task-oriented examples and native lifetime guidance.

This remains a low-level API: ordinary generated calls and state queries do not automatically translate the AL or ALC error state into Python exceptions. The owned methods document the places where lifetime-sensitive failures are checked and raised explicitly.

Library loading and extensions¶

Typed low-level bindings and runtime loading for OpenAL Soft.

pyalsoft.bindings.LibraryPath ¶

LibraryPath = str | PathLike[str]

A string or path-like location of an OpenAL shared library.

pyalsoft.bindings.ForeignFunction ¶

ForeignFunction = Callable[..., Any]

A generated ctypes callable for one raw OpenAL command.

pyalsoft.bindings.OpenALLibrary ¶

A loaded OpenAL library with typed core and extension functions.

Core functions and their generated signatures are bound lazily. AL extension functions are resolved for the current context; ALC extension functions are resolved for the device supplied to get_function or get_alc_extension. Resolved entry points are cached by native context or device scope.

Prefer load unless direct construction is useful. A loaded library does not itself own devices or contexts and has no close operation.

Parameters:

Name	Type	Description	Default
`path`	`LibraryPath \| None`	Explicit shared-library path. `None` searches the bundled runtime, platform discovery results, and conventional OpenAL library names.	`None`

Attributes:

Name	Type	Description
`library_name`		Path or loader name used to open the native library.
`native_library`	`Any`	Underlying `ctypes.CDLL` instance.
`al`	`ALCommands`	Generated Python-value wrappers for AL commands and objects.
`alc`	`ALCCommands`	Generated Python-value wrappers for ALC commands.
`extensions`	`ExtensionCapabilities`	Generated mapping and attributes for registry extensions.

Raises:

Type	Description
`TypeError`	`path` is not string or path-like.
`LibraryNotFoundError`	No usable library could be loaded.

native_library `property` ¶

native_library: Any

The underlying ctypes.CDLL instance.

al `property` ¶

al: ALCommands

Python-value wrappers for AL commands and typed AL objects.

Core commands are available immediately. Calling extension commands may require a current context and raises an extension-resolution error when the entry point is unavailable.

alc `property` ¶

alc: ALCCommands

Python-value wrappers for ALC device and context commands.

extensions `property` ¶

extensions: ExtensionCapabilities

Generated capability objects for all registry extensions.

Capabilities support mapping lookup by registry name and generated snake-case attributes such as alc_ext_efx.

get_export ¶

get_export(name: str) -> ForeignFunction

Return a directly exported command without checking extensions.

Parameters:

Name	Type	Description	Default
`name`	`str`	Exact C command name present in the generated registry.	required

Returns:

Type	Description
`ForeignFunction`	A cached `ctypes` callable with the generated prototype.

Raises:

Type	Description
`FunctionUnavailableError`	`name` is unknown, is extension-only, or is not exported by the loaded library.

clear_extension_cache ¶

clear_extension_cache() -> None

Clear all cached extension entry points.

Owned devices and contexts invalidate their own scopes automatically. Applications that destroy or reconfigure raw native handles should clear this cache before a handle address can be reused.

register_system_event_callback ¶

register_system_event_callback(
    callback: Callable[
        [int, int, object | None, str], None
    ],
    *,
    event_types: Sequence[int] = (),
) -> CallbackRegistration

Register and retain the global ALC_SOFT_system_events callback.

Only one registration may be active for the same loaded native library; registering another closes the previous one. The callback can run on a background system thread and receives (event_type, device_type, device_handle, message). It must return promptly and must not call AL or ALC functions. Python exceptions are retained by the returned registration.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[int, int, object \| None, str], None]`	Function invoked for each enabled system event. A null native device pointer is delivered as `None`.	required
`event_types`	`Sequence[int]`	Registry event-type values to enable. An empty sequence installs the callback without explicitly enabling event types.	`()`

Returns:

Type	Description
`CallbackRegistration`	Owned registration that keeps the native trampoline alive.

Raises:

Type	Description
`TypeError`	`callback` is not callable or an event type is not integer-like.
`ExtensionUnavailableError`	`ALC_SOFT_system_events` is unavailable.
`CallbackControlError`	OpenAL cannot enable the requested event types.

clear_system_event_callback ¶

clear_system_event_callback() -> None

Disable events and remove this native library's global callback.

Calling this without an active registration is harmless. Callback errors retained during unregistration remain available on a registration held by the caller.

Raises:

Type	Description
`CallbackControlError`	Called from the active callback or while its registration close is already in progress on this thread.

is_al_extension_present ¶

is_al_extension_present(extension: str) -> bool

Check an AL extension against the current context.

Parameters:

Name	Type	Description	Default
`extension`	`str`	ASCII registry extension name.	required

Returns:

Type	Description
`bool`	Whether the current context reports the extension.

Raises:

Type	Description
`ValueError`	`extension` contains non-ASCII characters.
`ContextRequiredError`	No AL context is current.
`FunctionUnavailableError`	A required core query is unavailable.

is_alc_extension_present ¶

is_alc_extension_present(
    extension: str, device: object | None = None
) -> bool

Check an ALC extension for a device or the null-device scope.

Parameters:

Name	Type	Description	Default
`extension`	`str`	ASCII registry extension name.	required
`device`	`object \| None`	Native ALC device handle. `None` queries null-device extensions.	`None`

Returns:

Type	Description
`bool`	Whether the selected ALC scope reports the extension.

Raises:

Type	Description
`ValueError`	`extension` contains non-ASCII characters.
`FunctionUnavailableError`	The required core query is unavailable.

get_al_extension ¶

get_al_extension(
    name: str,
    *,
    device: object | None = None,
    check_extension: bool = True,
) -> ForeignFunction

Resolve and cache an AL extension command for the effective scope.

AL-only commands use the current context. Commands from extensions that also expose ALC entry points can instead use an explicit device, which is required by direct-context APIs.

Parameters:

Name	Type	Description	Default
`name`	`str`	Exact C name of an AL extension command.	required
`device`	`object \| None`	Optional native ALC device used by dual-API extensions.	`None`
`check_extension`	`bool`	Verify that the effective context or device reports the declaring extension before resolving the entry point.	`True`

Returns:

Type	Description
`ForeignFunction`	A cached `ctypes` callable with the generated prototype.

Raises:

Type	Description
`ValueError`	`name` contains non-ASCII characters.
`ContextRequiredError`	Resolution requires a context or device that was not supplied.
`ExtensionUnavailableError`	The declaring extension is not present.
`FunctionUnavailableError`	The name, namespace, or native entry point is invalid or unavailable.

get_alc_extension ¶

get_alc_extension(
    name: str,
    device: object | None = None,
    *,
    check_extension: bool = True,
) -> ForeignFunction

Resolve and cache an ALC extension command for a device scope.

Parameters:

Name	Type	Description	Default
`name`	`str`	Exact C name of an ALC extension command.	required
`device`	`object \| None`	Native ALC device handle, or `None` for the null-device scope.	`None`
`check_extension`	`bool`	Verify that the effective scope reports the declaring extension before resolving the entry point.	`True`

Returns:

Type	Description
`ForeignFunction`	A cached `ctypes` callable with the generated prototype.

Raises:

Type	Description
`ValueError`	`name` contains non-ASCII characters.
`ContextRequiredError`	An AL-side extension check requires a current context.
`ExtensionUnavailableError`	The declaring extension is not present.
`FunctionUnavailableError`	The name, namespace, or native entry point is invalid or unavailable.

get_function ¶

get_function(
    name: str,
    *,
    device: object | None = None,
    check_extension: bool = True,
) -> ForeignFunction

Return a typed core or extension function by its C command name.

Direct exports use get_export. Extension commands are routed to the AL or ALC resolver according to generated registry metadata.

Parameters:

Name	Type	Description	Default
`name`	`str`	Exact C command name.	required
`device`	`object \| None`	Native ALC device handle used for device-scoped resolution.	`None`
`check_extension`	`bool`	Verify extension availability before resolving an extension entry point.	`True`

Returns:

Type	Description
`ForeignFunction`	A cached `ctypes` callable with the generated prototype.

Raises:

Type	Description
`ContextRequiredError`	Resolution requires a current AL context.
`ExtensionUnavailableError`	The command's extension is not present.
`FunctionUnavailableError`	`name` is unknown or its entry point is unavailable.
`ValueError`	A command or extension name cannot be ASCII encoded.

pyalsoft.bindings.Extension ¶

Capabilities and runtime access for one registry extension.

Do not construct instances directly. Obtain them from OpenALLibrary.extensions by registry name or generated snake-case attribute. Declaration metadata is available without querying the runtime.

Attributes:

Name	Type	Description
`library`		Loaded library used for runtime queries and command resolution.
`name`	`str`	Registry extension name.
`apis`	`tuple[str, ...]`	API namespaces declared by the extension, such as `"al"` or `"alc"`.
`commands`	`tuple[str, ...]`	Commands declared by all requirements of the extension.
`enums`	`tuple[str, ...]`	Enum names declared by all requirements of the extension.
`types`	`tuple[str, ...]`	C type names declared by all requirements of the extension.
`dependencies`	`tuple[str, ...]`	Non-empty registry dependency expressions.

name `property` ¶

name: str

Registry extension name.

apis `property` ¶

apis: tuple[str, ...]

API namespaces declared by this extension.

commands `property` ¶

commands: tuple[str, ...]

Command names declared by this extension, without duplicates.

enums `property` ¶

enums: tuple[str, ...]

Enum names declared by this extension, without duplicates.

types `property` ¶

types: tuple[str, ...]

C type names declared by this extension, without duplicates.

dependencies `property` ¶

dependencies: tuple[str, ...]

Registry dependency expressions, without duplicates.

is_present ¶

is_present(device: object | None = None) -> bool

Check whether the extension is available for a context or device.

ALC extensions use device or the null-device scope. AL extensions use the current context. For dual-API extensions, supplying a device selects the ALC query.

Parameters:

Name	Type	Description	Default
`device`	`object \| None`	Native ALC device handle, or `None` when using the current AL context or null-device scope.	`None`

Returns:

Type	Description
`bool`	Whether the selected runtime scope reports this extension.

Raises:

Type	Description
`ContextRequiredError`	An AL query has no current context.
`FunctionUnavailableError`	A required core query is unavailable.

require ¶

require(device: object | None = None) -> None

Require this extension for a context or device scope.

Parameters:

Name	Type	Description	Default
`device`	`object \| None`	Native ALC device handle, or `None` when using the current AL context or null-device scope.	`None`

Raises:

Type	Description
`ContextRequiredError`	An AL query has no current context.
`ExtensionUnavailableError`	The selected scope does not report this extension.
`FunctionUnavailableError`	A required core query is unavailable.

get_function ¶

get_function(
    name: str, *, device: object | None = None
) -> ForeignFunction

Resolve a command declared by this extension.

Parameters:

Name	Type	Description	Default
`name`	`str`	Exact C command name declared by this extension.	required
`device`	`object \| None`	Native ALC device used for device-scoped resolution.	`None`

Returns:

Type	Description
`ForeignFunction`	Typed, cached native command callable.

Raises:

Type	Description
`KeyError`	`name` is not declared by this extension.
`ContextRequiredError`	Resolution requires a current AL context.
`ExtensionUnavailableError`	This extension is not present.
`FunctionUnavailableError`	The native entry point is unavailable.

pyalsoft.bindings.load ¶

load(path: LibraryPath | None = None) -> OpenALLibrary

Load OpenAL and return its typed low-level binding object.

Each call creates an independent Python binding object and native-library handle. It does not cache a process-wide singleton.

Parameters:

Name	Type	Description	Default
`path`	`LibraryPath \| None`	Explicit shared-library path. `None` searches the bundled runtime, platform discovery results, and conventional OpenAL library names.	`None`

Returns:

Type	Description
`OpenALLibrary`	Loaded low-level library with lazy command namespaces.

Raises:

Type	Description
`TypeError`	`path` is not string or path-like.
`LibraryNotFoundError`	No usable library could be loaded.

Owned devices and contexts¶

Typed low-level bindings and runtime loading for OpenAL Soft.

pyalsoft.bindings.Device ¶

An owned ALC device handle.

Do not construct instances directly. Use the more specific PlaybackDevice, LoopbackDevice, or CaptureDevice returned by the module-level open helpers. Closing a playback device first closes every context created through it. Context-manager exit calls close.

Extension-backed properties raise ExtensionUnavailableError when the device does not expose their named extension. Access requiring a native handle raises HandleClosedError after closure. Query helpers forward directly to generated commands; callers remain responsible for the native ALC error state.

Attributes:

Name	Type	Description
`library`		Loaded OpenAL library that owns the command wrappers.
`closed`	`bool`	Whether the native device has been closed.
`handle`	`object`	Native ALC device pointer for generated raw calls.
`name`	`str \| None`	Implementation-provided device specifier, when available.
`extensions`	`frozenset[str]`	Extension names reported for this device.
`version`	`tuple[int, int]`	Reported ALC major and minor version.

closed `property` ¶

closed: bool

Whether the native device has been closed.

handle `property` ¶

handle: object

The underlying ALC device pointer for raw generated calls.

Raises:

Type	Description
`HandleClosedError`	This device has been closed.

name `property` ¶

name: str | None

The implementation-provided device name.

extensions `property` ¶

extensions: frozenset[str]

Extensions reported for this device.

version `property` ¶

version: tuple[int, int]

The device's ALC major and minor version.

connected `property` ¶

connected: bool

Whether the device remains connected (ALC_EXT_disconnect).

hrtf_enabled `property` ¶

hrtf_enabled: bool

Whether HRTF rendering is currently enabled.

hrtf_status `property` ¶

hrtf_status: ALCHrtfStatusSOFT | int

The device's detailed HRTF status.

hrtf_name `property` ¶

hrtf_name: str | None

The active HRTF specifier, if any.

hrtf_specifier_count `property` ¶

hrtf_specifier_count: int

The number of HRTF specifiers available to the device.

output_limiter_enabled `property` ¶

output_limiter_enabled: bool

Whether the output limiter is currently enabled.

device_clock `property` ¶

device_clock: int

The device clock in nanoseconds.

device_latency `property` ¶

device_latency: int

The device latency in nanoseconds.

clock_latency `property` ¶

clock_latency: tuple[int, int]

Atomically query device clock and latency in nanoseconds.

output_mode `property` ¶

output_mode: ALCOutputModeSOFT | int

The active output mode (ALC_SOFT_output_mode).

max_ambisonic_order `property` ¶

max_ambisonic_order: int

The highest loopback ambisonic order supported by the device.

context_flags `property` ¶

context_flags: ALCContextFlagsEXT

The active context flags (ALC_EXT_debug).

require_extension ¶

require_extension(name: str) -> None

Require an ALC extension on this device.

Parameters:

Name	Type	Description	Default
`name`	`str`	Registry extension name.	required

Raises:

Type	Description
`KeyError`	`name` is not a known registry extension.
`HandleClosedError`	This device is closed.
`ExtensionUnavailableError`	The device does not report `name`.

is_extension_present ¶

is_extension_present(name: str) -> bool

Return whether an ALC extension is present on this device.

Parameters:

Name	Type	Description	Default
`name`	`str`	ASCII registry extension name.	required

Returns:

Type	Description
`bool`	Whether the device reports the extension.

Raises:

Type	Description
`HandleClosedError`	This device is closed.
`ValueError`	`name` contains non-ASCII characters.

get_string ¶

get_string(parameter: ALCContextString | int) -> str | None

Query one device string through alcGetString.

Parameters:

Name	Type	Description	Default
`parameter`	`ALCContextString \| int`	ALC string selector.	required

Returns:

Type	Description
`str \| None`	Decoded implementation string, or `None` for a null result.

Raises:

Type	Description
`HandleClosedError`	This device is closed.

get_integers ¶

get_integers(
    parameter: ALCContextInteger | int, count: int = 1
) -> tuple[int, ...]

Query one or more device integers through alcGetIntegerv.

Parameters:

Name	Type	Description	Default
`parameter`	`ALCContextInteger \| int`	ALC integer selector.	required
`count`	`int`	Positive number of integers to return.	`1`

Returns:

Type	Description
`tuple[int, ...]`	Exactly `count` integer values.

Raises:

Type	Description
`TypeError`	`count` is not an integer.
`ValueError`	`count` is less than one.
`HandleClosedError`	This device is closed.

get_integer ¶

get_integer(parameter: ALCContextInteger | int) -> int

Query one device integer through alcGetIntegerv.

Parameters:

Name	Type	Description	Default
`parameter`	`ALCContextInteger \| int`	ALC integer selector.	required

Returns:

Type	Description
`int`	The queried integer value.

Raises:

Type	Description
`HandleClosedError`	This device is closed.

get_integer64s ¶

get_integer64s(
    parameter: int, count: int = 1
) -> tuple[int, ...]

Query device clock values through ALC_SOFT_device_clock.

Parameters:

Name	Type	Description	Default
`parameter`	`int`	Extension integer selector.	required
`count`	`int`	Positive number of 64-bit integers to return.	`1`

Returns:

Type	Description
`tuple[int, ...]`	Exactly `count` integer values.

Raises:

Type	Description
`TypeError`	`count` is not an integer.
`ValueError`	`count` is less than one.
`HandleClosedError`	This device is closed.
`ExtensionUnavailableError`	`ALC_SOFT_device_clock` is unavailable.

get_hrtf_specifier ¶

get_hrtf_specifier(index: int) -> str | None

Return one available HRTF specifier by index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Non-negative index less than `hrtf_specifier_count`.	required

Returns:

Type	Description
`str \| None`	Implementation-provided HRTF name, or `None` for a null result.

Raises:

Type	Description
`TypeError`	`index` is not an integer.
`ValueError`	`index` is negative.
`HandleClosedError`	This device is closed.
`ExtensionUnavailableError`	`ALC_SOFT_HRTF` is unavailable.

close ¶

close() -> None

Close owned contexts and then the native device.

Contexts are closed in reverse creation order. Calling this again after a successful close is harmless. Exceptions raised while closing an owned context propagate and leave the device open.

Raises:

Type	Description
`DeviceCloseError`	OpenAL refuses to close the native device.

pyalsoft.bindings.PlaybackDevice ¶

Bases: Device

An owned playback device that can create and own AL contexts.

create_context ¶

create_context(
    attributes: Sequence[int] | None = None,
) -> Context

Create an owned context attached to this device.

Parameters:

Name	Type	Description	Default
`attributes`	`Sequence[int] \| None`	Flat ALC attribute/value sequence terminated by the generated wrapper. `None` requests backend defaults.	`None`

Returns:

Type	Description
`Context`	Open context owned by this device.

Raises:

Type	Description
`HandleClosedError`	This device is closed.
`ContextCreateError`	OpenAL cannot create the requested context.

pyalsoft.bindings.LoopbackDevice ¶

Bases: PlaybackDevice

An ALC_SOFT_loopback device for deterministic offline rendering.

Create a context with explicit loopback format attributes, start AL sources, then render frames into caller-owned writable storage with render_samples.

is_render_format_supported ¶

is_render_format_supported(
    frequency: int,
    channels: ALCRenderFormatChannelSOFT | int,
    sample_type: ALCRenderFormatTypeSOFT | int,
) -> bool

Return whether a loopback render format is supported.

Parameters:

Name	Type	Description	Default
`frequency`	`int`	Requested sample rate in frames per second.	required
`channels`	`ALCRenderFormatChannelSOFT \| int`	`ALC_SOFT_loopback` channel-layout value.	required
`sample_type`	`ALCRenderFormatTypeSOFT \| int`	`ALC_SOFT_loopback` sample representation.	required

Returns:

Type	Description
`bool`	Whether the device accepts this exact render format.

Raises:

Type	Description
`HandleClosedError`	This device is closed.

render_samples ¶

render_samples(buffer: object, samples: int) -> None

Render frames into caller-owned writable storage.

The caller must size buffer for samples complete frames in the format selected when creating the active loopback context.

Parameters:

Name	Type	Description	Default
`buffer`	`object`	Writable buffer accepted by the generated command wrapper.	required
`samples`	`int`	Non-negative number of sample frames to render.	required

Raises:

Type	Description
`TypeError`	`samples` is not an integer or `buffer` is incompatible.
`ValueError`	`samples` is negative.
`HandleClosedError`	This device is closed.

pyalsoft.bindings.CaptureDevice ¶

Bases: Device

An owned input device opened through the core ALC capture API.

Do not construct instances directly. Use open_capture_device. The handle remembers the requested format for callers but does not convert captured samples.

Attributes:

Name	Type	Description
`library`		Loaded OpenAL library used by this device.
`frequency`		Capture sample rate in frames per second.
`format`		OpenAL sample-format value requested at open time.
`available_samples`	`int`	Number of complete frames currently ready to read.
`name`	`str \| None`	Implementation-provided capture device specifier.
`capturing`	`bool`	Whether `start` has been called without a matching `stop`.
`closed`	`bool`	Whether the native capture device has been closed.
`handle`	`object`	Native ALC capture-device pointer for generated raw calls.

available_samples `property` ¶

available_samples: int

The number of capture frames currently ready to read.

name `property` ¶

name: str | None

The implementation-provided capture device name.

capturing `property` ¶

capturing: bool

Whether capture has been started through this handle.

start ¶

start() -> None

Start input capture.

Calling this while capture is already started is harmless.

Raises:

Type	Description
`HandleClosedError`	This capture device is closed.

stop ¶

stop() -> None

Stop input capture while preserving buffered samples.

Calling this while capture is not started is harmless.

read_samples ¶

read_samples(buffer: object, samples: int) -> None

Read capture frames into caller-owned writable storage.

The caller must provide storage for samples complete frames in this device's format and should not request more than available_samples.

Parameters:

Name	Type	Description	Default
`buffer`	`object`	Writable buffer accepted by the generated command wrapper.	required
`samples`	`int`	Non-negative number of sample frames to read.	required

Raises:

Type	Description
`TypeError`	`samples` is not an integer or `buffer` is incompatible.
`ValueError`	`samples` is negative.
`HandleClosedError`	This capture device is closed.

close ¶

close() -> None

Stop capture and close the native capture device.

Calling this again after a successful close is harmless.

Raises:

Type	Description
`DeviceCloseError`	OpenAL refuses to close the native capture device.

pyalsoft.bindings.Context ¶

An owned AL context attached to a playback device.

Do not construct instances directly. Use PlaybackDevice.create_context. The context owns callback registrations and retained static-buffer storage; closing it destroys that native state and invalidates every typed AL object bound to it. Context-manager exit calls close.

Operations that require this context temporarily activate it while holding the loaded library's context lock, then restore the previous context. Ordinary state properties forward directly to generated commands; callers remain responsible for querying and clearing the native AL error state.

Attributes:

Name	Type	Description
`device`		Playback or loopback device that owns this context.
`library`		Loaded OpenAL library shared with `device`.
`closed`	`bool`	Whether the native context has been destroyed.
`handle`	`object`	Native ALC context pointer for generated raw calls.
`current`	`bool`	Whether this is the process-wide current context.
`listener`	`Listener`	Typed context-scoped listener singleton.

closed `property` ¶

closed: bool

Whether the native context has been destroyed.

handle `property` ¶

handle: object

The underlying ALC context pointer for raw generated calls.

Raises:

Type	Description
`HandleClosedError`	This context has been destroyed.

current `property` ¶

current: bool

Whether this is the process-wide current context.

This does not inspect the ALC_EXT_thread_local_context override.

Raises:

Type	Description
`HandleClosedError`	This context has been destroyed.

listener `property` ¶

listener: Listener

Return the typed listener singleton bound to this context.

Raises:

Type	Description
`HandleClosedError`	This context is closed.

vendor `property` ¶

vendor: str | None

The current AL implementation vendor, or None on native failure.

version `property` ¶

version: str | None

The current AL implementation version, or None on native failure.

renderer `property` ¶

renderer: str | None

The current AL renderer name, or None on native failure.

extensions `property` ¶

extensions: frozenset[str]

Extensions reported for this AL context.

doppler_factor `property` `writable` ¶

doppler_factor: float

Get or set the global Doppler scale.

OpenAL defines non-negative values and uses 1.0 by default. The low-level setter forwards the value without consuming the native AL error state.

doppler_velocity `property` `writable` ¶

doppler_velocity: float

Get or set the legacy Doppler reference velocity.

This OpenAL 1.0 control is retained for compatibility; prefer speed_of_sound for OpenAL 1.1 behavior.

speed_of_sound `property` `writable` ¶

speed_of_sound: float

Get or set propagation speed for Doppler calculations.

Values are in world-units per second. OpenAL requires at least 0.0001 and uses 343.3 by default.

distance_model `property` `writable` ¶

distance_model: ALDistanceModel | int

Get or set the global distance-attenuation model.

Unknown future values are returned as integers.

default_filter_order `property` ¶

default_filter_order: int

The default resampler filter order for this context.

Raises:

Type	Description
`ExtensionUnavailableError`	`ALC_EXT_DEFAULT_FILTER_ORDER` is absent.
`HandleClosedError`	This context or its device is closed.

make_current ¶

make_current() -> None

Make this the process-wide current context.

The prior context is not restored automatically. Use activate for a temporary change.

Raises:

Type	Description
`HandleClosedError`	This context has been destroyed.
`ContextActivationError`	OpenAL refuses the context change.

make_thread_current ¶

make_thread_current() -> None

Make this current only for the calling thread.

The prior thread-local context is not restored automatically. Use activate(thread_local=True) for a temporary change.

Raises:

Type	Description
`HandleClosedError`	This context or its device is closed.
`ExtensionUnavailableError`	`ALC_EXT_thread_local_context` is absent.
`ContextActivationError`	OpenAL refuses the context change.

require_extension ¶

require_extension(name: str) -> None

Require an AL extension while this context is temporarily current.

Parameters:

Name	Type	Description	Default
`name`	`str`	Registry extension name.	required

Raises:

Type	Description
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	The context does not report `name`.
`ContextActivationError`	The context cannot be activated or restored.

activate ¶

activate(
    *, thread_local: bool = False
) -> Iterator[Context]

Temporarily make this context current and restore the prior context.

Activation is serialized across contexts that share this loaded library. Nested activation of the same context is supported.

Parameters:

Name	Type	Description	Default
`thread_local`	`bool`	Use `ALC_EXT_thread_local_context` instead of the process-wide current-context API.	`False`

Yields:

Type	Description
`Context`	This context while it is current in the requested scope.

Raises:

Type	Description
`HandleClosedError`	This context or its device is closed.
`ExtensionUnavailableError`	Thread-local activation was requested but the device does not expose the extension.
`ContextActivationError`	OpenAL cannot activate or restore a context.

source ¶

source(identifier: int) -> Source

Wrap an existing integer source identifier for this context.

This does not allocate a source or verify that identifier is live.

Parameters:

Name	Type	Description	Default
`identifier`	`int`	Non-negative OpenAL source name.	required

Returns:

Type	Description
`Source`	Context-affine typed source.

Raises:

Type	Description
`TypeError`	`identifier` is not an integer.
`ValueError`	`identifier` is negative.
`HandleClosedError`	This context is closed.

buffer ¶

buffer(identifier: int) -> Buffer

Wrap an existing integer buffer identifier for this context.

This does not allocate a buffer or verify that identifier is live.

Parameters:

Name	Type	Description	Default
`identifier`	`int`	Non-negative OpenAL buffer name.	required

Returns:

Type	Description
`Buffer`	Context-affine typed buffer.

Raises:

Type	Description
`TypeError`	`identifier` is not an integer.
`ValueError`	`identifier` is negative.
`HandleClosedError`	This context is closed.

effect ¶

effect(identifier: int) -> Effect

Wrap an existing integer EFX effect identifier for this context.

This does not allocate an effect or verify that identifier is live.

Parameters:

Name	Type	Description	Default
`identifier`	`int`	Non-negative OpenAL effect name.	required

Returns:

Type	Description
`Effect`	Context-affine typed effect.

Raises:

Type	Description
`TypeError`	`identifier` is not an integer.
`ValueError`	`identifier` is negative.
`HandleClosedError`	This context is closed.

filter ¶

filter(identifier: int) -> Filter

Wrap an existing integer EFX filter identifier for this context.

This does not allocate a filter or verify that identifier is live.

Parameters:

Name	Type	Description	Default
`identifier`	`int`	Non-negative OpenAL filter name.	required

Returns:

Type	Description
`Filter`	Context-affine typed filter.

Raises:

Type	Description
`TypeError`	`identifier` is not an integer.
`ValueError`	`identifier` is negative.
`HandleClosedError`	This context is closed.

auxiliary_effect_slot ¶

auxiliary_effect_slot(
    identifier: int,
) -> AuxiliaryEffectSlot

Wrap an existing EFX auxiliary-slot identifier for this context.

This does not allocate a slot or verify that identifier is live.

Parameters:

Name	Type	Description	Default
`identifier`	`int`	Non-negative OpenAL auxiliary effect slot name.	required

Returns:

Type	Description
`AuxiliaryEffectSlot`	Context-affine typed auxiliary effect slot.

Raises:

Type	Description
`TypeError`	`identifier` is not an integer.
`ValueError`	`identifier` is negative.
`HandleClosedError`	This context is closed.

register_event_callback ¶

register_event_callback(
    callback: EventCallback,
    *,
    event_types: Sequence[int] = (),
) -> CallbackRegistration

Register and retain an AL_SOFT_events callback.

The callback receives (event_type, object_id, parameter, message). Registering another event callback on this context closes the previous registration. Python exceptions are retained instead of crossing the C boundary.

Parameters:

Name	Type	Description	Default
`callback`	`EventCallback`	Function invoked for enabled AL events.	required
`event_types`	`Sequence[int]`	Registry event-type values to enable. An empty sequence installs the callback without explicitly enabling event types.	`()`

Returns:

Type	Description
`CallbackRegistration`	Owned registration that keeps the native trampoline alive.

Raises:

Type	Description
`TypeError`	`callback` is not callable or an event type is not integer-like.
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	`AL_SOFT_events` is unavailable.
`CallbackControlError`	The previous callback cannot be removed safely.
`ContextActivationError`	This context cannot be activated or restored.

register_debug_callback ¶

register_debug_callback(
    callback: DebugCallback, *, enable_output: bool = True
) -> CallbackRegistration

Register and retain an AL_EXT_debug message callback.

The callback receives (source, type, identifier, severity, message). Registering another debug callback on this context closes the previous registration. Python exceptions are retained by the registration.

Parameters:

Name	Type	Description	Default
`callback`	`DebugCallback`	Function invoked for native debug messages.	required
`enable_output`	`bool`	Enable `AL_DEBUG_OUTPUT_EXT` for the registration and restore its previous disabled state when the registration closes.	`True`

Returns:

Type	Description
`CallbackRegistration`	Owned registration that keeps the native trampoline alive.

Raises:

Type	Description
`TypeError`	`callback` is not callable.
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	`AL_EXT_debug` is unavailable.
`CallbackControlError`	The previous callback cannot be removed safely.
`ContextActivationError`	This context cannot be activated or restored.

register_buffer_callback ¶

register_buffer_callback(
    buffer: Buffer | int,
    format: ALFormat | int,
    frequency: int,
    callback: BufferCallback,
) -> CallbackRegistration

Register a lifetime-safe AL_SOFT_callback_buffer callback.

The callback receives a writable byte view valid only for that callback invocation and returns the number of bytes written. Exceptions and invalid byte counts are retained and reported to OpenAL as zero bytes. Python callback execution is not guaranteed to satisfy hard real-time constraints.

Registering again for the same buffer closes the prior registration. Successful installation replaces retained static-buffer storage. Closing can fail while the buffer remains attached to a source; in that case the registration retains its native trampoline until cleanup can be retried or the context closes.

Parameters:

Name	Type	Description	Default
`buffer`	`Buffer \| int`	Positive integer buffer name or typed buffer from this context.	required
`format`	`ALFormat \| int`	OpenAL sample-format value produced by the callback.	required
`frequency`	`int`	Positive sample rate in frames per second.	required
`callback`	`BufferCallback`	Function that fills the temporary writable view and returns a byte count from zero through the view length.	required

Returns:

Type	Description
`CallbackRegistration`	Owned registration that keeps the native trampoline alive.

Raises:

Type	Description
`TypeError`	A value has the wrong type or `callback` is not callable.
`ValueError`	The buffer belongs to another context or an integer value is outside its supported range.
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	`AL_SOFT_callback_buffer` is unavailable.
`CallbackControlError`	Native callback installation, replacement, or rollback cannot be completed safely.
`ContextActivationError`	This context cannot be activated or restored.

start_foldback ¶

start_foldback(
    mode: ALFoldbackMode | int,
    count: int,
    length: int,
    memory: object,
    callback: FoldbackCallback,
) -> FoldbackRegistration

Start an owned AL_EXT_FOLDBACK request.

The callback receives (event_type, block_index). Starting another request closes the prior foldback registration. The returned registration retains both the native trampoline and the exact writable sample backing.

Parameters:

Name	Type	Description	Default
`mode`	`ALFoldbackMode \| int`	`AL_FOLDBACK_MODE_MONO` or `AL_FOLDBACK_MODE_STEREO`.	required
`count`	`int`	Number of sample blocks; at least two.	required
`length`	`int`	Positive number of frames in each block.	required
`memory`	`object`	Writable `ALfloat` ctypes array, writable contiguous byte buffer, or numeric sequence. Sequences are copied to retained native storage.	required
`callback`	`FoldbackCallback`	Function invoked for foldback start, block, and stop events.	required

Returns:

Type	Description
`FoldbackRegistration`	Owned foldback registration exposing the retained sample memory.

Raises:

Type	Description
`TypeError`	A value has the wrong type, storage is not writable and contiguous, or `callback` is not callable.
`ValueError`	The mode, dimensions, or storage capacity is invalid.
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	`AL_EXT_FOLDBACK` is unavailable.
`CallbackControlError`	A previous foldback request cannot close safely.
`NativeCallError`	OpenAL reports an error before or during startup.
`ContextActivationError`	This context cannot be activated or restored.

set_static_buffer_data ¶

set_static_buffer_data(
    buffer: Buffer | int,
    format: ALFormat | int,
    data: bytes | bytearray | memoryview,
    frequency: int,
) -> None

Set AL_EXT_STATIC_BUFFER data and retain its native backing.

Writable bytearray and memoryview inputs are borrowed without a copy and must not be resized while retained. Immutable or read-only input is copied into native storage. The backing remains alive until this buffer is updated again or the context closes. An active callback on the buffer is closed before static storage is installed.

Parameters:

Name	Type	Description	Default
`buffer`	`Buffer \| int`	Positive integer buffer name or typed buffer from this context.	required
`format`	`ALFormat \| int`	OpenAL sample-format value.	required
`data`	`bytes \| bytearray \| memoryview`	Contiguous PCM bytes to retain or copy.	required
`frequency`	`int`	Positive sample rate in frames per second.	required

Raises:

Type	Description
`TypeError`	A value has the wrong type or `data` is not contiguous.
`ValueError`	The buffer belongs to another context or an integer value is outside its supported range.
`HandleClosedError`	This context is closed.
`ExtensionUnavailableError`	`AL_EXT_STATIC_BUFFER` is unavailable.
`CallbackControlError`	An existing buffer callback cannot be removed.
`NativeCallError`	OpenAL has a pre-existing error or rejects the update.
`ContextActivationError`	This context cannot be activated or restored.

close ¶

close() -> None

Stop foldback, detach, and destroy the native context.

Closing an already closed context is harmless. Active callbacks are marked closed after native context destruction, and retained static-buffer storage is released. All typed objects bound to the context become unusable.

Raises:

Type	Description
`CallbackControlError`	Foldback or callback cleanup cannot complete.
`NativeCallError`	OpenAL rejects an active foldback stop request.
`ContextActivationError`	The context cannot be detached before destruction.

pyalsoft.bindings.open_device ¶

open_device(
    name: str | bytes | None = None,
    *,
    library: OpenALLibrary | None = None,
    path: LibraryPath | None = None,
) -> PlaybackDevice

Open an owned playback device.

Parameters:

Name	Type	Description	Default
`name`	`str \| bytes \| None`	Device specifier as text or encoded bytes. `None` selects the implementation's default playback device.	`None`
`library`	`OpenALLibrary \| None`	Existing loaded library to use.	`None`
`path`	`LibraryPath \| None`	Shared-library path to load when `library` is omitted.	`None`

Returns:

Type	Description
`PlaybackDevice`	Open playback device that owns contexts created through it.

Raises:

Type	Description
`TypeError`	`name` or `path` has an unsupported type.
`ValueError`	`library` and `path` are both supplied.
`DeviceOpenError`	OpenAL cannot be loaded or the requested device cannot be opened.

pyalsoft.bindings.open_loopback_device ¶

open_loopback_device(
    name: str | bytes | None = None,
    *,
    library: OpenALLibrary | None = None,
    path: LibraryPath | None = None,
) -> LoopbackDevice

Open an owned ALC_SOFT_loopback device.

Parameters:

Name	Type	Description	Default
`name`	`str \| bytes \| None`	Device specifier as text or encoded bytes. `None` selects the implementation's default loopback device.	`None`
`library`	`OpenALLibrary \| None`	Existing loaded library to use.	`None`
`path`	`LibraryPath \| None`	Shared-library path to load when `library` is omitted.	`None`

Returns:

Type	Description
`LoopbackDevice`	Open loopback device for context creation and offline rendering.

Raises:

Type	Description
`TypeError`	`name` or `path` has an unsupported type.
`ValueError`	`library` and `path` are both supplied.
`DeviceOpenError`	OpenAL cannot be loaded or a loopback device cannot open.
`ExtensionUnavailableError`	`ALC_SOFT_loopback` is unavailable.

pyalsoft.bindings.open_capture_device ¶

open_capture_device(
    frequency: int,
    format: ALFormat | int,
    buffer_size: int,
    name: str | bytes | None = None,
    *,
    library: OpenALLibrary | None = None,
    path: LibraryPath | None = None,
) -> CaptureDevice

Open an owned core ALC capture device.

buffer_size controls the native capture ring capacity; it is measured in sample frames, not bytes.

Parameters:

Name	Type	Description	Default
`frequency`	`int`	Positive capture sample rate in frames per second.	required
`format`	`ALFormat \| int`	Core OpenAL mono or stereo sample-format value.	required
`buffer_size`	`int`	Positive native capture-buffer capacity in sample frames.	required
`name`	`str \| bytes \| None`	Device specifier as text or encoded bytes. `None` selects the implementation's default capture device.	`None`
`library`	`OpenALLibrary \| None`	Existing loaded library to use.	`None`
`path`	`LibraryPath \| None`	Shared-library path to load when `library` is omitted.	`None`

Returns:

Type	Description
`CaptureDevice`	Open capture device with explicit start, stop, and read operations.

Raises:

Type	Description
`TypeError`	A name, path, format, frequency, or buffer size has an unsupported type.
`ValueError`	A size is non-positive or `library` and `path` are both supplied.
`DeviceOpenError`	OpenAL cannot be loaded or the requested capture device cannot be opened.

Callback types and registrations¶

Typed low-level bindings and runtime loading for OpenAL Soft.

pyalsoft.bindings.EventCallback ¶

EventCallback = Callable[[int, int, int, str], None]

An AL_SOFT_events callback receiving type, object, parameter, and message.

pyalsoft.bindings.DebugCallback ¶

DebugCallback = Callable[[int, int, int, int, str], None]

An AL_EXT_debug callback receiving source, type, ID, severity, and message.

pyalsoft.bindings.SystemEventCallback ¶

SystemEventCallback = Callable[
    [int, int, object | None, str], None
]

An ALC system callback receiving event type, device type, handle, and message.

pyalsoft.bindings.BufferCallback ¶

BufferCallback = Callable[[memoryview], int]

A buffer callback that fills a temporary writable view and returns bytes used.

pyalsoft.bindings.FoldbackCallback ¶

FoldbackCallback = Callable[[int, int], None]

A foldback callback receiving the event type and completed block index.

pyalsoft.bindings.CallbackRegistration ¶

Own a native callback and unregister it deterministically.

Native audio callbacks must never allow a Python exception to cross the C boundary. Exceptions are retained and can be observed through errors or re-raised in an application-controlled thread with raise_if_failed.

Do not construct instances directly. Registration helpers return them after installing and retaining the native ctypes trampoline. Use a with statement or call close deterministically; losing the Python reference does not unregister the native callback.

Attributes:

Name	Type	Description
`closed`	`bool`	Whether unregistration completed.
`errors`	`tuple[BaseException, ...]`	Snapshot of exceptions retained from callback invocations or callback-control cleanup.

closed `property` ¶

closed: bool

Whether the callback has been unregistered.

errors `property` ¶

errors: tuple[BaseException, ...]

Exceptions raised by the Python callback, in arrival order.

raise_if_failed ¶

raise_if_failed() -> None

Raise and clear exceptions retained from native callback threads.

Raises:

Type	Description
`BaseExceptionGroup`	One or more retained callback exceptions. The retained list is cleared before the group is raised.

close ¶

close() -> None

Unregister the callback and wait for in-flight invocations.

Calling this more than once is harmless. If native unregistration fails, the registration remains open so cleanup can be retried. A callback must never close its own registration.

Raises:

Type	Description
`CallbackControlError`	Called from this registration's callback or re-entered on the thread already closing it.

pyalsoft.bindings.FoldbackRegistration ¶

Bases: CallbackRegistration

Own an active foldback request and its writable sample storage.

Do not construct instances directly. Context.start_foldback returns this specialization. The public memory attribute is the exact ALfloat backing passed to OpenAL and remains available after closure.

Attributes:

Name	Type	Description
`memory`		Retained writable `ALfloat` storage containing foldback samples.
`stopping`	`bool`	Whether a native stop was requested but has not completed.
`closed`	`bool`	Whether the native STOP event was received and cleanup completed.
`errors`	`tuple[BaseException, ...]`	Exceptions retained from the callback or stop preparation.

stopping `property` ¶

stopping: bool

Whether native foldback stop has been requested.

close ¶

close() -> None

Request foldback stop and wait for the native STOP event.

Calling this after closure is harmless. OpenAL provides no timeout for the STOP notification, so this call waits until the native implementation delivers it and all in-flight callbacks return.

Raises:

Type	Description
`CallbackControlError`	Called from the foldback callback or re-entered on the thread already closing it.
`NativeCallError`	OpenAL rejects the stop request.

Exceptions¶

Typed low-level bindings and runtime loading for OpenAL Soft.

pyalsoft.bindings.OpenALError ¶

Bases: Exception

Base exception for loading or resolving OpenAL functions.

pyalsoft.bindings.LibraryNotFoundError ¶

Bases: OpenALError

Raised when no usable OpenAL shared library can be loaded.

pyalsoft.bindings.FunctionUnavailableError ¶

Bases: OpenALError

Raised when an OpenAL function has no usable entry point.

pyalsoft.bindings.ExtensionUnavailableError ¶

Bases: FunctionUnavailableError

Raised when the current implementation does not expose an extension.

pyalsoft.bindings.ContextRequiredError ¶

Bases: FunctionUnavailableError

Raised when resolving a function requires a current AL context.

pyalsoft.bindings.ContextMismatchError ¶

Bases: ValueError

Raised when typed AL objects from different contexts are combined.

pyalsoft.bindings.ALCHandleError ¶

Bases: OpenALError

Base exception for owned ALC device and context handles.

pyalsoft.bindings.DeviceOpenError ¶

Bases: ALCHandleError

Raised when an ALC device cannot be opened.

pyalsoft.bindings.DeviceCloseError ¶

Bases: ALCHandleError

Raised when an ALC device refuses to close.

pyalsoft.bindings.ContextCreateError ¶

Bases: ALCHandleError

Raised when an ALC context cannot be created.

pyalsoft.bindings.ContextActivationError ¶

Bases: ALCHandleError

Raised when an ALC context cannot be made current or restored.

pyalsoft.bindings.HandleClosedError ¶

Bases: ALCHandleError

Raised when an operation requires an open device or context.

pyalsoft.bindings.NativeCallError ¶

Bases: ALCHandleError

Raised when a lifetime-sensitive native operation reports an error.

pyalsoft.bindings.CallbackControlError ¶

Bases: NativeCallError

Raised when native callback state cannot be enabled or removed safely.

Owned backend API reference¶

Library loading and extensions¶

pyalsoft.bindings.LibraryPath ¶

pyalsoft.bindings.ForeignFunction ¶

pyalsoft.bindings.OpenALLibrary ¶

native_library property ¶

al property ¶

alc property ¶

extensions property ¶

get_export ¶

clear_extension_cache ¶

register_system_event_callback ¶

clear_system_event_callback ¶

is_al_extension_present ¶

is_alc_extension_present ¶

get_al_extension ¶

get_alc_extension ¶

get_function ¶

pyalsoft.bindings.Extension ¶

name property ¶

apis property ¶

commands property ¶

enums property ¶

types property ¶

dependencies property ¶

is_present ¶

require ¶

get_function ¶

pyalsoft.bindings.load ¶

Owned devices and contexts¶

pyalsoft.bindings.Device ¶

closed property ¶

handle property ¶

name property ¶

extensions property ¶

version property ¶

connected property ¶

hrtf_enabled property ¶

hrtf_status property ¶

hrtf_name property ¶

hrtf_specifier_count property ¶

output_limiter_enabled property ¶

device_clock property ¶

device_latency property ¶

clock_latency property ¶

output_mode property ¶

max_ambisonic_order property ¶

context_flags property ¶

require_extension ¶

is_extension_present ¶

get_string ¶

get_integers ¶

get_integer ¶

get_integer64s ¶

get_hrtf_specifier ¶

close ¶

pyalsoft.bindings.PlaybackDevice ¶

create_context ¶

pyalsoft.bindings.LoopbackDevice ¶

is_render_format_supported ¶

render_samples ¶

pyalsoft.bindings.CaptureDevice ¶

available_samples property ¶

name property ¶

capturing property ¶

start ¶

stop ¶

read_samples ¶

close ¶

pyalsoft.bindings.Context ¶

closed property ¶

handle property ¶

current property ¶

listener property ¶

vendor property ¶

version property ¶

renderer property ¶

extensions property ¶

doppler_factor property writable ¶

doppler_velocity property writable ¶

native_library `property` ¶

al `property` ¶

alc `property` ¶

extensions `property` ¶

name `property` ¶

apis `property` ¶

commands `property` ¶

enums `property` ¶

types `property` ¶

dependencies `property` ¶

closed `property` ¶

handle `property` ¶

name `property` ¶

extensions `property` ¶

version `property` ¶

connected `property` ¶

hrtf_enabled `property` ¶

hrtf_status `property` ¶

hrtf_name `property` ¶

hrtf_specifier_count `property` ¶

output_limiter_enabled `property` ¶

device_clock `property` ¶

device_latency `property` ¶

clock_latency `property` ¶

output_mode `property` ¶

max_ambisonic_order `property` ¶

context_flags `property` ¶

available_samples `property` ¶

name `property` ¶

capturing `property` ¶

closed `property` ¶

handle `property` ¶

current `property` ¶

listener `property` ¶

vendor `property` ¶

version `property` ¶

renderer `property` ¶

extensions `property` ¶

doppler_factor `property` `writable` ¶

doppler_velocity `property` `writable` ¶

speed_of_sound `property` `writable` ¶

distance_model `property` `writable` ¶

default_filter_order `property` ¶

closed `property` ¶

errors `property` ¶

stopping `property` ¶