Audio (cinder/audio)

cinder/audio is the engine's sound layer over miniaudio. It provides mixing buses, decoded and streamed sounds, one-shots that clean up after themselves, 3D spatialisation with distance attenuation, a single listener, and an ECS bridge that moves sounds with entities and the listener with the camera. It sits beside render, physics, anim and input in the module map (docs/ARCHITECTURE.md): it depends on core, ecs, platform and the generated ffi bindings, and is owned and driven by cinder/app.

Source: cinder/audio/engine.mojo (the engine), cinder/audio/sync.mojo (ECS components and sync_audio), native/src/audio.c (the shim side). API reference: docs/api/audio.md. Design decisions: docs/adr/0012-physics-animation-audio-input.md, "Audio" section.

Key types and ownership #

Everything miniaudio-shaped lives in the shim. ma_engine, ma_sound and ma_sound_group are large structs that are opaque to Mojo, so cn_audio_engine_create, cn_audio_sound_create_in_group and cn_audio_group_create allocate them in C and hand back pointers; Mojo keeps those pointers in AudioEngine.engine, AudioEngine.buses and a slot table (AudioEngine.slots). Sound handles are generational: release bumps the slot's generation and puts the index on the free list, so a stale handle fails is_valid and every method that takes a handle raises "audio: stale sound handle".

Bus 0 is always the master bus, created by the constructor on the engine endpoint; live_buses() does not count it. live_sounds() counts slots that still hold a sound.

Lifetimes and leaks: AudioEngine.__deinit__ destroys any remaining sounds, then the buses in reverse order, then the engine and its event queue, so leaking is not fatal. The convention, enforced by the tests and by App.live_objects(), is that live_sounds() and live_buses() are zero before the engine goes away: release every sound and destroy_bus every bus you created (live_buses() counts created buses not yet destroyed) (App.live_objects() sums physics objects, live sounds and live buses for the shutdown leak report). Because App.audio is a field of App, a Game that holds SoundHandles must be destroyed before the App; see docs/guides/app.md.

The engine needs the NativePtr of a NativeLibrary that outlives it. Inside App that is App.lib, declared last so it is destroyed last.

Creating an engine #

Through App, AppConfig.audio (default True) creates the engine; headless apps get a device-less engine automatically. Standalone, as the tests do:

from cinder.audio import AudioEngine, SoundDesc
from cinder.platform import NativeLibrary

var lib = NativeLibrary()
var audio = AudioEngine(lib.ptr(), True)      # headless=True: no device, output is pulled
var sfx = audio.create_bus(String("sfx"))     # parent defaults to 0 (master)
var music = audio.create_bus(String("music"))

The constructor arguments are (lib, headless=False, sample_rate=48000, channels=2). It raises "audio: miniaudio engine creation failed (no device?)" when a device is requested on a machine without one; pass headless=True (or run the app with --headless) in that case. create_bus(name, parent=0) returns the bus index; parent=-1 attaches a bus directly to the engine endpoint, which is how the master bus itself is created. find_bus(name) returns -1 when no live bus has that name.

destroy_bus(index) destroys a bus made with create_bus (through the shim's cn_audio_group_destroy) and lowers live_buses() by one. Its index then stays invalid: indices are never reused, so every bus method, load and create_bus(parent=index) raise "audio: bus <i> does not exist" for it, as does a second destroy_bus. It also raises for the master bus (0 belongs to the engine) and for a bus that still has sounds (release them first) or live child buses (destroy those first, children before parents).

Loading and playing #

load creates the sound stopped; play starts it. SoundDesc takes the common options positionally: SoundDesc(path, bus=0, streamed=False, looping=False, spatial=True). The remaining fields (volume, pitch, attenuation, min_distance, max_distance, rolloff, one_shot) are set on the value after construction. Supported file types are WAV, FLAC, MP3 and Vorbis.

# Streamed, looping, non-spatial music on its own bus (from sample/game/game.mojo).
var song = audio.load(
    SoundDesc(String("assets/game/audio/music_level.wav"), music, True, True, False)
)
audio.play(song)
audio.set_bus_volume(music, 0.6)

# Decoded, looping, spatial effect at a position.
var tone = audio.load(SoundDesc(String("tone.wav"), sfx, False, True, True))
audio.set_position(tone, Vec3(-10.0, 0.0, 0.0))
audio.play(tone)
audio.stop(tone)
audio.release(tone)

• streamed=True maps to MA_SOUND_FLAG_STREAM: the file is decoded while it plays (music). Otherwise MA_SOUND_FLAG_DECODE decodes the whole file at load time (effects).
• spatial=False sets MA_SOUND_FLAG_NO_SPATIALIZATION: the sound is mixed centred, with set_pan as the only positioning control.
• Per-sound controls after loading: set_volume, set_pitch, set_pan, set_looping, fade(from, to, milliseconds), seek(frame), is_playing, at_end.
• A failed load raises "audio: could not load '<path>'" and leaves nothing behind (the slot is returned to the free list; the test asserts live_sounds() is unchanged).

One-shots #

play_one_shot(desc, position) sets one_shot=True and looping=False on the description, loads, positions the sound if it is spatial, starts it and returns the handle. When the sound ends, the next update() releases it. The sample fires impact sounds this way:

var desc = SoundDesc(String("assets/game/audio/impact.wav"), self.sfx_bus, False, False, True)
desc.min_distance = 2.0
desc.max_distance = 60.0
_ = app.audio.value().play_one_shot(desc^, position)

Do not keep one-shot handles around for long: once released, is_valid is false and play raises.

3D position, attenuation and the listener #

Spatial sounds take set_position(handle, Vec3) and set_velocity(handle, Vec3); set_spatial toggles spatialisation on an existing sound. The attenuation model and its distances are applied at load time from the SoundDesc (defaults: Attenuation.inverse(), min_distance=1.0, max_distance=100.0, rolloff=1.0) and can be changed with set_attenuation(handle, model, min_distance, max_distance, rolloff).

The listener is miniaudio's listener 0. set_listener(position, forward, up=Vec3.unit_y(), velocity=Vec3.zero()) sets its position, direction, world up and velocity. The engine convention is right-handed, Y up, -Z forward, so a listener looking down -Z hears a source at negative X on the left; tests/audio/test_audio_engine.mojo checks exactly that with RMS measurements per channel.

The ECS bridge #

cinder/audio/sync.mojo connects sounds to entities. AudioSource(sound, velocity) on an entity with a WorldTransform makes sync_audio set that sound's position to the transform's translation and its velocity to the component's velocity. AudioListener(velocity) marks the listener entity: its WorldTransform gives the position, -Z transformed by the matrix gives forward, +Y gives up. When several entities carry AudioListener, the first chunk found wins.

from cinder.audio import AudioListener, AudioSource
from cinder.ecs import LocalTransform, World, propagate_transforms

var camera = world.spawn()
world.add[LocalTransform](camera, LocalTransform(Mat4.identity()))
world.add[AudioListener](camera, AudioListener(Vec3.zero()))
var emitter = world.spawn()
world.add[LocalTransform](emitter, LocalTransform(Mat4.translation(Vec3(-10.0, 0.0, 0.0))))
world.add[AudioSource](emitter, AudioSource(tone, Vec3.zero()))
_ = propagate_transforms(world)      # WorldTransform must exist before sync_audio
var positioned = sync_audio(world, audio)   # returns the number of sources positioned

sync_audio skips sources whose handle is no longer valid instead of raising, so releasing a sound does not require removing its component first. Component ids are AUDIO_SOURCE_COMPONENT_ID = 10 and AUDIO_LISTENER_COMPONENT_ID = 11. App.run_frame calls propagate_transforms and then sync_audio every frame, so with App you only add the components.

Per-frame work: update, take_ended, read_frames #

update() drains the shim's event queue. Log callbacks from miniaudio become LogRecords in AudioEngine.diagnostics (category "audio"; error_count() counts those at error level). Sound-end events are matched to a live handle, recorded in AudioEngine.ended, and one-shots are released. update() returns how many sounds ended. take_ended() moves the ended list out so gameplay can react once:

_ = audio.update()
for h in audio.take_ended():
    if h == self.footstep:
        self.footstep = SoundHandle.null()

In headless mode there is no device pulling the mixer, so nothing progresses unless you pull it. read_frames(frames) mixes frames frames and returns frames * channels interleaved Float32 samples; it raises on a device-backed engine. App.run_frame does this for you: each frame it reads dt * sample_rate frames (capped at one second) and discards them, so one-shots end and streams advance in tests and benchmarks exactly as they would with a device.

Threading #

• The miniaudio device thread never runs Mojo. The shim registers only two callbacks (on_log and on_sound_end in native/src/audio.c), and both post fixed-size events to a CnEventQueue that update() drains on the main thread (ADR-0003, docs/THREADING.md).
• Setters such as set_position and set_bus_volume are direct ma_* calls from the calling thread; miniaudio makes them safe against its own mixing thread. Call them from the main thread.
• With a headless engine there is no audio thread at all: mixing happens inside read_frames, so the end callbacks fire on the caller's thread during that call and still only post events.

Pitfalls #

• The sound-end callback fires on the processing step after the one that reached the end, and the sound is already stopped inside it (docs/MOJO_NOTES.md, Phase 6). A headless test therefore reads one more buffer with read_frames before calling update() and expecting the end event.
• update() releases one-shots, so a handle returned by play_one_shot becomes stale without any call of yours. Check is_valid before reusing it.
• Sound paths are passed to C as a borrowed C string; load keeps the String alive across the call with keep. If you add a shim call that takes a path, do the same (MOJO_NOTES.md, untracked pointers do not keep their pointee alive).
• set_master_volume is the engine's own volume, separate from bus 0's volume; the sample's settings apply master_volume to the engine and music_volume/sfx_volume to buses found by name.
• Buses cannot be destroyed individually; they live until the engine does. Create them once in Game.start.
• AppConfig.audio = False (--no-audio) leaves App.audio empty; always test if app.audio: before app.audio.value().

Tests and references #

• tests/audio/test_audio_engine.mojo: writes WAV files, then checks buses, left/right panning, distance attenuation, bus muting, streamed looping music, one-shot release through update, failed loads, and the ECS bridge (sources follow entities, listener follows the camera, stale handles are skipped). Run with pixi run test-audio-engine.
• tests/sample/test_sample_game.mojo: after the level is cleared, 240 headless frames let the one-shots end so only the music loop remains (live_sounds() == 1, live_buses() == 2).
• docs/adr/0012-physics-animation-audio-input.md: miniaudio used as is, headless engines for tests, callbacks post events, listener follows an entity.
• docs/adr/0013-tools-and-app-runtime.md: how App owns the engine and pumps it headless.