omi_audio

Renderer-agnostic spatial audio for Python, built natively on the glTF KHR_audio_emitter data model — which is the Web Audio PannerNode model. Emitters have a distance curve, an optional directional cone and a gain; a listener hears them panned about its own forward axis. The mixing is a fixed voice pool summed in NumPy.

• NumPy is the only hard dependency. No graphics library, no scenegraph, no audio library is required to mix.
• miniaudio is optional — it decodes files and reaches the sound card. Without it the library still mixes and simply stays silent.
• Ogg Opus decodes too, through the optional opus extra. miniaudio does not read it, so the container is demultiplexed here from the published RFCs and the codec is libopus.
• Nothing here is copyleft, and neither is anything it depends on: miniaudio and every decoder it bundles are MIT or public domain, and the Opus chain — libopus, the opuslib bindings, the wheel that carries them — is BSD-3-Clause throughout. The convenient wrappers are not: libsndfile, PyAV and pydub via ffmpeg are LGPL or worse and cannot be a dependency here, whatever they would save.
• Silence is a backend. A missing package, a device that will not open, or a machine with no audio hardware all end in one warning and a NullDevice. open_device() cannot raise.
• The audio thread never allocates, blocks, decodes or logs. Pre-allocated buffers, NumPy out= everywhere, and a lock the mixing never takes.
• A document's uri is never resolved here. A glTF file comes from somebody you have never met; deciding what one of its strings is allowed to mean is the application's call, not a library's. See AudioLibrary.

⚠️ This code is largely LLM-written. It has a test suite, but it comes with no guarantees of correctness, accuracy, or fitness for any purpose (see LICENSE, MIT). Review it before relying on it for anything that matters.

Install

pip install omi_audio                # mixing only (NumPy)
pip install "omi_audio[playback]"    # + miniaudio, for files and a sound card
pip install "omi_audio[opus]"        # + Ogg Opus decoding

The opus extra carries a libopus inside its wheel for Linux, macOS and Windows, about 330 KB. A libopus already on the system is used where the extra is absent, which covers most Linux desktops — but it is not a component Windows or macOS ships, so relying on the system alone would decode on one platform and quietly fail on the others.

Quick start

from omi_audio import AudioEngine, model, synth

engine = AudioEngine()                      # opens a device, or silence

# A sound with no file behind it, so this runs anywhere.
engine.clips.put('ping', synth.impact(0.4, seed=1))

emitter = model.AudioEmitter(
    gain=0.8,
    positional=model.PositionalProperties(refDistance=2.0, rolloffFactor=1.0),
)

handle = engine.play('ping', emitter=emitter, position=(3.0, 0.0, -5.0))

Run it for real, with no assets and no sound card required:

python examples/orbit.py            # a sound orbits the listener for ten seconds
python examples/orbit.py --silent   # never opens a device, still prints levels

Each frame, move the listener and re-aim whatever is still playing. A moving sound is re-aimed, never restarted: aim() writes two floats and the mixer ramps to them across the next block.

engine.listen(camera)                       # anything with .position/.quaternion
engine.aim(handle, emitter, position=emitter_world_position)

Testing without a sound card

Everything below the device is arithmetic over arrays, so build an engine on a NullDevice and assert on the mix:

from omi_audio import AudioEngine, NullDevice, synth

engine = AudioEngine(device=NullDevice(sample_rate=8000), voices=8)
engine.mixer.play(synth.tone(440.0, 1.0, sample_rate=8000), pan=1.0)
block = engine.mixer.mix(64)                # (64, 2) float32
assert block[:, 0].max() < 1e-9             # nothing in the left ear
assert block[:, 1].max() > 0.1              # and plenty in the right

The pieces

In the order sound travels through them:

Deeper documentation is in docs/ — start with GAME-INTEGRATION.md if you are building something, or SPATIALISATION.md for every gain curve with a diagram of each, generated from the code that implements it.

What this does not do

Stated up front, because finding out later is worse:

• Stereo only, and the pan carries azimuth alone. A sound directly overhead and one dead ahead are indistinguishable. Height needs an HRTF and surround needs more than two channels; neither is here.
• No reverb, occlusion or doppler. muffle is the only effect, and it is a master-bus low-pass.
• No streaming. Clips are decoded whole into memory.
• No scheduling. Nothing here has a clock; autoplay starts when your application says the scene has begun.

Using it from a scenegraph

omi_audio is deliberately ignorant of scenegraphs: it is handed world positions, a listener pose and clips. OpenGLContext is the reference integration — AudioEmitter, AudioSource and VRML97's Sound nodes, a per-context engine driven once a frame from the render pass, and a glTF loader that reads KHR_audio_emitter blocks straight into this model.

Contributing, changes, security

• CONTRIBUTING.md — how to run the gates, and the two rules with teeth (the audio thread, and the untrusted document).
• CHANGELOG.md
• SECURITY.md — the threat model, and why your resolver is the boundary.

Licence

MIT. Note that some jurisdictions do not allow for LLM generated code to have a copyright, as such this library may be in the Public Domain in your jurisdiction. There is NO warranty of any kind on the software.

See LICENSE.