web-audio-api 0.3.1

A Rust/Python implementation of the Web Audio API, for use in non-browser contexts

Python bindings for web-audio-api-rs

A Rust/Python implementation of the Web Audio API, for use in non-browser contexts.

Usage

Install from PyPI:

pip install web-audio-api

Create a simple audio context and start an oscillator:

import web_audio_api

ctx = web_audio_api.AudioContext()
osc = ctx.createOscillator()
osc.frequency.value = 300
osc.connect(ctx.destination)
osc.start()

Examples

Runnable example scripts live in examples:

• examples/osc_gain.py: simple oscillator through a gain node
• examples/worklet_white_noise.py: AudioWorklet white noise with message-based volume changes
• examples/analyser_meter.py: analyser-based terminal level meter
• examples/buffer_source.py: build and play a short buffer
• examples/mic_input.py: microphone input into a graph
• examples/recorder.py: record graph output to a WAV file

Run an example after maturin develop:

.venv/bin/python examples/osc_gain.py

Advanced usage

The binding now exposes asyncio-native awaitables for the Web Audio methods that are async in web-audio-api-rs.

This includes:

• AudioContext.resume()
• AudioContext.suspend()
• AudioContext.close()
• OfflineAudioContext.startRendering()
• OfflineAudioContext.resume()
• OfflineAudioContext.suspend(suspendTime)
• BaseAudioContext.decodeAudioData(...)

Use them inside a running event loop:

import asyncio
import web_audio_api


async def main():
    ctx = web_audio_api.AudioContext({"sinkId": "none"})
    await ctx.resume()
    await ctx.suspend()
    await ctx.close()


asyncio.run(main())

Offline rendering is also async:

import asyncio
import web_audio_api


async def main():
    ctx = web_audio_api.OfflineAudioContext(1, 2_000, 2_000.0)
    src = ctx.createConstantSource()
    src.offset.value = 0.25
    src.connect(ctx.destination)
    src.start(0.25)
    src.stop(0.75)

    rendered = await ctx.startRendering()
    data = rendered.getChannelData(0)
    print(data[:8])


asyncio.run(main())

decodeAudioData(...) returns an awaitable and also accepts optional callbacks:

import asyncio
import pathlib
import web_audio_api


async def main():
    ctx = web_audio_api.OfflineAudioContext(1, 128, 44_100.0)
    audio_bytes = pathlib.Path("example.wav").read_bytes()

    def success(buffer):
        print(buffer.length, buffer.sampleRate)

    buffer = await ctx.decodeAudioData(audio_bytes, successCallback=success)
    print(buffer.numberOfChannels)


asyncio.run(main())

One practical detail: create these awaitables inside the running loop. In other words, prefer asyncio.run(main()) with the Web Audio calls inside main(), instead of constructing an awaitable earlier and awaiting it later.

Local development

Create and activate a virtual environment:

uv venv --python 3.11 .venv
source .venv/bin/activate

Install the development build into the active environment:

.venv/bin/python -m pip install maturin
maturin develop

Try the binding:

import web_audio_api
ctx = web_audio_api.AudioContext()
osc = ctx.createOscillator()
osc.connect(ctx.destination)
osc.start()
osc.frequency.value = 300

The scripts in examples are a good next step after this quick smoke test.

Build

Build a wheel:

.venv/bin/python -m pip wheel . --no-deps --wheel-dir dist

Test

Run the Rust tests:

cargo test

Run the Python tests against an installed wheel:

maturin develop
.venv/bin/python -m unittest discover -s tests

Release

Update the version in pyproject.toml. Create and push a tag matching the release version:

git tag v0.1.0
git push origin main
git push origin v0.1.0

Pushing the tag triggers the GitHub Actions release workflow, which builds the release artifacts and uploads them to PyPI.