omi-audio 0.1.0a1__tar.gz

omi_audio-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+Notable changes to `omi_audio`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+follows [semantic versioning](https://semver.org/) — with the usual caveat that
+`0.x` makes no compatibility promise, and this is an alpha.
+
+## [Unreleased]
+
+## [0.1.0a1] — 2026-07-31
+
+**Initial public release.** An alpha: the API may still move
+
+### The package
+
+Renderer-agnostic spatial audio built natively on glTF's `KHR_audio_emitter`
+model — which is the Web Audio `PannerNode` model — and mixed in NumPy. NumPy is
+the only hard dependency; `miniaudio` is an optional extra for decoding files
+and reaching a sound card, and without it the library still mixes and stays
+silent.
+
+### What is in it
+
+- **The data model** (`model`) — `KHR_audio_emitter` as plain dataclasses, field
+  for field, with the extension's own names and defaults. `from_gltf` /
+  `to_gltf` round-trip, and `from_gltf` never raises whatever a third-party
+  document contains. Node and scene emitter references are read, so a positional
+  emitter can be located.
+- **Resolving a document's audio** (`library`) — `AudioLibrary` holds what one
+  document's `audio` array has resolved to. **A `uri` is never resolved, opened
+  or interpreted by this package**: the application supplies a `fetch` callback,
+  because only it knows where its content lives and what a third-party document
+  may reach. Audio arrives as a local file, as bytes, or as an already-decoded
+  clip — so `bufferView` audio (every `.glb`) and `data:` URIs play, and a
+  download that lands three frames later is an ordinary silence until it does.
+- **Spatialisation** (`spatial`) — the extension's three distance models
+  implemented as written, the Web Audio cone, equal-power stereo panning with
+  the behind-the-listener fold, and VRML97's two ellipsoids for `Sound` nodes,
+  which nothing else can express. Every curve is a pure function of geometry.
+- **Clips** (`clip`) — encoded audio decoded to mono float32 at one rate, from a
+  file or from bytes, decoded once and cached by name.
+- **The mixer** (`mixer`) — a fixed voice pool summed into stereo blocks:
+  allocation-free, lock-free on the audio thread, priority-based voice stealing,
+  per-block gain ramping, and an underwater low-pass.
+- **The device seam** (`device`) — `miniaudio`, or silence. A missing package, a
+  device that will not open and a machine with no audio hardware all end in one
+  warning and a `NullDevice`; `open_device()` cannot raise.
+- **The engine** (`engine`) — the one object an application holds, keeping
+  decoding and path resolution off the audio thread.
+- **Synthesised sounds** (`synth`) — tones, chirps, noise and impacts made out of
+  arithmetic, so a demo or a test needs no assets and no licences.
+
+### Known limitations
+
+Stated here because finding them out later is worse:
+
+- **Stereo only**, and the pan carries azimuth alone — a sound overhead and one
+  dead ahead are indistinguishable. Height needs an HRTF, surround needs more
+  than two channels, and neither is implemented.
+- **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, so `autoplay` starts when the
+  application says its scene has begun.
+- **`maxDistance` follows the extension's formulas, not its prose** — the two
+  disagree, and only the `linear` model uses it. `PositionalProperties.in_range()`
+  is the other reading, kept explicit. See
+  [SPATIALISATION.md](docs/SPATIALISATION.md#maxdistance-means-two-different-things-and-this-library-picks-one).
+
+### Quality of the release
+
+- 435 tests, 99% branch coverage, `ruff` and `mypy --strict` clean, all gated in
+  CI across Python 3.10–3.15 with and without the optional backend.
+- `py.typed` shipped, so the annotations are a promise downstream type checkers
+  can use.
+- **Largely LLM-written**, and the README, the package docstring and
+  [SECURITY.md](SECURITY.md) all say so. Review it before relying on it for
+  anything that matters.
+
+[Unreleased]: https://github.com/mcfletch/omi_audio/compare/v0.1.0a1...HEAD
+[0.1.0a1]: https://github.com/mcfletch/omi_audio/releases/tag/v0.1.0a1

omi_audio-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# Contributing
+
+Bug reports, questions and patches all welcome. This file is short because the
+rules that matter are few.
+
+## Getting set up
+
+```bash
+git clone https://github.com/mcfletch/omi_audio
+cd omi_audio
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+That runs the whole suite in under a second. `miniaudio` comes in with the
+`dev` extra; without it the package still works and simply stays silent, which
+is a path the suite exercises on purpose.
+
+## Before you open a pull request
+
+```bash
+ruff check .                 # lint
+mypy --strict src/omi_audio  # types
+pytest --cov --cov-branch    # tests, with the coverage floor
+```
+
+or, all of it the way CI does:
+
+```bash
+tox -e lint,typecheck,py312-playback,py312-nobackend
+```
+
+All three are gates. A merge needs them green.
+
+## What the code is held to
+
+This is a small library that other people are meant to read, so:
+
+- **Tests come first, and they must fail before they pass.** Write the assertion,
+  watch it go red, then make it green. A test written after the code often only
+  proves the code does what it does.
+- **A test must be able to fail for the reason it is named after.** `assert
+  handle is not None` in a test called *the source's gain is applied* is not a
+  test of the gain. If you are unsure a test is real, break the thing it covers
+  and check that it notices.
+- **Docstrings explain *why*, not *what*.** The signature says what. The
+  docstring says what problem this shape avoids, in prose, and names the failure
+  it is designed against. That habit is the most valuable thing in this
+  codebase; please keep it up.
+- **Documentation ships with the change, not after it.** A new option, a changed
+  default, a new file format, a changed public API — none is finished while
+  `docs/` still describes the old world. Say in your pull request which
+  documentation you changed, and if you changed none, say that and why.
+- **`%`-formatting, not f-strings**, matching the surrounding code and required
+  by the logging calls (`log.warning('%s', x)` defers the work until somebody is
+  listening). `ruff` is configured accordingly.
+
+## Two rules with teeth
+
+### The audio thread
+
+Everything in `mixer.py` from `mix()` down runs on the device's own thread.
+There it must **not allocate, block, decode, resolve a path, take a lock, or
+log**. An allocation on the audio thread is a garbage collection on the audio
+thread, and that is an audible gap.
+
+Pre-allocate in `__init__` and write with NumPy's `out=`. Two tests assert this
+under `tracemalloc`; if you make them fail, the answer is to allocate less, not
+to raise the threshold.
+
+There is exactly one sanctioned exception, and it is documented where it lives:
+the oversized-block path may grow its silence buffer, once per size, on a path
+that is already broken.
+
+Numbers crossing *onto* the thread are checked on the control side, where it is
+free — see `_finite()`. A NaN gain survives `np.clip` and every voice shares one
+buffer, so one bad emitter would otherwise silence the whole scene.
+
+### The document is not trusted
+
+`omi_audio` consumes glTF from third parties. A `uri` is **never** resolved,
+opened or interpreted here; that is the application's job, through
+`AudioLibrary`. `model.from_gltf()` must never raise and must never let a value
+of the wrong type into the model. See [SECURITY.md](SECURITY.md).
+
+## Changing a gain curve
+
+The diagrams in `docs/images/` are generated from `omi_audio.spatial` by
+`docs/make_diagrams.py`, and `tests/test_diagrams.py` fails if the committed
+files stop matching. So:
+
+```bash
+python docs/make_diagrams.py     # or: tox -e diagrams
+```
+
+and commit what changes. A picture of a gain curve is a claim about the code.
+
+## Releasing
+
+**Bumping the version is what cuts a release.** `.github/workflows/release.yml`
+runs on every push to `main`: it runs the whole test workflow, then reads
+`__version__` from `src/omi_audio/__init__.py` and asks PyPI whether that
+version exists. If it does, the push is an ordinary CI run and nothing is
+published. If it does not, the sdist and wheel are built and uploaded.
+
+So a release is:
+
+1. Update `CHANGELOG.md` under a new heading.
+2. Bump `__version__` in `src/omi_audio/__init__.py`.
+3. Merge to `main`.
+
+Nothing is published from a red build. PyPI versions are immutable, so a
+release number burned on a broken build cannot be taken back — which is why the
+publish job waits on every released Python, both backends, lint, types, the
+coverage floor and the docs build, and why the version check treats anything
+other than a clean 200 or 404 from PyPI as a reason to stop rather than to guess.
+
+The one check that is *not* binding is Python 3.15, which is still a
+prerelease. It runs on every push and its failures are visible, but a
+regression in a CPython beta is not a reason to hold up a merge or a release.
+Make it binding by moving `"3.15"` back into the `test` matrix in
+`.github/workflows/test.yml` and deleting the `prerelease` job.
+
+### One-time setup
+
+The workflow needs two things that do not live in this repository, and it
+cannot publish until both exist:
+
+**A PyPI trusted publisher** for this project — owner `mcfletch`, repository
+`omi_audio`, workflow `release.yml`, and the **environment field left blank**.
+The workflow uses no GitHub environment, so its OIDC claim carries none; a
+publisher that names one will not match, and the upload is rejected with an
+error that does not obviously say why.
+
+Before the first release the project does not exist on PyPI yet, so this has to
+be added as a *pending* publisher (PyPI → Your projects → Publishing).
+
+No API token is stored anywhere: the upload authenticates over OIDC. Note that
+without an environment there is no place to require a reviewer, so a green push
+to `main` with a new version publishes without anyone approving it — the version
+bump is the decision.
+
+## Licensing
+
+`omi_audio` is MIT, and everything it depends on is MIT or public domain. **Do
+not contribute code copied or translated from a GPL, LGPL, AGPL, SSPL or CC-BY-SA
+source**, in whole or in part. The `miniaudio` choice was made on exactly these
+grounds — the convenient alternatives (`libsndfile`, PyAV, `pydub`-via-ffmpeg)
+are copyleft — and the reasoning is recorded in `pyproject.toml` so it is
+not quietly undone.
+
+Behaviour taken from a published *specification* is fine and welcome; cite it
+from the docstring, as the existing code cites `KHR_audio_emitter`, the Web
+Audio API and ISO/IEC 14772-1.
+
+## A note on how this was written
+
+Much of this package is LLM-written, and it says so in the README. That is not a
+reason to hold a contribution to a lower standard — it is the reason the tests,
+the review in `docs/reviews/` and the gates above exist.

omi_audio-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike C. Fletcher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omi_audio-0.1.0a1/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include pyproject.toml
+include tox.ini
+recursive-include src/omi_audio py.typed
+recursive-include docs *.md *.py *.rst *.svg
+recursive-include examples *.py
+recursive-include tests *.py

omi_audio-0.1.0a1/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: omi_audio
+Version: 0.1.0a1
+Summary: Renderer-agnostic spatial audio on the glTF KHR_audio_emitter model, mixed in NumPy
+Author-email: "Mike C. Fletcher" <mcfletch@vrplumber.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mcfletch/omi_audio
+Project-URL: Repository, https://github.com/mcfletch/omi_audio
+Project-URL: Documentation, https://github.com/mcfletch/omi_audio/tree/main/docs
+Project-URL: Changelog, https://github.com/mcfletch/omi_audio/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mcfletch/omi_audio/issues
+Keywords: audio,spatial audio,3D sound,panning,mixer,OMI,glTF,KHR_audio_emitter,numpy,game
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Mixers
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Provides-Extra: playback
+Requires-Dist: miniaudio>=1.59; extra == "playback"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: miniaudio>=1.59; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: omi_audio[test]; extra == "dev"
+Requires-Dist: omi_audio[docs]; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# omi_audio
+
+Renderer-agnostic **spatial audio** for Python, built natively on the glTF
+[`KHR_audio_emitter`](https://github.com/omigroup/gltf-extensions/tree/main/extensions/2.0/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.
+- **Nothing here is copyleft**, and neither is anything it depends on:
+  `miniaudio` and every decoder it bundles are MIT or public domain.
+- **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`](docs/DATA-MODEL.md#getting-the-actual-audio-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`](LICENSE), MIT). Review it before relying on it for anything that
+> matters.
+
+## Install
+
+```bash
+pip install omi_audio                # mixing only (NumPy)
+pip install "omi_audio[playback]"    # + miniaudio, for files and a sound card
+```
+
+## Quick start
+
+```python
+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:
+
+```bash
+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.
+
+```python
+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:
+
+```python
+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:
+
+| Module | Answers |
+|---|---|
+| `model` | `KHR_audio_emitter` as typed records, with the extension's own field names and defaults; `from_gltf`/`to_gltf` round-trip, and the node/scene references that say where an emitter *is* |
+| `library` | What a document's audio references have resolved to — the seam where **your** resolver, not this library, decides what a `uri` means |
+| `spatial` | Every gain curve — three glTF distance models, the Web Audio cone, VRML97's two ellipsoids, equal-power panning — and the listener's pose |
+| `clip` | Encoded audio → mono float32 at one rate, from a file or from bytes (`.glb` buffer views, `data:` URIs, downloads), decoded once |
+| `synth` | Tones, chirps, noise and impacts made out of arithmetic, so demos and tests need no assets and no licences |
+| `mixer` | A fixed voice pool summed into stereo blocks: allocation-free, lock-free on the audio thread, priority stealing, gain ramping, an underwater low-pass |
+| `device` | Where blocks go — `miniaudio`, or silence |
+| `engine` | The one object an application holds |
+
+Deeper documentation is in [`docs/`](docs/README.md) — start with
+[**GAME-INTEGRATION.md**](docs/GAME-INTEGRATION.md) if you are building
+something, or [SPATIALISATION.md](docs/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](https://github.com/mcfletch/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](CONTRIBUTING.md) — how to run the gates, and the two rules
+  with teeth (the audio thread, and the untrusted document).
+- [CHANGELOG.md](CHANGELOG.md)
+- [SECURITY.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`](LICENSE).

omi_audio-0.1.0a1/README.md

@@ -0,0 +1,142 @@
+# omi_audio
+
+Renderer-agnostic **spatial audio** for Python, built natively on the glTF
+[`KHR_audio_emitter`](https://github.com/omigroup/gltf-extensions/tree/main/extensions/2.0/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.
+- **Nothing here is copyleft**, and neither is anything it depends on:
+  `miniaudio` and every decoder it bundles are MIT or public domain.
+- **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`](docs/DATA-MODEL.md#getting-the-actual-audio-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`](LICENSE), MIT). Review it before relying on it for anything that
+> matters.
+
+## Install
+
+```bash
+pip install omi_audio                # mixing only (NumPy)
+pip install "omi_audio[playback]"    # + miniaudio, for files and a sound card
+```
+
+## Quick start
+
+```python
+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:
+
+```bash
+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.
+
+```python
+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:
+
+```python
+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:
+
+| Module | Answers |
+|---|---|
+| `model` | `KHR_audio_emitter` as typed records, with the extension's own field names and defaults; `from_gltf`/`to_gltf` round-trip, and the node/scene references that say where an emitter *is* |
+| `library` | What a document's audio references have resolved to — the seam where **your** resolver, not this library, decides what a `uri` means |
+| `spatial` | Every gain curve — three glTF distance models, the Web Audio cone, VRML97's two ellipsoids, equal-power panning — and the listener's pose |
+| `clip` | Encoded audio → mono float32 at one rate, from a file or from bytes (`.glb` buffer views, `data:` URIs, downloads), decoded once |
+| `synth` | Tones, chirps, noise and impacts made out of arithmetic, so demos and tests need no assets and no licences |
+| `mixer` | A fixed voice pool summed into stereo blocks: allocation-free, lock-free on the audio thread, priority stealing, gain ramping, an underwater low-pass |
+| `device` | Where blocks go — `miniaudio`, or silence |
+| `engine` | The one object an application holds |
+
+Deeper documentation is in [`docs/`](docs/README.md) — start with
+[**GAME-INTEGRATION.md**](docs/GAME-INTEGRATION.md) if you are building
+something, or [SPATIALISATION.md](docs/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](https://github.com/mcfletch/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](CONTRIBUTING.md) — how to run the gates, and the two rules
+  with teeth (the audio thread, and the untrusted document).
+- [CHANGELOG.md](CHANGELOG.md)
+- [SECURITY.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`](LICENSE).