ludus::audio::AudioSystem¶

Class

Instance-owned audio control surface with one caller-owned control thread.

Public warm operations allocate nothing; preparation and native device setup are explicit cold operations. Forward requests from other threads to the owner. Construction is fallible: check IsValid or Initialize. Browser lifecycle is asynchronous; call Service to advance it. See docs/wiki/guides/audio.md.

Declared in modules/audio/include/ludus/audio/audio_system.h

#include <ludus/audio/audio_system.h>

class ludus::audio::AudioSystem final

Methods¶

AudioSystem¶

ludus::audio::AudioSystem::AudioSystem() noexcept

Declared in modules/audio/include/ludus/audio/audio_system.h

~AudioSystem¶

ludus::audio::AudioSystem::~AudioSystem() noexcept

Declared in modules/audio/include/ludus/audio/audio_system.h

AudioSystem¶

ludus::audio::AudioSystem::AudioSystem(const AudioSystem &)=delete

Declared in modules/audio/include/ludus/audio/audio_system.h

operator=¶

AudioSystem & ludus::audio::AudioSystem::operator=(const AudioSystem &)=delete

Related types: AudioSystem

Declared in modules/audio/include/ludus/audio/audio_system.h

AudioSystem¶

ludus::audio::AudioSystem::AudioSystem(AudioSystem &&)=delete

Declared in modules/audio/include/ludus/audio/audio_system.h

operator=¶

AudioSystem & ludus::audio::AudioSystem::operator=(AudioSystem &&)=delete

Related types: AudioSystem

Declared in modules/audio/include/ludus/audio/audio_system.h

Initialize¶

Status ludus::audio::AudioSystem::Initialize(const SystemConfig &config) noexcept

Allocate fixed runtime storage and validate the bus tree, groups and capacities.

Parameter	Description
`config`	Session mode, sample rate and borrowed bus/group configuration.

Returns

Ok when ready; InvalidArgument for invalid configuration or repeated initialization; OutOfMemory on allocation failure; DeviceError when native context/device startup fails. Failed initialization permits an explicit retry.

Note

Call on the sole control owner. Device mode uses CoreAudio on macOS and PulseAudio/ALSA on Linux, with float32 stereo at the requested session rate. The period is a hint; miniaudio may convert the hardware format/rate. No null-device or Disabled fallback is selected implicitly.

Related types: Status · SystemConfig

Declared in modules/audio/include/ludus/audio/audio_system.h

GetState¶

SystemState ludus::audio::AudioSystem::GetState() const noexcept

Related types: SystemState

Declared in modules/audio/include/ludus/audio/audio_system.h

GetMode¶

Mode ludus::audio::AudioSystem::GetMode() const noexcept

Related types: Mode

Declared in modules/audio/include/ludus/audio/audio_system.h

GetSession¶

uint32 ludus::audio::AudioSystem::GetSession() const noexcept

Declared in modules/audio/include/ludus/audio/audio_system.h

GetSampleRate¶

uint32 ludus::audio::AudioSystem::GetSampleRate() const noexcept

Declared in modules/audio/include/ludus/audio/audio_system.h

PrepareClip¶

Status ludus::audio::AudioSystem::PrepareClip(std::span< const uint8 > encoded, const ClipDescriptor &descriptor, ClipHandle &outClip) noexcept

Decode/convert encoded bytes into owned finite PCM at the session rate.

The caller's bytes are borrowed only for the duration of this call.

Related types: Status · ClipDescriptor · ClipHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

PrepareStream¶

Status ludus::audio::AudioSystem::PrepareStream(std::span< const uint8 > encoded, const StreamDescriptor &descriptor, StreamHandle &outStream) noexcept

Copy encoded bytes, open a seekable decoder and prefill bounded PCM chunks.

Parameter	Description
`encoded`	Bytes borrowed only during this cold owner-side call.
`descriptor`	Codec and optional source-frame loop bounds.
`outStream`	Receives a session handle on success; invalidated on failure.

Returns

Ok, a decode/argument/capacity/allocation status, or IoError if the native worker cannot start. Native workers support Linux and macOS.

Related types: Status · StreamDescriptor · StreamHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

RetireClip¶

Status ludus::audio::AudioSystem::RetireClip(ClipHandle clip) noexcept

Close new admission for an asset; storage is retained for existing reservations/voices/worker jobs and reclaimed by Service after terminal acknowledgment.

No forced stop.

Related types: Status · ClipHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

RetireStream¶

Status ludus::audio::AudioSystem::RetireStream(StreamHandle stream) noexcept

Close stream admission without stopping existing voices; Service reclaims after quiescence.

Related types: Status · StreamHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

IsClipReady¶

bool ludus::audio::AudioSystem::IsClipReady(ClipHandle clip) const noexcept

True when clip names a currently-prepared, non-retiring resident clip in this session.

Owner-side; lets application descriptor validators check a variation handle without attempting playback.

Related types: ClipHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

PrepareStream¶

Status ludus::audio::AudioSystem::PrepareStream(foundation::core::UniquePtr< StreamInput > input, const StreamDescriptor &descriptor, StreamHandle &outStream) noexcept

Prepare a stream with exclusive input ownership, including on failure.

Parameter	Description
`input`	Seekable reader used during preparation and by the native Linux/macOS decode worker. File inputs bound encoded memory independently of track duration; renderer callbacks never read or seek this input.
`descriptor`	Codec and optional source-frame loop bounds.
`outStream`	Receives a session handle on success; invalidated on failure.

Returns

Ok or an explicit decode/argument/capacity/allocation/worker status.

Note

Call on the sole control owner. Retired input remains owned until voice and worker references quiesce; shutdown joins before reclaiming it.

Related types: StreamInput · foundation::core::UniquePtr · Status · StreamDescriptor · StreamHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

InstallClip¶

Status ludus::audio::AudioSystem::InstallClip(PreparedClip &prepared, ClipHandle &outClip) noexcept

Related types: PreparedClip · Status · ClipHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

TrySubmitBatch¶

BatchResult ludus::audio::AudioSystem::TrySubmitBatch(std::span< const Command > commands) noexcept

Validate the whole batch (<= MAX_BATCH_RECORDS), copy all records, reserve slots and asset pins transactionally, then publish once.

The returned Voices span is owned by the system and remains valid until the next submission call. noexcept, no allocation, no lock, no wait.

Related types: BatchResult · Command

Declared in modules/audio/include/ludus/audio/audio_system.h

PlayClip¶

Status ludus::audio::AudioSystem::PlayClip(const PlayParams &params, VoiceHandle &outVoice) noexcept

Convenience single-command Play using the batch path.

Related types: Status · PlayParams · VoiceHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

PlayStream¶

Status ludus::audio::AudioSystem::PlayStream(StreamHandle stream, uint32 busIndex, uint8 priority, float32 gain, VoiceHandle &outVoice) noexcept

Stream playback: a prepared StreamHandle is admitted once.

A second play on the same handle returns NotReady.

Related types: Status · StreamHandle · VoiceHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

Stop¶

Status ludus::audio::AudioSystem::Stop(VoiceHandle voice) noexcept

Stop uses a per-slot generation mailbox independent of normal queue room.

Idempotent for a terminal handle still known to the owner.

Related types: Status · VoiceHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

StopAll¶

void ludus::audio::AudioSystem::StopAll() noexcept

Advance the cancellation epoch; affects all voices admitted before this call, including queued plays.

Never needs queue space. Mix settings remain.

Declared in modules/audio/include/ludus/audio/audio_system.h

Service¶

void ludus::audio::AudioSystem::Service() noexcept

Drain diagnostics, acknowledge durable terminals, free retired storage, and advance setup/worker/backend lifecycle.

Not a mixer tick. Output continuity does not depend on calling this at the game frame rate.

Declared in modules/audio/include/ludus/audio/audio_system.h

GetVoiceInfo¶

Status ludus::audio::AudioSystem::GetVoiceInfo(VoiceHandle voice, VoiceInfo &out) const noexcept

Related types: Status · VoiceHandle · VoiceInfo

Declared in modules/audio/include/ludus/audio/audio_system.h

GetGroupInfo¶

Status ludus::audio::AudioSystem::GetGroupInfo(uint32 groupIndex, GroupInfo &out) const noexcept

Related types: Status · GroupInfo

Declared in modules/audio/include/ludus/audio/audio_system.h

GetBusMeter¶

Status ludus::audio::AudioSystem::GetBusMeter(uint32 busIndex, BusMeter &out) const noexcept

Related types: Status · BusMeter

Declared in modules/audio/include/ludus/audio/audio_system.h

GetSystemSnapshot¶

void ludus::audio::AudioSystem::GetSystemSnapshot(SystemSnapshot &out) const noexcept

Related types: SystemSnapshot

Declared in modules/audio/include/ludus/audio/audio_system.h

RenderOffline¶

Status ludus::audio::AudioSystem::RenderOffline(std::span< float32 > output, ChannelLayout layout, BufferLayout bufferLayout, uint32 frames) noexcept

Run the production render entry serially on the caller thread.

Rejects concurrent device rendering. output is validated against layout/frames.

Related types: ChannelLayout · BufferLayout · Status

Declared in modules/audio/include/ludus/audio/audio_system.h

ResumeFromUserGesture¶

Status ludus::audio::AudioSystem::ResumeFromUserGesture() noexcept

Must be called inside a genuine DOM activation handler on the browser.

Schedules resume; returns Pending/result.

Related types: Status

Declared in modules/audio/include/ludus/audio/audio_system.h

BeginShutdown¶

Status ludus::audio::AudioSystem::BeginShutdown() noexcept

Close admission, quiesce native callbacks and join the decode worker before reclaiming assets. Linux/macOS teardown is synchronous on the control owner.

Returns

Ok after native teardown (also on repeated completed shutdown), or NotReady before initialization. Native completion leaves Disabled state.

Related types: Status

Declared in modules/audio/include/ludus/audio/audio_system.h

GetShutdownState¶

ShutdownState ludus::audio::AudioSystem::GetShutdownState() const noexcept

Related types: ShutdownState

Declared in modules/audio/include/ludus/audio/audio_system.h

SetDebugSink¶

void ludus::audio::AudioSystem::SetDebugSink(AudioDebugSnapshotSink *sink) noexcept

Attach/detach an owner-side snapshot/trace sink.

Does not transfer ownership; the sink must outlive the attachment. Null detaches.

Related types: AudioDebugSnapshotSink

Declared in modules/audio/include/ludus/audio/audio_system.h

AcquireModifier¶

Status ludus::audio::AudioSystem::AcquireModifier(std::span< const ModifierValue > values, float32 weight, ModifierHandle &outModifier) noexcept

Acquire a bounded attenuation-modifier instance with per-bus dB targets and a weight in [0,1].

Returns a generation-checked ModifierHandle. Overlapping owners get distinct instances. AssetCapacity-style failure is reported as Status (no handle). The modifier ramps in on acquisition.

Related types: Status · ModifierHandle · ModifierValue

Declared in modules/audio/include/ludus/audio/audio_system.h

UpdateModifier¶

Status ludus::audio::AudioSystem::UpdateModifier(ModifierHandle modifier, float32 weight) noexcept

Update a modifier's weight (ramps). Generation-checked.

Related types: Status · ModifierHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

ReleaseModifier¶

Status ludus::audio::AudioSystem::ReleaseModifier(ModifierHandle modifier) noexcept

Release a modifier: fades its weight to zero, then retires its slot after the renderer acknowledges.

Removing one instance never removes another.

Related types: Status · ModifierHandle

Declared in modules/audio/include/ludus/audio/audio_system.h

IsValid¶

bool ludus::audio::AudioSystem::IsValid() const noexcept

True when construction + Initialize produced usable fixed storage.

Declared in modules/audio/include/ludus/audio/audio_system.h

Static methods¶

UserGainFromSlider¶

static float32 ludus::audio::AudioSystem::UserGainFromSlider(float32 u, float32 dbRange) noexcept

Map a normalized slider u in [0,1] through an explicit dB range to a UserGain amplitude: 0 at u==0 (exact mute), else 10^((u-1)*range/20).

Declared in modules/audio/include/ludus/audio/audio_system.h