Skip to content

ludus::audio

Ludus Wiki · API overview · Browse API

Namespace

Declared in modules/audio/content/include/ludus/audio/content/definitions.h

Enumerations

OwnerEventKind

enum class OwnerEventKind : uint8
An owner-side policy/admission diagnostic that is NOT a voice: a suppressed trigger, a rejected batch, or a failed preparation, tagged with the caller's numeric key so it can be correlated without inventing a VoiceHandle.

BatchRejected

BatchRejected

PreparationFailed

PreparationFailed

PolicySuppressed

PolicySuppressed

QueueFull

QueueFull

GroupRejected

GroupRejected

VoiceCapacityRejected

VoiceCapacityRejected

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

PolicyCause

enum class PolicyCause : uint8

None

None

Cooldown

Cooldown

AlreadyActive

AlreadyActive

TableFull

TableFull

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

ShutdownState

enum class ShutdownState : uint8
Browser async teardown progress (design section 10).

NotStarted

NotStarted

ClosingAdmission

ClosingAdmission

QuiescingRenderer

QuiescingRenderer

QuiescingWorker

QuiescingWorker

ClosingContext

ClosingContext

Complete

Complete

Failed

Failed

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

Status

enum class Status : uint8
Status: the single bounded result domain for public fallible calls.
Backend/library detail is mapped into these codes; an invalid handle is not overloaded with every failure reason (design section 3).

Ok

Ok

Pending

Pending

Disabled

Disabled

Suspended

Suspended

NotReady

NotReady

Unsupported

Unsupported

InvalidArgument

InvalidArgument

InvalidHandle

InvalidHandle

QueueFull

QueueFull

VoiceCapacity

VoiceCapacity

GroupCapacity

GroupCapacity

StreamCapacity

StreamCapacity

AssetCapacity

AssetCapacity

OutOfMemory

OutOfMemory

DecodeError

DecodeError

IoError

IoError

DeviceError

DeviceError

SequenceExhausted

SequenceExhausted

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

Mode

enum class Mode : uint8

Device

Device

Offline

Offline

Disabled

Disabled

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

SystemState

enum class SystemState : uint8

Starting

Starting

Ready

Ready

Suspended

Suspended

Disabled

Disabled

Stopping

Stopping

Failed

Failed

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

ChannelLayout

enum class ChannelLayout : uint8
Channel / buffer contracts (design section 5).
Channel meaning, layout, frame count and writable sample capacity are named explicitly. A frame holds one sample per channel; SampleValues = Frames * Channels (checked usize).

Mono

Mono

Stereo

Stereo

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

BufferLayout

enum class BufferLayout : uint8

Interleaved

Interleaved

Planar

Planar

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

SourceFormat

enum class SourceFormat : uint8
Supported prepared source formats (design section 9).
Everything else is rejected with Status::Unsupported.

Wav

Wav

Flac

Flac

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

AttenuationOrigin

enum class AttenuationOrigin : uint8
Which position drives distance attenuation for a positional voice.

Listener

Listener

PanningPosition

PanningPosition

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

VirtualPolicy

enum class VirtualPolicy : uint8

AdvanceWhenVirtual

AdvanceWhenVirtual

KillWhenInaudible

KillWhenInaudible

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

VoiceState

enum class VoiceState : uint8

Pending

Pending

Scheduled

Scheduled

Mixed

Mixed

Virtualizing

Virtualizing

Virtual

Virtual

Stopping

Stopping

Terminal

Terminal

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

PreparationState

enum class PreparationState : uint8

Preparing

Preparing

Ready

Ready

Failed

Failed

Retiring

Retiring

Reclaimed

Reclaimed

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

StateCause

enum class StateCause : uint8
Numeric cause attached to every voice state change (design sections 3, 11).

None

None

PlayConsumed

PlayConsumed

StartFrameReached

StartFrameReached

SelectedAudible

SelectedAudible

LostSelectionGroupQuota

LostSelectionGroupQuota

LostSelectionGlobalBudget

LostSelectionGlobalBudget

LostSelectionAudibility

LostSelectionAudibility

ReselectedReversed

ReselectedReversed

HigherPriorityDisplaced

HigherPriorityDisplaced

StopRequested

StopRequested

StopAllEpoch

StopAllEpoch

NaturalEof

NaturalEof

Expired

Expired

FadeComplete

FadeComplete

PreparationFailed

PreparationFailed

Cancelled

Cancelled

StreamError

StreamError

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

TerminalReason

enum class TerminalReason : uint8
Terminal reason recorded in the durable mailbox (design section 4).

None

None

Completed

Completed

Stopped

Stopped

Cancelled

Cancelled

Expired

Expired

Killed

Killed

DecodeFailed

DecodeFailed

StreamError

StreamError

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

SilenceCause

enum class SilenceCause : uint16
Independent silence cause flags (design section 11).
Multiple may coexist, so this is a bitset, not a single enum. The current flags fit in 16 bits; the bitwise operators widen to uint32 for safe shifting.

None

None = 0

NotStarted

NotStarted = 1U << 0

DistanceZero

DistanceZero = 1U << 1

UserMuted

UserMuted = 1U << 2

BelowThreshold

BelowThreshold = 1U << 3

GroupQuota

GroupQuota = 1U << 4

GlobalBudget

GlobalBudget = 1U << 5

WaitingForFadeSlot

WaitingForFadeSlot = 1U << 6

Stopping

Stopping = 1U << 7

StreamStarved

StreamStarved = 1U << 8

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

CommandKind

enum class CommandKind : uint8
A command record published in a batch (design section 4).
The kind selects which payload is meaningful. BatchLocalPlayIndex lets an Update/Stop target a Play reserved earlier in the same batch before handles are finalized.

Play

Play

UpdateVoice

UpdateVoice

StopVoice

StopVoice

SetListener

SetListener

SetBusBaseGain

SetBusBaseGain

SetBusUserGain

SetBusUserGain

AddModifier

AddModifier

UpdateModifier

UpdateModifier

RemoveModifier

RemoveModifier

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

Constants and variables

LOGICAL_VOICE_CAPACITY

constexpr usize ludus::audio::LOGICAL_VOICE_CAPACITY = 256
resident logical slots

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

MIXED_VOICE_CAPACITY

constexpr usize ludus::audio::MIXED_VOICE_CAPACITY = 64
total mixed incl. tails + streams

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

RESIDENT_STEADY_SELECT

constexpr usize ludus::audio::RESIDENT_STEADY_SELECT = 56
steady-state resident selection ceiling

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

STREAM_CAPACITY

constexpr usize ludus::audio::STREAM_CAPACITY = 4
protected stream instances

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

GROUP_CAPACITY

constexpr usize ludus::audio::GROUP_CAPACITY = 16
resident concurrency groups

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

BUS_CAPACITY

constexpr usize ludus::audio::BUS_CAPACITY = 16
buses in the static tree

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

MODIFIER_CAPACITY

constexpr usize ludus::audio::MODIFIER_CAPACITY = 8
active attenuation modifier instances

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

COMMAND_QUEUE_CAPACITY

constexpr usize ludus::audio::COMMAND_QUEUE_CAPACITY = 512
queued command records (SPSC ring)

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

MAX_BATCH_RECORDS

constexpr usize ludus::audio::MAX_BATCH_RECORDS = 32
records per TrySubmitBatch

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

CONTROL_BOUNDARY_BUDGET

constexpr usize ludus::audio::CONTROL_BOUNDARY_BUDGET = 64
applied commands per 128-frame quantum

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

STREAM_RING_FRAMES

constexpr usize ludus::audio::STREAM_RING_FRAMES = 32768
stereo frames per stream ring (8 x 4096)

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

STREAM_CHUNK_FRAMES

constexpr usize ludus::audio::STREAM_CHUNK_FRAMES = 4096
frames per stream chunk

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

STREAM_CHUNK_COUNT

constexpr usize ludus::audio::STREAM_CHUNK_COUNT = 8
chunks per stream ring

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

CONTROL_QUANTUM_FRAMES

constexpr uint32 ludus::audio::CONTROL_QUANTUM_FRAMES = 128
control boundary granularity

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

DEFAULT_SAMPLE_RATE

constexpr uint32 ludus::audio::DEFAULT_SAMPLE_RATE = 48000
typical session rate

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

DEFAULT_DEVICE_PERIOD_FRAMES

constexpr uint32 ludus::audio::DEFAULT_DEVICE_PERIOD_FRAMES = 256
native request hint

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

DEFAULT_RAMP_MS

constexpr uint32 ludus::audio::DEFAULT_RAMP_MS = 5
default transition duration

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

MAX_SCHEDULE_HORIZON_SECONDS

constexpr uint32 ludus::audio::MAX_SCHEDULE_HORIZON_SECONDS = 2
StartFrame lookahead bound.

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

COLD_DECODE_UNIT_FRAMES

constexpr uint32 ludus::audio::COLD_DECODE_UNIT_FRAMES = 4096
yield granularity for cold worker

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

PRIORITY_MIN

constexpr uint8 ludus::audio::PRIORITY_MIN = 0

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

PRIORITY_MAX

constexpr uint8 ludus::audio::PRIORITY_MAX = 7

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

RATE_MIN

constexpr float32 ludus::audio::RATE_MIN = 0.5F

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

RATE_MAX

constexpr float32 ludus::audio::RATE_MAX = 2.0F

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

GROUP_MAX_ADMITTED_LIMIT

constexpr uint32 ludus::audio::GROUP_MAX_ADMITTED_LIMIT = 256

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

GROUP_MAX_SELECTED_LIMIT

constexpr uint32 ludus::audio::GROUP_MAX_SELECTED_LIMIT = 56

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

DEFAULT_USER_GAIN_DB_RANGE

constexpr float32 ludus::audio::DEFAULT_USER_GAIN_DB_RANGE = 40.0F

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

MODIFIER_DB_MIN

constexpr float32 ludus::audio::MODIFIER_DB_MIN = -96.0F

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

MODIFIER_DB_MAX

constexpr float32 ludus::audio::MODIFIER_DB_MAX = 0.0F

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

RESIDENT_PCM_CAP_BYTES

constexpr uint64 ludus::audio::RESIDENT_PCM_CAP_BYTES = 64ULL * 1024 * 1024

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

BROWSER_ENCODED_CAP_BYTES

constexpr uint64 ludus::audio::BROWSER_ENCODED_CAP_BYTES = 32ULL * 1024 * 1024

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

STREAM_RING_TOTAL_BYTES

constexpr uint64 ludus::audio::STREAM_RING_TOTAL_BYTES = 1ULL * 1024 * 1024

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

CORE_RUNTIME_CAP_BYTES

constexpr uint64 ludus::audio::CORE_RUNTIME_CAP_BYTES = 2ULL * 1024 * 1024

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

kNoParent

constexpr uint32 ludus::audio::kNoParent = 0xFFFFFFFFU

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

Functions

InspectSource

Status ludus::audio::InspectSource(std::span< const uint8 > encoded, SourceFormat format, SourceInfo &output, std::span< float32 > peaks={}) noexcept
Cold, bounded scratch decode. peaks receives max absolute values in equal source-frame ranges; an empty span requests metadata without a full scan.

Related types: SourceFormat · Status · SourceInfo

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

InspectSource

Status ludus::audio::InspectSource(StreamInput &input, SourceFormat format, SourceInfo &output, std::span< float32 > peaks={}) noexcept

Related types: StreamInput · SourceFormat · Status · SourceInfo

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

IsOk

constexpr bool ludus::audio::IsOk(Status status) noexcept

Related types: Status

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

ToString

const char * ludus::audio::ToString(Status status) noexcept
Stable, bounded, allocation-free diagnostic name. Returns a static string.

Related types: Status

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

ChannelCount

constexpr uint32 ludus::audio::ChannelCount(ChannelLayout layout) noexcept

Related types: ChannelLayout

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

operator|

constexpr SilenceCause ludus::audio::operator|(SilenceCause a, SilenceCause b) noexcept

Related types: SilenceCause

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

operator&

constexpr SilenceCause ludus::audio::operator&(SilenceCause a, SilenceCause b) noexcept

Related types: SilenceCause

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

operator|=

constexpr SilenceCause & ludus::audio::operator|=(SilenceCause &a, SilenceCause b) noexcept

Related types: SilenceCause

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

HasCause

constexpr bool ludus::audio::HasCause(SilenceCause set, SilenceCause flag) noexcept

Related types: SilenceCause

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