simvx.core.audio_backend._null

The silent (no-op) audio backend.

NullAudioBackend is selected when no audio device is available (sandboxed CI, headless containers). Calls return valid channel IDs and behave consistently, but nothing is rendered to a device.

Module Contents

Classes

NullAudioBackend

Silent backend implementing :class:AudioPlaybackBackend + :class:AudioBusBackend.

API

class simvx.core.audio_backend._null.NullAudioBackend(sample_rate: int = _DEFAULT_SAMPLE_RATE, nchannels: int = _DEFAULT_CHANNELS)

Silent backend implementing :class:AudioPlaybackBackend + :class:AudioBusBackend.

Selected automatically by :func:make_backend when neither the native extension nor the legacy miniaudio path can start (e.g. no audio device on the host, ALSA/Pulse not running, the miniaudio Python package not installed, or a sandboxed environment with no compiler).

The engine, scene tree, and :class:AudioPlayer nodes all operate normally: calls return valid channel IDs and

Meth:

is_channel_active behaves consistently, but nothing is rendered to a device.

NullBackend does NOT implement :class:AudioStreamingBackend. Code paths that need streaming (procedural synth via

Class:

AudioSynth.attach_to, AudioWorklet feeds, etc.) must check isinstance(backend, AudioStreamingBackend) and raise / warn-once when it’s absent. Advertised capabilities are narrowed to {Capability.PLAY_BASIC} so effect modules don’t try to instantiate native nodes on the null path.

Initialization

play_audio(stream: simvx.core.audio.AudioClip, *, mode: str = 'non_positional', position: Any = None, volume_db: float = 0.0, pitch: float = 1.0, loop: bool = False, bus: str = 'Master', max_distance: float = 100.0, from_position: float = 0.0, pan: float = 0.0, gain_db: float = 0.0) → int | None

stop_audio(channel_id: int) → None

pause_audio(channel_id: int) → None

resume_audio(channel_id: int) → None

update_audio_2d(channel_id: int, volume_db: float, pan: float) → None

update_audio_3d(channel_id: int, volume_db: float, pan: float, pitch: float) → None

set_pitch(channel_id: int, pitch: float) → None

set_listener_position(x: float, y: float, z: float) → None

set_listener_velocity(x: float, y: float, z: float) → None

set_listener_direction(x: float, y: float, z: float) → None

set_listener_world_up(x: float, y: float, z: float) → None

get_playback_position(channel_id: int) → float

is_channel_active(channel_id: int) → bool

shutdown() → None

list_capabilities() → frozenset[simvx.core.audio_protocol.Capability]

sync_bus_layout(layout: simvx.core.audio_bus.AudioBusLayout) → None