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
| Option | Description |
|---|---|
getMedia | The 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. |
releaseSource | Called 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. |
onState | Called with the MediaState when anything other than position, buffered, bufferedRanges or seekableRange changes, and once on attach(). |
onProgress | Called 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. |
onError | Called 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. |
seekDebounce | Quiet time in milliseconds before scrub seeks. Default 120. |
pauseOnDestroy | Pause when the controller is destroyed for good. Default true. |
clearSourceOnDestroy | Remove 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.
| Field | Description |
|---|---|
status | idle (no source), loading, ready (loaded, not started), playing, paused, ended or error. |
position | Seconds. 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. |
duration | Seconds. NaN before metadata, Infinity for a live stream. |
seekable | Metadata 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. |
live | The duration is Infinity. |
buffered, bufferedRanges | End, in seconds, of the buffered range that contains position (0 when none does), and every range as [start, end] for a segmented bar. |
seekableRange | The window media.seekable reports, [start, end], or null. For a live stream with a rewind window, seeks are clamped to it. |
currentSrc | The source the element actually plays; '' when it has none. |
volume, muted, rate, loop | The element's volume, muted, playbackRate and loop. loop has no event, so it is read on every refresh. |
waiting | Playing with readyState below HAVE_FUTURE_DATA: playback started and is waiting for data. |
seeking | The element is seeking. |
blocked | The last play() was refused by the autoplay policy. The status is paused and error stays null; the next user-initiated play() can succeed. |
error | A 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
| Method | Description |
|---|---|
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-resolvesgetMediaand does nothing for the same element, so it is also how a late-rendered element is picked up (the visualizer has a separaterefresh()because it also re-readsgetEnabled). Attaching to a different element, or tonull, first ends the session on the old one asdestroy()does: paused and released in a microtask unless another controller still uses it. A controller attached afterdestroy()syncs again.- While the status is
playingone frame loop runs, never two. It stops on pause,ended,emptied, an error, a status that is no longerplayinganddestroy(). Animation frames stop in a background tab, so whiledocument.hiddenthe loop is replaced bytimeupdateandonProgresskeeps running for a Media Session or lyric sync. - A callback may call a method. After
onStateand afteronErrorthe controller reads the state again, soonProgressnever receives a state older than the one the callback caused. - The constructor makes no DOM,
windowor media access, so building one on the server is safe. Methods do nothing beforeattach(). - A media
errorevent, a last failingsourcechild or a rejectedresolveSourceputs the state inerrorand callsonErroronce.load()orretry()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-pressedfrom the state, as the example does (!audio.paused, becausetoggle()pauses anything that is not paused). If you want the label to change (Play, Pause) leavearia-pressedoff: a button must not do both, or a screen reader announces "Pause, toggle button, pressed". aria-valuetexton the position control with the position and the duration, for example1:15 of 4:00fromformatMediaTime. 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,blockedanderrorfromonStateinstead. - A visible way to start playback: when
blockedistruethe browser refused autoplay, so show the play control and let the user press it.
Protected hooks
None. Change behavior through the config callbacks.