MediaController

The playback core of an audio or video element: one state snapshot, per-frame progress, seek, scrub, volume and rate.

Reach for it to build an audio or video player with custom controls. The host never listens to a media event: it reads a MediaState and calls methods. It works on any HTMLMediaElement, so on audio and video alike.

Import

import {
	MediaController,
	createMediaController,
	type MediaState,
	type MediaStatus,
} from '@ecopages/radiant-ui/controllers';
import { formatMediaTime, clampSeek, bufferedEnd } from '@ecopages/radiant-ui/helpers';

Try it

A four second tone, generated in the page as a WAV blob, loops. Drag the range to scrub: the position follows the pointer at once and the media seeks once you pause. The status line is the state the controller reports.

idle

<div data-example="media">
	<audio></audio>
	<button type="button" data-action="play" aria-pressed="false">Play</button>
	<button type="button" data-action="back">Back 1s</button>
	<button type="button" data-action="forward">Forward 1s</button>
	<button type="button" data-action="mute" aria-pressed="false">Mute</button>
	<button type="button" data-action="rate">1x</button>
	<input type="range" aria-label="Position" min="0" max="0" step="0.01" value="0" disabled />
	<p data-status>idle</p>
</div>
import { MediaController, type MediaState } from '@ecopages/radiant-ui/controllers';
import { formatMediaTime } from '@ecopages/radiant-ui/helpers';

const RATES = [1, 1.5, 2];

export function mount(root: HTMLElement): () => void {
	const audio = root.querySelector('audio')!;
	const play = root.querySelector<HTMLButtonElement>('[data-action="play"]')!;
	const back = root.querySelector<HTMLButtonElement>('[data-action="back"]')!;
	const forward = root.querySelector<HTMLButtonElement>('[data-action="forward"]')!;
	const mute = root.querySelector<HTMLButtonElement>('[data-action="mute"]')!;
	const rate = root.querySelector<HTMLButtonElement>('[data-action="rate"]')!;
	const seek = root.querySelector<HTMLInputElement>('input[type="range"]')!;
	const status = root.querySelector('[data-status]')!;
	const url = toneUrl(4);

	const renderProgress = (state: MediaState) => {
		const hours = state.duration >= 3600;
		const position = formatMediaTime(state.position, { hours });
		const duration = formatMediaTime(state.duration, { hours });
		seek.max = String(Number.isFinite(state.duration) ? state.duration : 0);
		seek.value = String(state.position);
		seek.setAttribute('aria-valuetext', `${position} of ${duration}`);
		status.textContent = state.error
			? `error: ${state.error.message || 'the media failed'}`
			: `${state.status}, ${position} of ${duration}, buffered to ${formatMediaTime(state.buffered)}`;
	};

	const renderState = (state: MediaState) => {
		play.setAttribute('aria-pressed', String(!audio.paused));
		mute.setAttribute('aria-pressed', String(state.muted));
		rate.textContent = `${state.rate}x`;
		seek.disabled = !state.seekable;
		back.disabled = !state.seekable;
		forward.disabled = !state.seekable;
		renderProgress(state);
	};

	const media = new MediaController({
		getMedia: () => audio,
		onState: renderState,
		onProgress: renderProgress,
	});
	media.attach();
	media.setLoop(true);
	void media.load(url);

	play.addEventListener('click', () => void media.toggle());
	back.addEventListener('click', () => media.skip(-1));
	forward.addEventListener('click', () => media.skip(1));
	mute.addEventListener('click', () => media.toggleMuted());
	rate.addEventListener('click', () =>
		media.setRate(RATES[(RATES.indexOf(media.getState().rate) + 1) % RATES.length]!),
	);
	seek.addEventListener('input', () => media.scrub(Number(seek.value)));

	return () => {
		media.destroy();
		URL.revokeObjectURL(url);
	};
}

toneUrl(seconds) returns an object URL of a 440 Hz WAV built in memory; it is in the page script. mount runs once for each example element on the page, and the function it returns undoes it; see how the examples run.

Config

OptionDescription
getMediaThe HTMLMediaElement, resolved on every attach(). Returning null leaves the controller inert until the next attach().
resolveSource(url) => Promise<string>: turns the URL given to load() into the one the element gets. See Loading through a Blob.
releaseSourceCalled with a URL resolveSource returned once the element no longer uses it, so you can revoke an object URL. Never called for the URL in use, and each URL once. See Destroy.
onStateCalled with the MediaState when anything other than position, buffered, bufferedRanges or seekableRange changes, and once on attach().
onProgressCalled with the latest state once per animation frame while playing; on timeupdate while playing in a hidden tab; on timeupdate, seeked and progress otherwise; on visibilitychange; on attach(); and when a scrub starts and when its seek is applied.
onErrorCalled once for each error the state enters: a MediaError, a failed resolveSource, a play() that failed or a last source child that could not load.
seekDebounceQuiet time in milliseconds before scrub seeks. Default 120.
pauseOnDestroyPause when the controller is destroyed for good. Default true.
clearSourceOnDestroyRemove src and reload the element when the controller is destroyed for good. Default false.

State

getState() and every callback return a MediaState, a fresh object read from the element's own properties (readyState, networkState, paused, ended, error, played, buffered, seekable) on every media event. The controller holds only what the element cannot answer: a pending scrub target, a resolveSource in flight, blocked, whether playback was ever started, and a failure that has no MediaError. They are cleared when the element is emptied or loads again, but they are flags: if you change the element behind the controller's back, they can lag until the next media event.

FieldDescription
statusidle (no source), loading, ready (loaded, not started), playing, paused, ended or error.
positionSeconds. While a scrub is pending it is the scrub target, so a range input does not jump back. After load(url, { startAt }) it is startAt until metadata arrives.
durationSeconds. NaN before metadata, Infinity for a live stream.
seekableMetadata is known, no resolveSource is pending or rejected and, for a live stream, the element reports a seekable window. seek and scrub do nothing while false.
liveThe duration is Infinity.
buffered, bufferedRangesEnd, in seconds, of the buffered range that contains position (0 when none does), and every range as [start, end] for a segmented bar.
seekableRangeThe window media.seekable reports, [start, end], or null. For a live stream with a rewind window, seeks are clamped to it.
currentSrcThe source the element actually plays; '' when it has none.
volume, muted, rate, loopThe element's volume, muted, playbackRate and loop. loop has no event, so it is read on every refresh.
waitingPlaying with readyState below HAVE_FUTURE_DATA: playback started and is waiting for data.
seekingThe element is seeking.
blockedThe last play() was refused by the autoplay policy. The status is paused and error stays null; the next user-initiated play() can succeed.
errorA MediaError from the element, or the Error of a failed resolveSource, play() or last source child (No supported source).

How the status is read: an error wins (a pending resolveSource hides the old error), then a pending resolveSource is loading, an element with networkState empty is idle, ended is ended, an unpaused element is playing (loading while readyState is still 0), a paused element that is still fetching and has no current data is loading, and otherwise it is paused once playback was started and ready before.

A source child that fails is only seen when its error event fires after attach(). Markup that already failed before the controller attached reads as loading; call load(url) to recover.

Methods

MethodDescription
getState()The current MediaState.
load(url, { autoplay, startAt })Sets the source, through resolveSource when given. autoplay calls play() right after the source is set, so it works for preload="none" too. startAt seconds is applied as the element's default playback position, and position reports it from the load() call until metadata arrives, so it never shows 0. A newer load() replaces it, and it cancels a pending scrub. Resolves once the element has the source. Never rejects.
retry()Runs the last load() again with the same URL and options, to recover from an error.
play(), pause(), toggle()play() never rejects: an AbortError (a newer load() or a pause() interrupted it) is quiet, a NotAllowedError sets blocked, anything else is the error state. It does nothing while the status is idle, and after a rejected resolveSource while the error holds, so the track the element still has is not played by mistake: load() or retry() recovers. toggle() pauses an element that is not paused, which includes one that is loading; read a toggle button's pressed state from !audio.paused, not from status === 'playing'.
seek(seconds)Seeks now, clamped to [0, duration], or to the seekable window of a live stream. With an unknown duration it clamps at 0 only. Ignored while not seekable and for a value that is not finite. Cancels a pending scrub.
scrub(seconds)A debounced seek. position is the target at once; currentTime is set after seekDebounce ms without another scrub, once for a whole burst. load(), seek(), destroy() and a source change cancel it.
skip(delta)seek relative to the pending scrub target, or to the position when none is pending.
goLive()Seeks to the end of the seekable window of a live stream. Does nothing otherwise.
setVolume(0..1), setMuted(muted), toggleMuted(), setRate(rate), setLoop(loop)Set the element's property. setVolume clamps to 0..1 and setRate to 0.0625..16; both ignore a value that is not finite. The state follows on volumechange and ratechange, so it also follows a change someone else makes.

Events and lifecycle

Media events do not bubble, so the controller listens on the element itself, with one AbortController, to loadstart, loadedmetadata, loadeddata, canplay, canplaythrough, play, playing, pause, ended, waiting, stalled, suspend, seeking, seeked, timeupdate, durationchange, progress, volumechange, ratechange, emptied, abort and error, and in the capture phase to the error of source children. After each it reads the element again. Nothing counts events, so the order does not matter. In Chromium, setting src while playing fires abort, emptied, loadstart and canplay with no pause and no play, and paused turns true; load(url, { autoplay }) then adds play and playing.

  • attach() adds the listeners and reports the current state at once, because the media may already have metadata or be playing. It is repeat-safe: attaching again re-resolves getMedia and does nothing for the same element, so it is also how a late-rendered element is picked up (the visualizer has a separate refresh() because it also re-reads getEnabled). Attaching to a different element, or to null, first ends the session on the old one as destroy() does: paused and released in a microtask unless another controller still uses it. A controller attached after destroy() syncs again.
  • While the status is playing one frame loop runs, never two. It stops on pause, ended, emptied, an error, a status that is no longer playing and destroy(). Animation frames stop in a background tab, so while document.hidden the loop is replaced by timeupdate and onProgress keeps running for a Media Session or lyric sync.
  • A callback may call a method. After onState and after onError the controller reads the state again, so onProgress never receives a state older than the one the callback caused.
  • The constructor makes no DOM, window or media access, so building one on the server is safe. Methods do nothing before attach().
  • A media error event, a last failing source child or a rejected resolveSource puts the state in error and calls onError once. load() or retry() recovers.
  • Several controllers may share one element. They only read it and call its methods.

With a host, createMediaController(host, config) attaches on connect and destroys on disconnect; see bindController.

Destroy

destroy() stops listening, cancels the frame loop, the timers and a pending scrub, and makes a pending load() a no-op, all at once. It does not touch the element synchronously: pausing and releasing wait one microtask. If a controller attached to the same element again by then, which is what moving the element in the DOM does (cleanup, then connect), nothing happens and playback and the source carry on. The same holds while another MediaController is attached to the element: only the last one destroyed pauses it. Otherwise it pauses unless pauseOnDestroy is false, and with clearSourceOnDestroy removes src, reloads the element and calls releaseSource once with the resolved source. The resolved source is tracked per element, so when several controllers share it the last one destroyed releases it once, whichever of them loaded it. attach() to another element ends the session on the old one with the same rules. Both methods are idempotent.

Releasing a Blob URL revokes it, so the element cannot play that source again. With clearSourceOnDestroy, src is cleared and the URL released on the final destroy; without it the element keeps src and the URL stays alive until the next load() replaces it, so a reused element never plays a revoked URL. An element that was ever visualized by an AudioVisualizerController must keep same-origin or CORS sources.

Loading through a Blob

A media element can only seek in a file whose server answers range requests. Many dev and preview servers do not, so on those the position snaps to 0 whenever you seek. Loading through a Blob fixes it for short media, because the whole file is then in memory. Pass a resolveSource for that and a releaseSource to revoke the object URL; the controller calls it when the URL is no longer used, including on the final destroy():

createMediaController(this, {
	getMedia: () => this.querySelector('audio'),
	resolveSource: async (url) => URL.createObjectURL(await (await fetch(url)).blob()),
	releaseSource: (url) => URL.revokeObjectURL(url),
});

Long media should not be loaded this way: serve it with range support instead. The controller does not hard-code the workaround. It only guards the hook: a newer load() or a destroy() makes an older pending resolution a no-op and the URL it returned goes to releaseSource, and a URL the element is using is never released, so a resolveSource that caches and returns the same URL again is safe. While a source resolves the element is paused, the status is loading, and seek and scrub do nothing.

Accessibility

The controller sets no ARIA and handles no keys. The host provides:

  • A name for every control. A toggle such as play or mute keeps one label and sets aria-pressed from the state, as the example does (!audio.paused, because toggle() pauses anything that is not paused). If you want the label to change (Play, Pause) leave aria-pressed off: a button must not do both, or a screen reader announces "Pause, toggle button, pressed".
  • aria-valuetext on the position control with the position and the duration, for example 1:15 of 4:00 from formatMediaTime. Do not use the bare position.
  • Keyboard shortcuts (space, arrows, m), fullscreen, picture-in-picture and captions. The controller does none of these; call the element's own APIs.
  • Live-region announcements. Do not make the per-frame status line live. Announce changes of status, blocked and error from onState instead.
  • A visible way to start playback: when blocked is true the browser refused autoplay, so show the play control and let the user press it.

Protected hooks

None. Change behavior through the config callbacks.