Class Voice

Class Documentation

class Voice

One independently controlled playback.

Controls and snapshots are synchronized. Pause preserves progress; resume affects only Paused voices. Stop is terminal until restart explicitly requests frame zero. Finished voices also need restart. Changing looping does not restart a stopped/finished voice. Snapshot state can change immediately afterward as native playback progresses. A handle may survive its system: snapshot then reports Closed, and controls throw. Releasing a handle does not stop an active voice; the system retains playback.

Public Functions

virtual ~Voice() = default

Release the application handle without implicitly stopping an active voice; the owning system retains active playback.

virtual ::CE::Audio::VoiceSnapshot snapshot() const = 0

Declaration: [[nodiscard]]

Return a synchronized owned state observation.

Surviving handles report Closed after system close; no progress lock is retained by the returned value.

virtual void pause() = 0

Suspend a Playing voice while retaining progress; other states need not change.

Controls reject after system close and native failures can propagate.

virtual void resume() = 0

Resume only a Paused voice from retained progress.

Stopped/Finished voices require restart(); controls reject after system close.

virtual void stop() = 0

Stop playback terminally until restart() explicitly requests frame zero.

Does not destroy this handle; closed systems reject controls. Outcome-capable backends preserve an already observed Completed terminal reason rather than overwriting it with Stopped. Controls stage outcomes; only the owner pump invokes listeners.

virtual void restart() = 0

Request fresh playback from frame zero, preserving volume/looping.

Source/device failures can propagate; streaming restart may reopen the retained file. Concrete backends define failure effects beyond the common closed-system rejection.

virtual void set_volume(float volume) = 0

Set synchronized per-voice linear gain, inclusive[0,1].

Invalid/nonfinite volume rejects; system closure rejects even if the handle survives.

virtual void set_looping(bool looping) = 0

Change looping without restarting a stopped/finished voice.

Closed-system controls reject.