Sonus

Sonus is a C++23 audio playback library built on miniaudio. It provides a small thread-safe engine for sound file playback and generated metronome clicks, with std::expected-based error reporting through Modulus.

Sonus keeps miniaudio out of public headers and is intended for embedded Linux applications where startup cost, predictable ownership, and low callback overhead matter.

Devices And Threading

enumerate_playback_devices() returns device descriptions or a Modulus error if the audio backend cannot initialize or enumerate. A successful empty list means no playback devices were reported. Copy a description's id to audio_config::playback_device_id before creating an engine. IDs are opaque tokens derived from enumeration order and metadata, intended for immediate reuse; re-enumerate after hardware or backend changes. They are not permanent hardware identifiers.

Selection tries the ID first, then an exact playback_device_name fallback. Duplicate names select the first match, so use the ID to distinguish them. Empty selectors preserve the backend's default device. An unresolved explicit selector returns an error. no_device rejects device selectors and enables manual rendering instead.

Period size may be requested in frames or milliseconds (not both), with an optional period count and performance profile. The backend may adjust these requests to hardware capabilities.

Control calls on one engine are serialized and may run concurrently with playback. update_metronome() preserves the running/stopped state at publication. Render callbacks use immutable click buffers and lock-free snapshot reads; reclamation runs on control threads. Idle publications reclaim previous snapshots immediately. Snapshots retired during rendering are collected by subsequent metronome controls, collect_finished(), active_sound_count(), playback, or device stop. Manual renders are serialized. Do not move or destroy an engine while another thread is calling it.

Call collect_finished() periodically to release sounds that reach EOF without further playback or status calls. Sonus compiles miniaudio internally; installed consumers link sonus::sonus and need only Modulus core and its Boost dependency. Miniaudio headers are needed only to build Sonus.

Build

Configure, build, and test the default target:

python3 modulus.py configure
python3 modulus.py build
python3 modulus.py test

Create packages:

python3 modulus.py package --all

License

Sonus is released under the MIT License.