Class Voice
Defined in File system.h
Class Documentation
-
class Voice
One independently controlled playback.
Controls and snapshots are synchronized. Pause preserves progress and cancels a scheduled start; 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 or Scheduled voice while retaining progress and cancelling any pending start.
Other states need not change. Controls reject after system close and native failures can propagate.
-
virtual void resume() = 0
Resume only a Paused voice immediately from retained progress; a cancelled delay is not restored.
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 immediate fresh playback from frame zero, cancelling a pending start and preserving volume/looping/playback rate.
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.
-
virtual void set_playback_rate(float rate)
Set source speed and pitch together, without seeking or changing playback state.
Requires variable_rate playback; validate finite[0.125,8]. Preserved by restart. Synchronized like other controls; closed output and unsupported backends reject.
-
virtual void resume_after(std::chrono::duration<double> delay)
Arm a Paused voice to resume its existing source cursor after finite nonnegative output-clock seconds.
Zero resumes immediately. On supporting backends other live states are unchanged; pause first to replace an existing schedule. Unsupported backends reject with bad_request, including zero; closed output rejects controls. Scheduling does not create a playback generation or terminal outcome. Pause cancels the pending start while preserving the cursor; a subsequent resume() is immediate. Stop cancels and remains terminal; restart cancels and starts from source frame zero immediately. A scheduled voice stays active after its application handle is released. Backend clock quantization, buffering and source processing determine audible timing; acceptance is not a wall-clock or hardware sample-accuracy guarantee. Invalid delay, clock overflow or native start failure must not arm a previously paused voice.
See also
-
virtual ~Voice() = default