openal-py¶
Spatial audio for Python, with managed resources, streaming playback, and access
to the OpenAL object model. Use AudioEngine for everyday
playback, or work directly with devices, contexts, sources, and buffers when you
need more control.
Platform wheels bundle OpenAL Soft by default. The binding falls back to system OpenAL when the bundle is unavailable or detects no playback devices.
Installation¶
pip install openal-py
For FLAC, OGG, and other formats supported by SoundFile, install the optional decoder dependency:
pip install 'openal-py[soundfile]'
Mono/stereo 8-bit and 16-bit PCM WAV files work without this extra.
Play a sound¶
from openal_py import AudioEngine
with AudioEngine() as audio:
sound = audio.load("sound.wav")
voice = audio.play(sound, gain=0.8, position=(2, 0, -5))
voice.wait()
A Sound is a reusable audio asset. Each call to
play() creates a Voice with its
own position, gain, pitch, and playback controls. Closing the engine releases its
playback resources.
wait() is useful for small scripts. In an application loop, call
update() regularly and inspect voice.finished
instead of blocking. Engine operations run on the thread that created it.
Stream longer audio¶
Streaming decodes audio in chunks and reuses a bounded pool of OpenAL buffers:
import time
from openal_py import AudioEngine, SoundFileStream
with AudioEngine() as audio, SoundFileStream("music.flac") as stream:
with audio.play_stream(stream) as voice:
while voice.active:
audio.update()
time.sleep(0.01)
The engine refills streams during update(); it does not start a background
thread. Stream inputs are borrowed by default, so keep them open until playback
has stopped, as the nested resource blocks do above.
Subclass PCMStream to provide generated samples, an existing
decoder, or a queue fed by a producer. Supply a fixed format and sample rate, and
implement read_frames(count). Return complete PCM frames, empty bytes for EOF,
or None when data is temporarily unavailable. Reads must return promptly.
Explore the API¶
AudioEngine,Sound, andVoice: managed playback and reusable assets.PCMStream,SoundFileStream, andStreamingVoice: extensible streaming inputs and playback.Device,Context,Source, andBuffer: explicit OpenAL resource management. Usectx.activate()for context-dependent operations; resource blocks manage lifetime separately.Listener,Effect, andFilter: spatial audio and device-supported effects.LoopbackDeviceandCaptureDevice: offline rendering and audio capture where supported.
Browse the Examples for runnable scripts, including custom PCM streams and adapters for already-open SoundFile readers. Each page includes the source code and a download link.
Documentation
Demos¶
openal-explore: A PySide6 scene editor and spatial audio demo for
openal-py. The player stays at the centre while the world scrolls. Audio comes from stationary points or sources travelling along editable polylines.python-quake2: A port of the id Software Quake II engine (version 3.21) from C to Python.
Building these docs¶
From a source checkout with its build prerequisites available:
pip install '.[docs]'
ALSOFT_DRIVERS=null python -m sphinx -W -b html docs docs/_build/html
API documentation imports the compiled binding, so a usable OpenAL library must
be available. On Windows PowerShell, set $env:ALSOFT_DRIVERS = "null" before
running the python -m sphinx command. Generated HTML is written to
docs/_build/html/.