simvx.core.audio_backend

Desktop audio backends for SimVX.

make_backend() picks one, and warns loudly at every fallback (never silent degradation):

  1. An accelerator’s backend. A distribution offers one through the simvx.audio.backends entry point group, whose register() passes a factory to :func:register_backend. simvx-audio-miniaudio offers MiniaudioBackend, which mixes, spatializes and runs the bus effects in native C through miniaudio’s ma_engine, at about 20 ms of latency.

  2. _LegacyMiniaudioBackend: the fallback. Mixes in a numpy generator callback driven by miniaudio.PlaybackDevice from the miniaudio distribution, which wraps the same C library but exposes only its device and decoder layer, not its engine. Mixing therefore happens in Python under the GIL on the audio thread, which is what forces the 100 ms buffer: 20 ms would underrun on any heavy main-thread frame. 3D players still work: the mixer applies the attenuation, pan and doppler pitch the nodes compute. Bus routing and gain work; bus effects are not applied.

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

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

Package Contents

Functions

register_backend

Offer an audio backend to :func:make_backend under name.

make_backend

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

Data

log

__all__

BACKEND_ENTRY_POINT_GROUP

API

simvx.core.audio_backend.log

‘getLogger(…)’

simvx.core.audio_backend.__all__

[‘BACKEND_ENTRY_POINT_GROUP’, ‘_LegacyMiniaudioBackend’, ‘NullAudioBackend’, ‘make_backend’, ‘regist…

simvx.core.audio_backend.BACKEND_ENTRY_POINT_GROUP

‘simvx.audio.backends’

simvx.core.audio_backend.register_backend(name: str, factory: collections.abc.Callable[..., simvx.core.audio_protocol.AudioPlaybackBackend]) → None[source]

Offer an audio backend to :func:make_backend under name.

Called by the register() a simvx.audio.backends entry point names. factory is called with sample_rate and nchannels keywords and returns a started backend, or raises when it cannot start. Registering a name again replaces its factory.

simvx.core.audio_backend.make_backend(sample_rate: int = _DEFAULT_SAMPLE_RATE, nchannels: int = _DEFAULT_CHANNELS) → simvx.core.audio_protocol.AudioPlaybackBackend[source]

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

Resolution order:

  1. An accelerator’s backend, registered through the simvx.audio.backends entry point group (MiniaudioBackend, ~20 ms latency), when one is installed and starts.

  2. Legacy _LegacyMiniaudioBackend (~100 ms latency, no 3D positional audio), unless SIMVX_ALLOW_LEGACY_AUDIO is "0". Emits a one-time WARNING naming what is lost, with install instructions only when no accelerator is installed: one that is installed but could not open the device is not fixed by installing it again.

  3. Null NullAudioBackend (silent), when the legacy mixer cannot start either: typically a sandboxed CI without an audio device. Emits another one-time WARNING.

With SIMVX_ALLOW_LEGACY_AUDIO=0, a missing, unloadable or failing accelerator raises :class:AudioBackendUnavailable instead.