Class Voice

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

Delayed playback