Class System

Inheritance Relationships

Base Type

Class Documentation

class System : public CE::Audio::System

Declaration: final

Native-device or explicit offline miniaudio output, implementing the neutral synchronized voice/system contracts.

See also

Miniaudio integration

Public Functions

virtual ~System() override

Close output after external producers stop using this object; surviving Voice handles remain safe.

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

Declaration: [[nodiscard]]

Validate options, convert/retain PCM and publish a voice under the system lock.

Reclaims unreferenced inactive voices first. Closed/native/allocation failures throw; independent voices may share source PCM.

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

Declaration: [[nodiscard]]

Validate path/options and synchronously open streamed playback under the system lock.

Keep the file available for playback/restart. Closed/native/allocation failures propagate; options configure initial paused/looping/gain state.

virtual void set_volume(float volume) override

Set master linear gain after finite[0,1] validation.

Native failure throws before committing the cached gain; closed systems reject.

virtual float volume() const override

Declaration: [[nodiscard]]

Return the locked master gain; reject closed output.

virtual void maintain() override

Under the system lock, retire nonplaying voices whose only owner is the system.

Active playback and externally retained voices remain; closed output rejects.

virtual void close() noexcept override

Idempotently stop/retire all voices and uninitialize output under the shared lock.

Voice handles then report Closed.

virtual bool closed() const override

Declaration: [[nodiscard]]

Return whether output has been uninitialized, under the shared lock.

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

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() override

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 ::CE::Audio::PlaybackNotifications notification_snapshot() const override

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.

::CE::Runtime::ServiceAttachment pump_with(const ::CE::Runtime::RuntimeServices &services)

Declaration: [[nodiscard]]

Attach explicit platform-maintenance pumping after runtime initialization on the designated owner.

The move-only attachment controls pumping; it retains no audio output or borrowed System pointer. Set the event destination first. The application still owns producer settlement and output closure: close(), publish_notifications() for final outcomes, then release the attachment/system. Maintenance may also pump after explicit close. Destruction discards unpublished records without callbacks.

::CE::Audio::Format output_format() const

Declaration: [[nodiscard]]

Return a copied configured output format; closed systems reject.

std::string backend_name() const

Declaration: [[nodiscard]]

Return an owned backend identity string for diagnostics; closed systems reject.

void render(std::span<float> output)

Mix into borrowed interleaved float storage in offline mode only, serialized with controls/maintenance.

Size must contain complete output frames; empty spans are permitted. Native/closed mode and malformed sizes reject. Successful short reads are padded with silence while advancing the full requested interval. No span is retained; native failures can propagate after partial output/time changes.

Public Static Functions

static std::unique_ptr<System> open_device(::CE::Audio::Format output = {}, ::CE::Audio::PlaybackNotificationOptions notifications = {})

Declaration: [[nodiscard]]

Open native output at a validated mono/stereo 8..192kHz format.

Excludes miniaudio’s null backend; device/native/allocation failures throw. Playback advances independently on the native clock. Allocate the positive notification capacity before opening native output.

static std::unique_ptr<System> open_offline(::CE::Audio::Format output = {}, ::CE::Audio::PlaybackNotificationOptions notifications = {})

Declaration: [[nodiscard]]

Create output without opening a device.

Only render() advances the mixing clock; validate output as for open_device(). Allocate the positive notification capacity before initializing output.