simvx.core.audio_bus

Audio bus system – named buses with volume, mute, and routing.

Provides a mixing hierarchy similar to Godot’s audio bus layout. Buses can route to parent buses (e.g., SFX -> Master, Music -> Master), and the final volume is computed by walking the chain.

Bus names are case-sensitive and use the Godot convention: "Master", "Music", "SFX", "Voice", "UI". Looking up a bus that isn’t in the layout raises :class:UnknownBusError with the available names listed: no lazy creation, no fallback to Master.

Public API: from simvx.core.audio_bus import AudioBusLayout, AudioBus

layout = AudioBusLayout.get_default()
layout.get_bus("Music").volume_db = -6.0
layout.get_bus("SFX").mute = True

# Effective volume considers the full chain:
effective = layout.get_bus("SFX").effective_volume

Module Contents

Classes

AudioBus	A single audio bus with volume, mute, and parent routing.
AudioBusLayout	Collection of audio buses with routing and volume computation.

Data

log
__all__

API

simvx.core.audio_bus.log

‘getLogger(…)’

simvx.core.audio_bus.__all__

[‘AudioBus’, ‘AudioBusLayout’]

class simvx.core.audio_bus.AudioBus(name: str, volume_db: float = 0.0, send_to: str = '')

A single audio bus with volume, mute, and parent routing.

Attributes: name: Bus display name (e.g., “Master”, “SFX”). Case-sensitive. volume_db: Volume in decibels (-80 to 24). 0 = full volume. Clamped to the declared range on every write. mute: If True, this bus and all children produce no output. solo: If True, only this bus (and its children) produce output. send_to: Name of the parent bus this routes to (empty for Master).

Initialization

volume_db

‘Property(…)’

mute

‘Property(…)’

solo

‘Property(…)’

property linear_volume: float

volume_db converted to linear scale (0.0 to ~15.85).

property effective_volume: float

Effective dB after walking the send_to chain to Master.

Sum of volume_db along the chain. If any bus in the chain is muted, returns -80 (silent). Returns own volume_db when not in a layout.

Solo gating: when any bus in the layout has solo=True, every non-master, non-solo bus that is not an ancestor of a soloed bus is forced to the silence floor (-80 dB): mirroring the standard mixing-console “solo” behaviour. Master is always exempt so the listener still hears the surviving signal.

property effective_linear_volume: float

effective_volume converted to linear multiplier (0.0 to ~15.85).

add_effect(effect: Any) → None

Add an audio effect to this bus’s processing chain.

remove_effect(effect: Any) → None

Remove an audio effect from this bus.

property effects: list[Any]

Read-only view of effects on this bus.

__repr__() → str

class simvx.core.audio_bus.AudioBusLayout

Collection of audio buses with routing and volume computation.

Default layout creates four buses: Master (root) <- Music, SFX, Voice

Initialization

add_bus(name: str, volume_db: float = 0.0, send_to: str = '') → simvx.core.audio_bus.AudioBus

Add a new audio bus.

Args: name: Unique bus name (case-sensitive). volume_db: Initial volume in dB (clamped to [-80, 24]). send_to: Name of parent bus to route to. Must already exist in this layout (other than the empty string for root buses). "Master" is permitted regardless because it’s the conventional root and is always present in default layouts.

Returns: The created AudioBus.

Raises: UnknownBusError: send_to references a bus that does not exist in this layout (and isn’t "Master").

remove_bus(name: str) → None

Remove a bus by name. Cannot remove Master.

get_bus(name: str) → simvx.core.audio_bus.AudioBus

Return the bus named name.

Raises: UnknownBusError: name is not present in this layout. The error message lists the available names. Bus names are case-sensitive: "master" does not match "Master".

has_bus(name: str) → bool

Return True iff a bus named name exists. Cheap, no raise.

property buses: list[simvx.core.audio_bus.AudioBus]

All buses in the layout.

property bus_names: list[str]

Names of all buses.

classmethod get_default() → simvx.core.audio_bus.AudioBusLayout

Return the default bus layout (Master, Music, SFX, Voice, UI).

classmethod create_default() → simvx.core.audio_bus.AudioBusLayout

Create the standard five-bus layout (Godot convention).

Buses: Master (root), Music, SFX, Voice, UI, each child routed to Master. Names are case-sensitive; the engine and every shipped player Property default uses TitleCase.

classmethod reset()

Reset the default layout singleton (for tests).

to_dict() → list[dict]

Serialize to JSON-compatible format.

Each bus emits its effect chain via :meth:AudioEffect.to_dict;

Meth:

from_dict rebuilds the effects symmetrically.

classmethod from_dict(data: list[dict]) → simvx.core.audio_bus.AudioBusLayout

Deserialize from JSON format.

Buses are added in the order they appear, so children must follow their parent. Layouts produced by :meth:to_dict already obey this ordering. send_to validation in :meth:add_bus will raise

Class:

UnknownBusError if a child precedes its parent. Each bus’s effects list is rebuilt via :meth:AudioEffect.from_dict.