AudioPlayerHandle

Seconds of audio consumed since the current play() call. Resets on reset() and on media changes.

Total duration in seconds, when knowable. The element strategy exposes this once loadedmetadata fires; the pcm strategy leaves it undefined (PCM duration isn't known until message-finish).

Last error raised by the stream reader, decoder, or element.

RMS level of the last analysed frame, normalised to [0, 1]. Drop-in for a VU meter. 0 when no analyser frame has been read yet, when paused, or before play().

Current lifecycle state. See PlayerStatus.

Which implementation is active. "pcm" scheduling through AudioContext starts within one chunk of the first byte; "element" waits for message-finish before a hidden HTMLAudioElement takes over.

Current 256-bin frequency-domain snapshot from the internal AnalyserNode. Returns undefined before the graph is connected or on environments without Web Audio. Safe to poll inside requestAnimationFrame.

Current 256-sample waveform snapshot (byte time-domain) from the internal AnalyserNode. Returns undefined before the graph is connected or on environments without Web Audio.

Pause without discarding buffered samples / element position.

Start (or resume) playback. No-op while status === "error".

Resolve on the next terminal transition (finished | paused | idle). Reject on transitions to "error". Calling stop() or reset() resolves the pending promise immediately. Calling playToEnd also triggers play() if currently paused/idle.

Reset back to "idle" and drop any transient error. The next play() starts fresh from the current position.

Seek to an absolute timestamp in seconds. Only defined on the element strategy; undefined on pcm (random-access seeking of a live scheduled buffer is not supported).

Hard stop: tears down the AudioContext (PCM) or detaches the element (element) and drops any scheduled work.

Sugar for status === "playing" ? pause() : play().