#Interface: SyncedAudio

A local audio player following Plot's synchronized clock.

Create through Plot.toolkit.syncedAudio(). Each client must receive the same assets and playback anchor. Methods do not send multiplayer commands.

#See

• Synchronized audio
• Error handling

#Properties

#anchor

readonly anchor: SyncedAudioAnchor | null

Immutable latest requested anchor, retained while paused; null with no request.

---

#currentTime

readonly currentTime: number

Intended audio position in seconds, wrapping within [introDuration, introDuration + loopDuration) after the intro; frozen while paused. Zero with no request, NaN before required durations are known. This is not a measurement of sound at the speaker. Clock failures throw PlotError.

---

#duration

readonly duration: number

Standard seconds, Infinity for loaded loops, or NaN before loading.

---

#elapsedTime

readonly elapsedTime: number

Intended unwrapped audio seconds including resume offset, held before a future start and frozen while paused. Standard audio clamps to its known duration. Zero with no request. Clock failures throw PlotError.

---

#error

readonly error: PlotError | null

Last operational failure, cleared by a new valid attempt.

---

#introDuration

readonly introDuration: number

Intro seconds, zero if absent, or NaN before loading.

---

#introSrc

readonly introSrc: string | null

Resolved intro URL, or null without an intro.

---

#loop

readonly loop: boolean

Whether the source repeats indefinitely.

---

#loopDuration

readonly loopDuration: number

Loop seconds, zero for standard playback, or NaN before loading.

---

#muted

muted: boolean

Local mute without pausing the timeline. Non-boolean assignments throw TypeError; disposed assignments throw PlotError.

---

#src

readonly src: string

Resolved source URL, immutable for this object's lifetime.

---

#state

readonly state: SyncedAudioState

Local playback status.

---

#volume

volume: number

Local linear gain in [0,1]. Invalid assignments throw TypeError; disposed assignments throw PlotError.

#Methods

#dispose()

dispose(): void

Permanently stops and releases this object. Safe repeatedly; other audio objects continue.

#Returns

void

---

#load()

load(): Promise<void>

Fetches and decodes all clips, without playing or starting Plot readiness.

#Returns

Promise<void>

Shared loading promise, rejecting with PlotError on asset/browser failures.

---

#onEnded()

onEnded(listener): Unsubscribe

Observes future standard completions once per request, not pauses/stops or loop boundaries.

#Parameters

#listener

(event) => void

#Returns

Unsubscribe

An idempotent unsubscribe function.

#Throws

TypeError synchronously for a non-function listener; PlotError after disposal.

---

#onError()

onError(listener): Unsubscribe

Observes operational failures; validation and intentional cancellation do not emit errors. A pending failed method also rejects, so choose one path for error UI.

#Parameters

#listener

(error) => void

#Returns

Unsubscribe

An idempotent unsubscribe function.

#Throws

TypeError synchronously for a non-function listener; PlotError after disposal.

---

#pause()

pause(): void

Freezes this object's logical position and cancels pending/active playback. Does not pause Plot time or other audio. Repeated calls are safe. With no playback request it does nothing, including during preload before readiness.

#Returns

void

#Throws

PlotError synchronously after disposal or if the clock cannot be read.

---

#play()

play(startAtGameTimeMs): Promise<void>

Plays from audio position zero at a shared game timestamp; catches up if late. Equivalent to resume(0, startAtGameTimeMs). Repeating the same active request is safe.

#Parameters

#startAtGameTimeMs

number

Safe-integer timestamp from Plot.time.now().

#Returns

Promise<void>

Resolves once scheduled or already elapsed, not at audible completion.

#Throws

TypeError by rejection for invalid input; PlotError by rejection before readiness, during disconnect, on browser/asset failure, or when cancelled.

---

#resume()

resume(offsetSeconds, resumeAtGameTimeMs): Promise<void>

Schedules an explicit position at a shared timestamp, even without a prior pause. Before the timestamp the object is silent; late playback skips elapsed content.

#Parameters

#offsetSeconds

number

Finite nonnegative unwrapped audio seconds, including intro and complete loop iterations. Use one shared offset for all players.

#resumeAtGameTimeMs

number

Safe-integer timestamp from Plot.time.now().

#Returns

Promise<void>

Resolves once scheduled or already elapsed. Does not await the timestamp.

#Throws

TypeError by rejection for invalid arguments; PlotError by rejection on readiness, connection, browser, loading, cancellation, or disposed-object failures.

---

#stop()

stop(): void

Cancels playback and clears position/anchor; keeps assets. Safe repeatedly, even after disposal.

#Returns

void

---

#subscribe()

subscribe(listener): Unsubscribe

Immediately receives an immutable local snapshot and subsequent changes. Listener errors are isolated; this is not a per-frame progress event.

#Parameters

#listener

(snapshot) => void

#Returns

Unsubscribe

An idempotent unsubscribe function.

#Throws

TypeError synchronously for a non-function listener; PlotError after disposal.