simvx.core.audio_backend

Desktop audio backends for SimVX.

Three backends ship in this module:

  • MiniaudioBackend: the production path. Mixes audio natively via ma_engine (CFFI wrapper at simvx.core._native.miniaudio_engine). The native extension is built at uv pip install time by the PEP 517 build hook in packages/core/build_audio_ext_hook.py. If that build is skipped or fails, the runtime falls back to legacy.

  • _LegacyMiniaudioBackend: the pure-Python fallback. Mixes in a numpy generator callback driven by miniaudio.PlaybackDevice. Slower (target latency 100 ms vs 20 ms for the native path) and runs on the Python audio thread under the GIL, so it’s vulnerable to underruns from heavy main-thread frames.

  • NullAudioBackend: silent no-op backend used when no audio device is available (sandboxed CI, headless containers).

make_backend() resolution order, with loud warnings at every fallback (never silent degradation):

  1. Native MiniaudioBackend: picked when the extension is importable.

  2. Legacy _LegacyMiniaudioBackend: picked when native is unavailable AND a real audio device opens. Emits a one-time WARNING explaining the latency hit and the rebuild command.

  3. Null NullAudioBackend: picked when neither native nor legacy can start (no audio device). Emits a one-time WARNING.

Set SIMVX_ALLOW_LEGACY_AUDIO=0 to disable the legacy/null fallbacks and raise :class:AudioBackendUnavailable instead.

The runtime never invokes a C compiler. Use simvx build-audio (or uv pip install --reinstall -e packages/core) to (re)build the extension manually.

Package Contents

Functions

make_backend

Pick the best available audio backend, falling back loudly on failure.

Data

log

__all__

API

simvx.core.audio_backend.log

‘getLogger(…)’

simvx.core.audio_backend.__all__

[‘MiniaudioBackend’, ‘_LegacyMiniaudioBackend’, ‘NullAudioBackend’, ‘make_backend’]

simvx.core.audio_backend.make_backend(sample_rate: int = _DEFAULT_SAMPLE_RATE, nchannels: int = _DEFAULT_CHANNELS) → simvx.core.audio_backend._miniaudio.MiniaudioBackend | simvx.core.audio_backend._legacy._LegacyMiniaudioBackend | simvx.core.audio_backend._null.NullAudioBackend[source]

Pick the best available audio backend, falling back loudly on failure.

Resolution order (the runtime never invokes a C compiler: that’s the install-time build hook’s job):

  1. Native MiniaudioBackend (~20 ms latency). Selected when the compiled _simvx_miniaudio_engine extension imports cleanly.

  2. Legacy _LegacyMiniaudioBackend (~100 ms latency). Selected when native is unavailable AND SIMVX_ALLOW_LEGACY_AUDIO is not set to "0". Emits a one-time WARNING with rebuild instructions.

  3. Null NullAudioBackend (silent). Selected when neither native nor legacy can start: typically a sandboxed CI without an audio device. Emits another one-time WARNING.

Set SIMVX_ALLOW_LEGACY_AUDIO=0 to refuse the fallback chain and raise :class:AudioBackendUnavailable if the native extension is missing or fails to initialise.