simvx.core.audio_errors

Typed audio errors and the strict-mode flag.

The audio system raises typed exceptions instead of returning None or silently falling back. Callers can except AudioError (or any subclass) at well-defined boundaries; deep code paths never swallow.

Strict mode (SIMVX_AUDIO_STRICT, default "1") controls whether historically-silent code paths raise (strict, dev default) or warn-once (non-strict, release builds). Shipping games typically set SIMVX_AUDIO_STRICT=0 so a misconfigured asset doesn’t crash the player; development runs at strict to surface bugs early.

Module Contents

Functions

warn_once	Emit msg at WARNING level the first time key is seen, then suppress.
raise_or_warn	In strict mode, re-raise exc wrapped in :class:AudioError. Otherwise warn-once.

Data

__all__
STRICT

API

simvx.core.audio_errors.__all__

[‘STRICT’, ‘AudioError’, ‘AudioBackendUnavailable’, ‘UnknownBusError’, ‘InvalidStreamError’, ‘AudioC…

simvx.core.audio_errors.STRICT: bool

None

simvx.core.audio_errors.warn_once(key: str, msg: str, *args: object, exc_info: bool = False) → None

Emit msg at WARNING level the first time key is seen, then suppress.

Use for non-fatal audio failures where flooding the log would be worse than missing a few subsequent occurrences (e.g. a backend call that fails on every on_process tick).

simvx.core.audio_errors.raise_or_warn(exc: BaseException, *, key: str, message: str) → None

In strict mode, re-raise exc wrapped in :class:AudioError. Otherwise warn-once.

Use at boundaries where the surrounding code can continue without the operation that just failed (e.g. cleanup paths, best-effort releases). Hot-path code that fundamentally needs the operation to succeed should raise directly rather than route through this helper.

exception simvx.core.audio_errors.AudioError

Bases: Exception

Base class for every audio-system exception.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

exception simvx.core.audio_errors.AudioBackendUnavailable

Bases: simvx.core.audio_errors.AudioError

The requested audio backend is missing or failed to initialise.

Raised at backend-selection time (make_backend) or at first audio operation when the native extension is absent and the user hasn’t opted into a fallback.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

exception simvx.core.audio_errors.UnknownBusError(name: str, *, available: list[str])

Bases: simvx.core.audio_errors.AudioError

Bus name not found in the active layout.

Raised by AudioBusLayout.get_bus and every backend’s bus resolver when a player references a bus that hasn’t been declared. The error message lists the available bus names to help the caller fix the typo or register the missing bus.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

exception simvx.core.audio_errors.InvalidStreamError

Bases: simvx.core.audio_errors.AudioError

Stream source is unrecognised or unsupported by the active backend.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

exception simvx.core.audio_errors.AudioCapabilityError(capability: str | object, *, backend: str, advertised: set[str] | set[object] | frozenset[object], remediation: str | None = None)

Bases: simvx.core.audio_errors.AudioError

The active backend doesn’t support the requested capability.

Use when a player asks for something the backend can’t deliver (e.g. set_pitch on a streaming sound on a backend that can’t pitch-shift streams). Includes the capability name + the backend’s advertised capability set so the caller knows what’s available. An optional remediation string is appended verbatim to point the caller at the fix.

Accepts capability and the advertised set as either str or :class:simvx.core.audio_protocol.Capability. Members are stored as plain strings so the error remains hashable/serialisable.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()

exception simvx.core.audio_errors.AudioMutationDuringPlaybackError(prop_name: str, *, player: str)

Bases: simvx.core.audio_errors.AudioError

A next-play-only Property was mutated while a channel was active.

Raised in strict mode when a Property declared with mutation_policy="next_play" (e.g. loop, stream_mode) is written while the player has an active channel. Non-strict mode logs a one-time warning and silently defers the change to the next play() call.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class __cause__

class __context__

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getstate__()

__gt__()

__hash__()

__le__()

__lt__()

__ne__()

__new__()

__reduce__()

__reduce_ex__()

__repr__()

__setattr__()

__setstate__()

__sizeof__()

__str__()

__subclasshook__()

class __suppress_context__

class __traceback__

add_note()

class args

with_traceback()