PyALSoft

PyALSoft provides function-oriented playback and capture APIs, plus typed bindings for OpenAL Soft. Wheels include the native OpenAL Soft runtime and static-audio decoder.

Read the documentation | Browse the API reference | View the examples

PyALSoft is an independent project and is not affiliated with or endorsed by the OpenAL Soft project.

Installation

PyALSoft requires Python 3.12 or later.

python -m pip install pyalsoft

Quick start

play starts a WAV, FLAC, MP3, or Ogg Vorbis file immediately and returns a control handle:

from pyalsoft import play

sound = play("sound.wav")
sound.wait()

Use play("sound.wav", spatialize=False) for player-attached or UI audio that should not receive positional, distance, Doppler, or HRTF processing.

The managed API also supports spatial audio, effects and filters, recording, streaming, typed device and context configuration, live device reconfiguration, HRTF profile selection, and explicit playback sessions. See the documentation for guides and the complete API reference.

The lower-level pyalsoft.bindings namespace exposes typed OpenAL, ALC, EFX, and extension bindings, together with owned device and context handles.

Contributing

Development occurs on the development branch. Create the locked environment with uv:

uv sync --python 3.12

Before submitting a change, run the core checks:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run python tools/generate_bindings.py --check
uv run python tools/sync_openal_soft.py --check
uv run mkdocs build --strict

Bindings and docs/reference.md are generated from the vendored OpenAL registry. See the repository tool guide for development and release commands.

Add an entry under Unreleased in the changelog for every notable user-facing change. Group entries under Added, Changed, Deprecated, Removed, Fixed, or Security, and describe the effect from the user's perspective. Internal refactors, tests, and formatting do not need entries.

For example:

## Unreleased

### Added

- Added reverse playback support to `PlayingSound`. (@BDraves)

### Fixed

- Prevented audio frames from shifting left when replacing a sound's filter.
  (@BDraves)

License

PyALSoft's original Python code is available under the MIT License. Bundled OpenAL Soft and other third-party components remain under their respective licenses. The distribution includes their license texts and a third-party notice.