Skip to content

IAudioBackend

Concrete contract every audio backend implements. The player calls these methods; plugins tap outputNode() and analyserSource() to build effect chains.

TypeScript
import type { IAudioBackend } from '@nomercy-entertainment/nomercy-music-player/adapters/audio-backend';

kind

TypeScript
readonly kind: AudioBackendKind  // 'audio-element' | 'webaudio'

Discriminates the backend type. Use .kind to branch; do not compare the return value of player.backend() as a string.

TypeScript
const backend = player.backend();
if (backend.kind === 'webaudio') {
  // WebAudioBackend-specific code
}

Lifecycle

load(url, opts?)

TypeScript
load(url: string, opts?: { preload: 'auto' | 'metadata' | 'none' }): Promise<void>

Load and preload a media URL. Resolves when the backend is ready to play.

unload()

TypeScript
unload(): void

Detach the current source. Does not dispose the backend.

dispose()

TypeScript
dispose(): void

Tear down the backend: pause, disconnect all nodes, release all resources. After dispose(), the backend must not be used.

Transport

play()

TypeScript
play(): Promise<void>

Start or resume playback.

pause()

TypeScript
pause(): void

Pause playback.

stop()

TypeScript
stop(): void

Stop playback and reset position to 0.

Time

currentTime()

TypeScript
currentTime(): number
currentTime(seconds: number): void

Get or set the current playback position in seconds.

duration()

TypeScript
duration(): number

Total duration in seconds. May return NaN or 0 before metadata loads.

buffered()

TypeScript
buffered(): number

Seconds of audio buffered ahead of the current position.

bufferedRanges()

TypeScript
bufferedRanges(): TimeRanges

All buffered time ranges.

seekable()

TypeScript
seekable(): TimeRanges

Seekable time ranges.

playbackRate()

TypeScript
playbackRate(): number
playbackRate(rate: number): void

Get or set the playback rate.

Volume

volume()

TypeScript
volume(): number
volume(level: number): void

Get or set the volume (0–1 scale at the backend level; the player converts from its 0–100 scale).

mute()

TypeScript
mute(): void

Silence output without changing the stored volume.

unmute()

TypeScript
unmute(): void

Restore output.

State

state()

TypeScript
state(): BackendState

BackendState values: 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'error'

Effect chain

outputNode(ctx)

TypeScript
outputNode(ctx: AudioContext): AudioNode

The output node of the backend’s audio graph. Connect your processing chain here.

analyserSource(ctx)

TypeScript
analyserSource(ctx: AudioContext): AudioNode

A tap node suitable for AnalyserNode connection (spectrum, waveform visualization). Does not interrupt the main signal path.

Raw access

mediaElement()

TypeScript
mediaElement(): HTMLMediaElement

The underlying <audio> element. Used by Cast SDKs and other integrations that need direct element access.

Capture

captureStream()

TypeScript
captureStream(): MediaStream

MediaStream of the audio output. Use for recording, WebRTC, or piping to <video>.

Audio output routing

setSinkId(deviceId)

TypeScript
setSinkId(deviceId: string): Promise<void>

Route audio to a specific output device.

getSinkId()

TypeScript
getSinkId(): string

Id of the current output device.

DRM (planned v2.1)

mediaKeys()

TypeScript
mediaKeys(): MediaKeys | undefined

setMediaKeys(keys)

TypeScript
setMediaKeys(keys: MediaKeys): Promise<void>

outputProtectionState()

TypeScript
outputProtectionState(): 'unrestricted' | 'restricted' | 'unsupported'

Loader backpressure

pauseLoader()

TypeScript
pauseLoader(): void

Signal the backend to pause segment fetching (used by LiveTranscodingPlugin to drain the buffer before refilling).

resumeLoader()

TypeScript
resumeLoader(): void

loaderState()

TypeScript
loaderState(): 'running' | 'paused'

Crossfade

supportsCrossfade()

TypeScript
supportsCrossfade(): boolean

Whether this backend supports parallel playback for crossfade. Both built-in backends return true. Custom backends that cannot allocate a second handle should return false.

loadSecondary(url)

TypeScript
loadSecondary(url: string): Promise<void>

Allocate the secondary playback handle and load url into it without affecting primary playback.

primeSecondary(seekMs?)

TypeScript
primeSecondary(seekMs?: number): Promise<void>

Pre-roll the secondary to position seekMs (default 0). Waits for canplay before resolving.

crossfade(durationMs)

TypeScript
crossfade(durationMs: number): Promise<void>

Ramp primary gain → 0 and secondary gain → current volume over durationMs. At completion, secondary becomes primary and the old primary is disposed.

disposeSecondary()

TypeScript
disposeSecondary(): void

Tear down the secondary handle. Idempotent.

secondaryGain()

TypeScript
secondaryGain(): number
secondaryGain(value: number): void

Read or write the secondary’s gain (0–1). Returns 0 when no secondary is allocated.

Events

on(event, fn)

TypeScript
on<E extends BackendEvent>(event: E, fn: (data?: BackendEventPayload[E]) => void): void
off<E extends BackendEvent>(event: E, fn: (data?: BackendEventPayload[E]) => void): void

Backend events are forwarded to the player’s event bus by the player’s wiring layer. Subscribe to player-level events (player.on(...)) rather than backend-level events directly.

BackendEvent values: 'loadstart' | 'loadedmetadata' | 'canplay' | 'play' | 'playing' | 'pause' | 'ended' | 'timeupdate' | 'waiting' | 'stalled' | 'ratechange' | 'encrypted' | 'error' | 'backend:loading' | 'backend:loaded'

backend:loading payload: { url: string; kind: AudioBackendKind }. backend:loaded payload: { url: string; kind: AudioBackendKind; duration: number }. All DOM-bridge events carry the original Event object.

See also