Audio Buses¶

per-bus volume, mute/solo, and bus effects
Tags: audio buses effects mixing ui
A synthesised arpeggio loop plays on the “Music” bus while periodic blips fire on “SFX”. Sliders set each bus’s volume_db live, M/S check boxes drive mute and solo (solo silences every bus off the soloed bus’s routing path, so a group bus keeps whatever is routed into it audible), and two toggles put effects on the Music bus: a LowPassFilter whose cutoff sweeps continuously, and a ReverbEffect switched on and off whole. Only the five built-in buses (Master, Music, SFX, Voice, UI) are routable; a player’s bus property rejects any other name. Bus effects are silently inert on the pure-Python fallback audio backend.
What it demonstrates¶

Routing players to buses via the bus property (set before play()).
AudioBusLayout.get_default() and live volume_db / mute / solo.
effective_volume: the dB chain walked through send_to up to Master.
send_to as signal routing: a bus’s output runs through its target’s gain and effects, so an effect on Master processes every bus under it.
Bus effects: add_effect / remove_effect, sweeping a biquad’s cutoff_hz (clean), toggling a ReverbEffect whole (its parameters are never swept: changing them rebuilds the native chain audibly).
Controls: Sliders - per-bus volume_db M / S - mute / solo a bus (solo is ignored on Master) Toggles - low-pass cutoff sweep and reverb on the Music bus B - fire a blip on the SFX bus (or click the Blip button) ESC - Quit
Run: uv run python examples/features/audio/buses.py Headless self-check: uv run python examples/features/audio/buses.py –test
Source¶

"""Audio Buses: per-bus volume, mute/solo, and bus effects

A synthesised arpeggio loop plays on the "Music" bus while periodic blips
fire on "SFX". Sliders set each bus's volume_db live, M/S check boxes drive
mute and solo (solo silences every bus off the soloed bus's routing path,
so a group bus keeps whatever is routed into it audible), and two
toggles put effects on the Music bus: a LowPassFilter whose cutoff sweeps
continuously, and a ReverbEffect switched on and off whole. Only the five
built-in buses (Master, Music, SFX, Voice, UI) are routable; a player's
`bus` property rejects any other name. Bus effects are silently inert on
the pure-Python fallback audio backend.

# /// simvx
# tags = ["audio", "buses", "effects", "mixing", "ui"]
# ///

## What it demonstrates
- Routing players to buses via the `bus` property (set before play()).
- `AudioBusLayout.get_default()` and live `volume_db` / `mute` / `solo`.
- `effective_volume`: the dB chain walked through `send_to` up to Master.
- `send_to` as signal routing: a bus's output runs through its target's
  gain and effects, so an effect on Master processes every bus under it.
- Bus effects: `add_effect` / `remove_effect`, sweeping a biquad's
  `cutoff_hz` (clean), toggling a ReverbEffect whole (its parameters are
  never swept: changing them rebuilds the native chain audibly).

Controls:
  Sliders  - per-bus volume_db
  M / S    - mute / solo a bus (solo is ignored on Master)
  Toggles  - low-pass cutoff sweep and reverb on the Music bus
  B        - fire a blip on the SFX bus (or click the Blip button)
  ESC      - Quit

Run: uv run python examples/features/audio/buses.py
Headless self-check: uv run python examples/features/audio/buses.py --test
"""

import numpy as np

from simvx.core import (
    AnchorPreset,
    AudioBusLayout,
    AudioClip,
    AudioPlayer,
    Colour,
    Input,
    Key,
    Label,
    LowPassFilter,
    Node,
    Panel,
    ReverbEffect,
    Timer,
    Vec2,
)
from simvx.core.ui import Button, CheckBox, HBoxContainer, Slider, VBoxContainer
from simvx.graphics import App

WIDTH, HEIGHT = 960, 540
SAMPLE_RATE = 44100

# Slider range: a usable mixing window inside the bus's full [-80, 24] dB span.
SLIDER_MIN_DB, SLIDER_MAX_DB = -40.0, 12.0

# Low-pass sweep: cutoff_hz glides between these bounds, exponentially so the
# motion sounds even across octaves. Biquad parameter sweeps are clean; only
# Delay/Reverb rebuild their processing chain on a parameter change.
SWEEP_LOW_HZ, SWEEP_HIGH_HZ = 300.0, 8000.0
SWEEP_PERIOD_S = 6.0

BLIP_INTERVAL_S = 0.9
BLIP_FREQS = (660.0, 880.0, 1320.0)


def make_music_loop() -> AudioClip:
    """Render a two-second Cmaj7 arpeggio loop as a stereo PCM clip."""
    step_s = 0.25
    notes = (261.63, 329.63, 392.00, 493.88, 523.25, 493.88, 392.00, 329.63)
    n = int(SAMPLE_RATE * step_s)
    t = np.arange(n, dtype=np.float32) / SAMPLE_RATE
    # Fast attack, exponential decay: reads as a plucked note, and the decay
    # reaching near-zero by the step boundary keeps the loop seam silent.
    envelope = np.minimum(t / 0.01, 1.0) * np.exp(-4.0 * t)
    parts = []
    for freq in notes:
        wave = np.sin(2 * np.pi * freq * t) + 0.35 * np.sin(2 * np.pi * 2 * freq * t)
        parts.append((wave * envelope * 0.22).astype(np.float32))
    mono = np.concatenate(parts)
    stereo = np.repeat(mono, 2)  # interleave L/R with the same signal
    return AudioClip.from_pcm(stereo, sample_rate=SAMPLE_RATE, channels=2, name="arp_loop")


def make_blip(freq_hz: float) -> AudioClip:
    """Render a short percussive blip as a mono PCM clip."""
    n = int(SAMPLE_RATE * 0.12)
    t = np.arange(n, dtype=np.float32) / SAMPLE_RATE
    mono = (np.sin(2 * np.pi * freq_hz * t) * np.exp(-30.0 * t) * 0.4).astype(np.float32)
    return AudioClip.from_pcm(mono, sample_rate=SAMPLE_RATE, channels=1, name=f"blip_{int(freq_hz)}")


class BusMixerDemo(Node):
    """A three-strip mixer over the default bus layout, with Music-bus effects."""

    input_actions = {"quit": [Key.ESCAPE], "blip": [Key.B]}

    def on_ready(self):
        self._layout = AudioBusLayout.get_default()
        self._elapsed = 0.0
        self._blip_index = 0

        # Effect instances are kept and reused: toggling re-adds the same
        # object, so its parameters survive an off/on cycle.
        self._lowpass = LowPassFilter(cutoff_hz=SWEEP_HIGH_HZ)
        self._reverb = ReverbEffect(room_size=0.8, wet=0.45, dry=0.7)
        self._sweeping = False

        # Music: a looping synthesised arpeggio. `bus` and `loop` are
        # next-play properties, so both are set before the first play().
        self._music = self.add_child(AudioPlayer(name="Music"))
        self._music.bus = "Music"
        self._music.loop = True
        self._music.stream = make_music_loop()
        self._music.play()

        # SFX: short blips, re-triggered by a repeating Timer and by the B key.
        self._blips = [make_blip(freq) for freq in BLIP_FREQS]
        self._sfx = self.add_child(AudioPlayer(name="Blip"))
        self._sfx.bus = "SFX"
        timer = self.add_child(Timer(duration=BLIP_INTERVAL_S, one_shot=False, autostart=True))
        timer.timeout.connect(self._play_blip)

        self._build_ui()

    # --- UI -----------------------------------------------------------------

    def _build_ui(self):
        panel = Panel(name="MixerPanel")
        panel.set_anchor_preset(AnchorPreset.CENTER)
        panel.margin_left = -310
        panel.margin_right = 310
        panel.margin_top = -215
        panel.margin_bottom = 215
        panel.bg_colour = Colour.hex("#16182A")
        self.add_child(panel)

        column = VBoxContainer(name="Column")
        column.separation = 14.0
        column.set_anchor_preset(AnchorPreset.FULL_RECT)
        column.margin_left = 24
        column.margin_right = 24
        column.margin_top = 18
        column.margin_bottom = 18
        panel.add_child(column)

        title = Label("Audio Buses")
        title.font_size = 22.0
        title.alignment = "center"
        column.add_child(title)

        self._sliders: dict[str, Slider] = {}
        # Master last: its strip scales the whole mix, including both children.
        for bus_name in ("Music", "SFX", "Master"):
            column.add_child(self._make_strip(bus_name))

        # Effects on the Music bus. The low-pass toggle starts a continuous
        # cutoff sweep; the reverb toggle adds/removes the whole effect and its
        # parameters are deliberately left alone while it runs.
        fx_row = HBoxContainer(name="Effects")
        fx_row.separation = 18.0
        fx_label = Label("Music FX:")
        fx_label.min_size_x = 90
        fx_row.add_child(fx_label)
        self._sweep_toggle = CheckBox("Low-pass sweep", on_toggle=self._on_sweep_toggled)
        fx_row.add_child(self._sweep_toggle)
        self._reverb_toggle = CheckBox("Reverb", on_toggle=self._on_reverb_toggled)
        fx_row.add_child(self._reverb_toggle)
        blip_button = Button("Blip", on_press=self._play_blip)
        blip_button.size = Vec2(80, 26)
        fx_row.add_child(blip_button)
        column.add_child(fx_row)

        self._status = Label("")
        self._status.font_size = 13.0
        self._status.text_colour = Colour.LIGHT_GRAY
        column.add_child(self._status)

        hint = Label("Sliders: volume_db   M: mute   S: solo   B: blip   ESC: quit")
        hint.font_size = 12.0
        hint.text_colour = Colour.GRAY
        column.add_child(hint)

    def _make_strip(self, bus_name: str) -> HBoxContainer:
        """One mixer strip: name, volume slider, mute box, solo box."""
        bus = self._layout.get_bus(bus_name)
        row = HBoxContainer(name=f"{bus_name}Strip")
        row.separation = 12.0

        label = Label(bus_name)
        label.min_size_x = 90
        row.add_child(label)

        slider = Slider(SLIDER_MIN_DB, SLIDER_MAX_DB, value=bus.volume_db)
        slider.size = Vec2(260, 22)
        slider.value_changed.connect(lambda db, b=bus: setattr(b, "volume_db", db))
        self._sliders[bus_name] = slider
        row.add_child(slider)

        mute = CheckBox("M", checked=bus.mute, on_toggle=lambda on, b=bus: setattr(b, "mute", on))
        row.add_child(mute)
        if bus_name != "Master":
            # Soloing Master is a no-op (it is already the root mix), so the
            # engine ignores its solo flag and the strip omits the box.
            solo = CheckBox("S", checked=bus.solo, on_toggle=lambda on, b=bus: setattr(b, "solo", on))
            row.add_child(solo)
        return row

    # --- Behaviour ----------------------------------------------------------

    def _play_blip(self):
        # A fresh clip each trigger; stop() first so play() restarts rather
        # than resuming. The player was routed to "SFX" once, at ready.
        self._sfx.stop()
        self._sfx.stream = self._blips[self._blip_index]
        self._blip_index = (self._blip_index + 1) % len(self._blips)
        self._sfx.play()

    def _on_sweep_toggled(self, enabled: bool):
        self._sweeping = enabled
        music = self._layout.get_bus("Music")
        if enabled:
            music.add_effect(self._lowpass)
        else:
            music.remove_effect(self._lowpass)

    def _on_reverb_toggled(self, enabled: bool):
        music = self._layout.get_bus("Music")
        if enabled:
            music.add_effect(self._reverb)
        else:
            music.remove_effect(self._reverb)

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("blip"):
            self._play_blip()

        self._elapsed += dt
        if self._sweeping:
            # Exponential glide between the bounds: linear in octaves.
            phase = 0.5 - 0.5 * np.cos(2 * np.pi * self._elapsed / SWEEP_PERIOD_S)
            self._lowpass.cutoff_hz = SWEEP_LOW_HZ * (SWEEP_HIGH_HZ / SWEEP_LOW_HZ) ** phase

        self._refresh_status()

    def _refresh_status(self):
        # effective_volume walks the send_to chain, so it shows mute and solo
        # gating as -80 dB even when the strip's own slider is untouched.
        parts = []
        for name in ("Music", "SFX", "Master"):
            parts.append(f"{name} {self._layout.get_bus(name).effective_volume:+.0f} dB")
        line = "Effective:  " + "   ".join(parts)
        if self._sweeping:
            line += f"   |   cutoff {self._lowpass.cutoff_hz:.0f} Hz"
        self._status.text = line


def _selftest() -> bool:
    """Headless: check the bus maths on a fresh layout, then the demo's wiring."""
    ok = True

    def check(label: str, passed: bool, detail: str = "") -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}" + (f": {detail}" if detail else ""))

    # --- Pure bus logic, on a private layout so nothing global is touched ---
    layout = AudioBusLayout.create_default()
    check(
        "the default layout holds exactly the five routable buses",
        set(layout.bus_names) == {"Master", "Music", "SFX", "Voice", "UI"},
        str(layout.bus_names),
    )

    player = AudioPlayer(name="Probe")
    try:
        player.bus = "Ambience"
        routable = False
    except ValueError:
        routable = True
    check("a player's bus property rejects non-built-in names", routable)

    music, sfx, master = layout.get_bus("Music"), layout.get_bus("SFX"), layout.get_bus("Master")
    music.volume_db = -6.0
    master.volume_db = -6.0
    check("effective_volume sums the send_to chain", music.effective_volume == -12.0, f"{music.effective_volume}")
    music.volume_db = -200.0  # Property clamps to the [-80, 24] range
    check(
        "volume_db clamps to the floor and goes silent",
        music.volume_db == -80.0 and music.effective_linear_volume == 0.0,
        f"{music.volume_db} dB, linear {music.effective_linear_volume}",
    )
    music.volume_db = 0.0
    master.mute = True
    check("muting Master silences a child bus", music.effective_volume == -80.0, f"{music.effective_volume}")
    master.mute = False
    sfx.solo = True
    check(
        "solo on SFX gates Music but leaves SFX and Master audible",
        music.effective_volume == -80.0 and sfx.effective_volume > -80.0 and master.effective_volume > -80.0,
        f"music {music.effective_volume}, sfx {sfx.effective_volume}, master {master.effective_volume}",
    )
    footsteps = layout.add_bus("Footsteps", send_to="SFX")
    check(
        "solo on a group bus keeps what is routed into it audible",
        footsteps.effective_volume > -80.0,
        f"footsteps {footsteps.effective_volume}",
    )
    layout.remove_bus("SFX")
    check(
        "removing a bus re-routes what fed it rather than orphaning it",
        footsteps.send_to == "Master",
        f"footsteps -> {footsteps.send_to!r}",
    )
    layout = AudioBusLayout.create_default()
    music, sfx, master = layout.get_bus("Music"), layout.get_bus("SFX"), layout.get_bus("Master")

    lowpass = LowPassFilter(cutoff_hz=800.0)
    music.add_effect(lowpass)
    check("add_effect places the effect on the bus chain", lowpass in music.effects)
    lowpass.cutoff_hz = 5.0
    check("cutoff_hz clamps to its declared range", lowpass.cutoff_hz == 20.0, f"{lowpass.cutoff_hz}")
    music.remove_effect(lowpass)
    check("remove_effect takes it off again", lowpass not in music.effects)

    loop_clip = make_music_loop()
    check(
        "the synthesised loop is baked PCM the backend can play",
        loop_clip.backend_data is not None and loop_clip.backend_data.dtype == np.float32,
    )

    # --- The demo itself, mounted headless ---
    app = App(title="Audio Buses", width=WIDTH, height=HEIGHT, visible=False)
    scene = BusMixerDemo(name="BusMixerDemo")
    default = AudioBusLayout.get_default()
    cutoffs: list[float] = []

    def on_frame(idx: int, _t: float) -> bool:
        if idx == 5:
            # Drive the Music slider the way its signal contract promises.
            scene._sliders["Music"].value = -12.0
            scene._sliders["Music"].value_changed.emit(-12.0)
            scene._sweep_toggle.activate()  # toggles + emits, like a click
            scene._reverb_toggle.activate()
        if idx == 8:
            scene._play_blip()
        if idx >= 10:
            cutoffs.append(float(scene._lowpass.cutoff_hz))
        return True

    app.run_headless(scene, frames=60, on_frame=on_frame)

    check("the music loop is playing on the Music bus", scene._music.is_playing() and scene._music.bus == "Music")
    check("the blip player is routed to SFX", scene._sfx.bus == "SFX")
    check(
        "the slider write landed on the bus",
        default.get_bus("Music").volume_db == -12.0,
        f"{default.get_bus('Music').volume_db}",
    )
    check(
        "the toggles installed both effects on the Music bus",
        scene._lowpass in default.get_bus("Music").effects and scene._reverb in default.get_bus("Music").effects,
    )
    swept = len(cutoffs) >= 2 and cutoffs[0] != cutoffs[-1]
    in_range = all(20.0 <= c <= 20000.0 for c in cutoffs)
    check(
        "the low-pass cutoff sweeps within its legal range",
        swept and in_range,
        f"{cutoffs[0]:.0f} Hz -> {cutoffs[-1]:.0f} Hz over {len(cutoffs)} frames" if cutoffs else "no samples",
    )

    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Audio Buses", width=WIDTH, height=HEIGHT).run(BusMixerDemo())