Audio ownership and playback
Use this reference to manage independent playback, voice controls and output
shutdown. For a first sound, follow
miniaudio preparation and output:
link Cheryl::Audio::Miniaudio, create an application-owned system, prepare a clip and
call play(). This page defines the lifetime and failure rules around that sequence.
The public audio contracts belong
to Engine and contain no SDK, device or graphics types. Applications own an audio
system independently of CE::Runtime::Context and compose a selected audio module through
its public CMake target. Engine has no reverse dependency on that module.
Clips and voices
CE::Audio::Clip::from_samples takes owned interleaved float PCM, with mono/stereo
channels and a sample rate between 8 and 192 kHz. Data is nonempty, frames are
complete, and every sample is finite. The nominal sample range is [-1, 1];
storage does not clamp samples or change their rate. Copies share immutable
storage. Moving preserves the original valid snapshot. Clip creation does not
open a device. Its frame count and duration describe source audio, independently
of a mixer’s output rate.
CE::Audio::System::play creates a voice with an independent cursor. Voices can share
a clip without sharing playback progress. stream opens file-backed playback for
music; the file must remain available until playback ends. Decode and initial file
opening are synchronous preparation operations, so applications perform them at
loading boundaries or dispatch owned decode requests through their worker groups.
flowchart LR
accTitle: Shared clips and independent voices
accDescr: An audio system retains two voices with independent playback cursors. Both voices can use the same immutable clip storage.
system["Audio system"] -->|retains playback| first["Voice A and cursor A"]
system -->|retains playback| second["Voice B and cursor B"]
first -->|reads| clip["Shared immutable clip"]
second -->|reads| clip
Voice and master volumes are normalized linear gains in [0, 1], with zero as
mute. Invalid/non-finite gains throw. Multiple voices are mixed; overlapping loud
sources can exceed nominal PCM amplitude and applications manage their mix levels.
Operation/state |
Behavior |
|---|---|
Initial playback |
Starts immediately, or starts |
|
Pauses a playing voice and preserves progress. |
|
Resumes a paused voice; other live states are unchanged. |
Arms a paused voice; |
|
|
Leaves the voice |
Natural end |
Reports |
|
Requests source frame zero and starts playback. |
|
Changes the loop policy without restarting stopped/finished playback. |
System closure |
Surviving handles report |
Snapshots copy playback state, volume, loop policy, playback rate and known source duration. Backends supporting outcomes also supply system/voice identity, generation and an immutable optional terminal fact as described below. They are observations, not an atomic freeze of native playback. Live decoder cursors are outside the initial API; reading them concurrently with mixing needs additional synchronization. No game callback runs on the mixing thread.
Change playback speed
Opt in when creating a voice, then retain that handle to control it. With
audio and effect from the miniaudio setup,
replace its effect-play line with:
auto voice = audio->play(effect, {.volume = 0.5f, .variable_rate = true});
voice->set_playback_rate(2.0f);
const auto observed_rate = voice->snapshot().playback_rate;
set_playback_rate() accepts a finite multiplier in [0.125, 8]; 1 is normal,
2 plays twice as fast and 0.5 half as fast. Pitch follows speed. This is not
pitch-preserving time stretching or an independent pitch control. A successful
restart preserves the selected rate. Snapshot duration remains the original
source duration, not the rate-adjusted wall time or a remaining-time estimate.
The same PlaybackOptions::variable_rate option applies to stream(). Select it
before playback; miniaudio rejects rate changes on a voice opened without it,
including an attempt to set rate 1. Normal voices avoid the extra variable-rate
processing path and its latency. Other backends can reject this optional control;
choose a supporting backend or use an application fallback when speed is required.
Do not assume the base interface guarantees support.
During game updates, call voice->set_playback_rate(rate) when the desired rate
changes, using the retained live voice. Validate the game’s rate against the audio
range rather than passing an uncapped world-speed value. Controls take effect at
backend processing boundaries; they do not retime already queued device output.
Schedule a delayed start
Prepare a paused voice, then arm it using a std::chrono::duration. With the
existing miniaudio audio system and decoded effect, a 22 ms delayed effect is:
auto delayed = audio->play(effect, {.volume = 0.5f, .paused = true});
delayed->resume_after(std::chrono::milliseconds{22});
Include <chrono>. A paused voice from stream() uses the same operation.
Preparing the voice first keeps synchronous source opening outside the delay.
resume_after() measures finite nonnegative seconds from control admission on
the output clock; zero resumes immediately. Miniaudio rounds positive delays up
to output frames and rejects a delay or deadline outside its frame-counter range.
The base Voice implementation rejects this optional capability with bad_request,
including zero, so other backends need not silently pretend to schedule playback.
While waiting, the snapshot reports PlaybackState::Scheduled. Device mixing
advances the deadline independently of simulation; offline output advances only
through render(). Neither maintain() nor notification pumping advances time.
Keep Scheduled alongside Playing when tracking active effects. Releasing the
handle does not cancel an armed start; maintenance retains it until inactive.
Control |
Effect on a pending start |
|---|---|
Cancels the deadline, keeps the source cursor, and reports |
|
|
Resumes immediately; it does not restore a cancelled delay. |
|
Leaves playback unchanged; pause first to choose another delay. |
|
Cancels and reports |
Cancels and immediately restarts source frame zero, preserving volume, looping and playback rate. |
|
Output closure |
Cancels playback; surviving handles report |
Scheduling itself creates no generation or terminal notification. Completion, stop, restart/replacement and closure retain their ordinary outcome rules. Invalid delays, frame-clock overflow and native start failure leave the paused voice unarmed. Changing playback rate changes source speed/pitch without scaling its output-clock delay. Buffered output, decoder readiness and resampler latency still affect audible onset; this API promises neither wall-clock deadlines nor hardware sample accuracy.
For a volley, prepare its voices paused and arm each with its own delay. Individual calls measure from their own admission; this is not an atomic group or a shared absolute timestamp. Keep a premixed clip when exact relative sample offsets are required. Delayed starts remove dependence on a later simulation tick without providing absolute-time or batch scheduling.
Playback outcomes
CE::Audio::playback_ended_event reports one logical terminal outcome for each
admitted playback generation. The miniaudio backend implements it; other audio
systems can leave this optional extension unsupported. Its plain PlaybackEnded
payload owns checked system/voice identity, generation, terminal reason/sequence/
observation time and cumulative loss information. It retains no Voice or native
objects. Voice identity stays stable across restart; a successful restart admits
the next generation and clears only that new generation’s terminal fact.
Terminal reason |
Selection |
|---|---|
|
Native EOF was observed before another terminal operation. |
|
Stop succeeded, including when a restart stops the old voice but cannot start its replacement. |
|
A new generation successfully replaced unfinished playback. |
|
Output closed before another terminal outcome was observed. |
|
Maintenance reclaimed an unreferenced inactive generation, such as paused playback. |
Failed initial play/stream admits no generation and fabricates no outcome. Replacement preparation failure preserves the old generation. Failure to stop it admits no successor. After a successful old stop, a failed replacement start ends the old generation as Stopped unless Completed was already observed. Successful restart marks an unfinished predecessor Replaced. Pause/resume and loop iterations do not create terminal outcomes.
Terminal facts never change within a generation: observing EOF before stop or
close preserves Completed. set_looping() cannot resurrect completed playback.
After output closes, VoiceSnapshot.state reports Closed while its terminal
reason remains available. These are owner-observed logical outcomes rather than
sample-accurate claims about a mixer race.
Publish on an explicit owner
Call audio->publish_events_to(bus.publisher()) to choose a weak route and
designate the calling thread as notification owner. The backend stages terminal
records under its audio mutex, and publish_notifications() invokes listeners
outside that mutex on the designated owner. Neither controls, close, maintenance
nor the mixer invoke game listeners directly. Without prior configuration, the
first pump designates its caller; an empty route discards publication attempts.
Route changes require that same owner outside an active pump.
Each pump observes completion even for externally retained voices and drains only through its entry sequence cutoff. A listener’s newly staged outcomes wait for a later pump; recursive pumping rejects. The source reserves terminal-counter capacity before native effects so admitted unfinished generations can still end during noexcept close. Observation storage is a separate bound: miniaudio defaults to 1,024 preallocated records, configurable when opening output. Overflow drops the oldest pending record rather than rejecting playback or waiting for observers.
notification_snapshot() exposes source sequence, closure, capacity, pending
count and loss count/range. System ID zero means unsupported; unsupported default
routing/pump operations throw. A retained Voice’s current-generation snapshot
recovers its terminal fact after a gap. Neither snapshot recovers superseded
generation history. Each retained record gets one publication attempt; bus/queue
failure has no automatic retry or exactly-once delivery guarantee.
sequenceDiagram
accTitle: Audio outcomes are delivered by the owner pump
accDescr: Stop stages a terminal outcome under the audio lock. The owner pump removes staged records and notifies listeners outside that lock. Explicit close can be followed by a final pump; destruction discards unpublished observations.
participant Game as Producer
participant Audio as Audio system
participant Owner as Notification owner
participant Bus as Chosen EventBus
participant Listener
Game->>Audio: voice.stop()
Audio->>Audio: Commit terminal fact and stage record
Audio-->>Game: return without callbacks
Owner->>Audio: publish_notifications()
Audio->>Bus: notify(playback_ended_event, record)
Bus->>Listener: callback(record)
Bus-->>Audio: return
Audio-->>Owner: return
Lifetime and scheduling
Controls, submissions, snapshots and maintenance are synchronized across application producers. Their order follows control admission, rather than a deterministic simulation clock. Device playback progresses on its own clock without render or simulation admission. Offline processing is explicitly selected; an unavailable native device must not silently produce inaudible success.
Skipping world updates for a pause does not pause device playback. Retain the
music/effect voices that should pause and call their pause()/resume() controls
at the game’s transition boundary. Decide which menu sounds continue, and track
which voices the pause suspended so resume does not start independently paused
playback. Keep audio maintenance, and notification pumping when used, running
while the world is paused.
Calling play() on successive simulation ticks gives tick scheduling. Use
resume_after() on prepared paused voices for an
output-clock delay; use a premixed PCM clip when a group needs exact relative
sample offsets.
The system retains active playback after the application releases its voice
handle. Call maintain regularly to reclaim completed/stopped/paused voices that
have no application handles. Maintenance does not advance playback. Discarded
looping voices remain active until system closure; retain their handles when they
need individual control.
Create the system before playback. Settle all producers before destroying it.
close is idempotent, stops output, retires native voices before their mixer/device,
and leaves surviving handles safe. A system cannot reopen; construct another
system for a new session. Audio need not share the graphics owner’s thread, and
this contract does not add audio to the runtime’s existing adapter teardown.
For final observations, settle producers, call close(), then
publish_notifications() on the designated owner before releasing subscriptions
and the system. Publication remains allowed after close; destruction only cleans
up and discards unpublished records. The optional
runtime notification pump
does not transfer audio lifetime or producer settlement to Runtime.
Backends and limits
The miniaudio module supplies CPU decode, explicit device/offline output and streamed playback. Its independent consumer provides native observation without a game, window or graphics module. Linux root-assembly native stereo output and sustained WAV streaming are accepted; the module guide owns reusable validation and compressed-stream, composition and platform coverage limits.
World, entity and collision organization belongs to the game or its application-selected modules. FMOD is a later optional backend; Studio authoring formats/capabilities require a separate contract.