Class System

Inheritance Relationships

Derived Type

Class Documentation

class System

Application-owned audio output and voice lifetime, independent of graphics.

Play/stream/control/maintenance/close are synchronized across producers. Playback progresses on the backend clock, without update or render admission. Device opening, decode and initial stream opening may block; prepare them outside latency-sensitive simulation work. Stream paths remain required until playback ends. No game callback runs from the native mixing thread. Destroy/close stops output and retires voices before native output state. The application settles producers before destroying this object. Surviving Voice handles remain safe. After close, only closure/notification operations remain available.

Subclassed by CE::Audio::Miniaudio::System

Public Functions

virtual ~System() = default

Close output and retire voices after producers quiesce.

Voice handles can survive safely but cannot continue playback.

virtual std::shared_ptr<::CE::Audio::Voice> play(const ::CE::Audio::Clip &clip, ::CE::Audio::PlaybackOptions options = {}) = 0

Declaration: [[nodiscard]]

Admit an independent voice retaining the immutable clip data.

Options are copied; initial conversion/admission may block and fail. Playback progresses on the backend clock without game updates. Return a retained control handle; releasing it does not stop active playback.

See also

Audio output

virtual std::shared_ptr<::CE::Audio::Voice> stream(const std::filesystem::path &file, ::CE::Audio::PlaybackOptions options = {}) = 0

Declaration: [[nodiscard]]

Open an independent streaming voice, copying path/options.

Keep source files available until playback ends and for later restart; opening may block/fail. No game callback executes on the native mixer thread.

virtual void set_volume(float volume) = 0

Set synchronized master linear gain in inclusive[0,1], independently of per-voice gain.

Invalid/nonfinite values and closed systems reject.

virtual float volume() const = 0

Declaration: [[nodiscard]]

Return synchronized master gain; closed-system queries reject.

virtual void maintain() = 0

Reclaim Finished/Stopped/Paused voices with no application handle.

Call regularly; this does not advance the backend clock. Closed systems reject.

virtual void close() noexcept = 0

Idempotently stop output and retire voices before backend state.

Synchronize producers before destruction; surviving Voice snapshots become Closed and controls throw. Notification-capable backends stage unfinished terminal outcomes without listeners and permit a final publish_notifications() after close. Destruction discards unpublished observations.

virtual bool closed() const = 0

Declaration: [[nodiscard]]

Return synchronized output closure state; remains callable after close().

virtual void publish_events_to(::CE::Events::EventBus::Publisher publisher)

Choose a weak notification destination and designate the calling thread as publication owner.

Call before pumping/attaching services. A configured source rejects foreign-owner changes and changes during publication. Empty publishers discard attempts. Unsupported backends throw.

virtual void publish_notifications()

Observe completion and attempt pending outcomes through the entry sequence cutoff on the designated owner (the first pump designates it if unconfigured).

Never call recursively. Listeners run outside audio locks; their new records wait for a later pump. Allowed after close for final outcomes. Each record has one attempt; bus failure has no retry. Unsupported backends throw.

virtual PlaybackNotifications notification_snapshot() const

Declaration: [[nodiscard]]

Return synchronized closure, sequence and bounded-loss observations without invoking listeners.

Default backends return system zero. Retain individual Voice snapshots to reconcile a live generation after a gap; neither snapshot recovers superseded playback history.