Skip to content

API in Capabilities

Media Session API

Published Updated

navigator.mediaSession describes playing media to the operating system and receives playback commands from its controls. You can supply a title and artist along with the album and artwork. Playback commands include play and pause as well as seeking and track changes. They can come from lock screens or headset buttons, from keyboard media keys, or from the browser’s media hub. Without it those controls still toggle the <audio> or <video> element, and the browser may fall back to the document title and the largest icon it can find. The page supplies no track name, artist, or artwork, and no skip or seek handlers to answer those buttons.

MediaSession and setActionHandler() are available from Chrome 73 on desktop and Chrome 57 on Android, Firefox 82, and Safari 15 on macOS and iOS; MediaMetadata is older (Chrome 57, Safari 14). Firefox for Android exposes the API but shows no media-control UI, and Android WebView has no implementation (BCD api.MediaSession). Individual actions arrive later than the interface: seekto in Chrome 78, stop in Chrome 77, togglemicrophone, togglecamera, and hangup in Chrome 93 (the two toggles also in Safari 18.4), previousslide and nextslide in Chrome 111, enterpictureinpicture in Chrome 120, and skipad in Chrome 128.

navigator.mediaSession.metadata = new MediaMetadata(init)
navigator.mediaSession.playbackState = "none" | "paused" | "playing"
navigator.mediaSession.setActionHandler(action, handler)
navigator.mediaSession.setActionHandler(action, null)
navigator.mediaSession.setPositionState()
navigator.mediaSession.setPositionState(state)
navigator.mediaSession.setMicrophoneActive(active)
navigator.mediaSession.setCameraActive(active)
navigator.mediaSession.setScreenshareActive(active)

metadata is null until the page assigns a MediaMetadata. setActionHandler() and setPositionState() return undefined; passing null as the handler removes the action and its button from the OS controls, and calling setPositionState() with no argument clears the position so the OS stops drawing a progress bar. The three capture-state setters return Promise<undefined> and only matter for conferencing pages that want the OS “mute” button to mirror their own state. The interface is [Exposed=Window] and does not require a secure context.

setActionHandler(action, handler) takes a MediaSessionAction enum value and a MediaSessionActionHandler callback that receives one MediaSessionActionDetails argument. The enum has seventeen members: play, pause, seekbackward, seekforward, previoustrack, nexttrack, skipad, stop, seekto, togglemicrophone, togglecamera, togglescreenshare, hangup, previousslide, nextslide, enterpictureinpicture, and voiceactivity.

MediaSessionActionDetails member Type Present when Description
action MediaSessionAction every call The action being delivered; required.
seekOffset double seekbackward, seekforward (optional) Seconds to move by; when absent the page picks its own step.
seekTime double seekto (required) Absolute target time in seconds.
fastSeek boolean seekto (optional) true while the user is still scrubbing; the final call in the sequence is false.
isActivating boolean togglemicrophone, togglecamera, togglescreenshare false when the browser is about to pause all inputs of that kind.
enterPictureInPictureReason "other", "useraction", "contentoccluded" enterpictureinpicture (required) Why the browser asked the page to enter picture-in-picture.

new MediaMetadata(init) takes a MediaMetadataInit dictionary; every member is optional.

Member Type Default Description
title DOMString "" Track or episode title.
artist DOMString "" Performer or author.
album DOMString "" Album, show, or playlist name.
artwork sequence<MediaImage> [] Images for the OS to choose from. Each MediaImage has a required src (USVString, resolved against the document base URL), optional sizes (same syntax as <link sizes>, for example "512x512"), and optional type (MIME type).
chapterInfo sequence<ChapterInformationInit> [] Chapter titles, start times, and artwork; Chrome 127 only (BCD api.MediaMetadata.chapterInfo).

setPositionState(state) takes a MediaPositionState dictionary.

Member Type Required Description
duration unrestricted double Yes, unless the dictionary is empty Length in seconds; Infinity for live streams.
position double No (default 0) Last reported playback position in seconds, from 0 to duration.
playbackRate double No (default 1.0) Positive for forward playback, negative for backwards; must not be zero.

The methods in the table below throw TypeError for the conditions listed.

Method Condition
setActionHandler() action is not one of the seventeen enum values (WebIDL enum conversion).
setPositionState() duration is absent from a non-empty dictionary; duration is negative or NaN; position is negative or greater than duration; playbackRate is 0.
new MediaMetadata() An artwork entry’s src fails to parse as a URL.

The capture-state setters (setMicrophoneActive() and setCameraActive(), plus setScreenshareActive()) reject with InvalidStateError when the document is not fully active, and may reject with InvalidStateError when active is true while the document is not visible, or with NotAllowedError when the browser denies the update. playbackState throws nothing: an invalid string is ignored and the last valid value stays in place. Chromium throws one extra TypeError, for skipad when its runtime feature is off (see the callout below).

Check 'mediaSession' in navigator before registering handlers. The fallback is the page’s own transport controls, which keep working in Android WebView and in any browser that lacks the API because the <audio> element itself is unaffected.

Registering metadata and handlers for a podcast player

Section titled “Registering metadata and handlers for a podcast player”

Wrapping each setActionHandler() call in its own try block means an action unknown to the browser (seekto in Chrome 73 to 77, previousslide outside Chrome) is skipped instead of aborting the loop and leaving the remaining buttons unregistered. Setting playbackState from the element’s own events keeps the OS play/pause icon correct when the user pauses inside the page.

const audio = document.querySelector('audio');
function registerMediaSession(episode) {
if (!('mediaSession' in navigator)) {
audio.controls = true; // on-page transport only
return;
}
navigator.mediaSession.metadata = new MediaMetadata({
title: episode.title,
artist: episode.show,
album: `Season ${episode.season}`,
artwork: [
{ src: episode.art512, sizes: '512x512', type: 'image/png' },
{ src: episode.art96, sizes: '96x96', type: 'image/png' },
],
});
const handlers = {
play: () => audio.play(),
pause: () => audio.pause(),
seekbackward: ({ seekOffset }) => { audio.currentTime -= seekOffset ?? 15; },
seekforward: ({ seekOffset }) => { audio.currentTime += seekOffset ?? 30; },
nexttrack: () => loadEpisode(episode.next),
};
for (const [action, handler] of Object.entries(handlers)) {
try {
navigator.mediaSession.setActionHandler(action, handler);
} catch (err) {
console.info(`Media Session action "${action}" unavailable: ${err.message}`);
}
}
audio.addEventListener('play', () => { navigator.mediaSession.playbackState = 'playing'; });
audio.addEventListener('pause', () => { navigator.mediaSession.playbackState = 'paused'; });
}

For a podcast, omit previoustrack to hide the OS button. Registering a handler that does nothing would leave an unusable button visible.

Reporting position so the lock screen shows a scrubber

Section titled “Reporting position so the lock screen shows a scrubber”

The OS extrapolates the position from the last report, so the page only needs to call setPositionState() when playback starts, seeks, or changes rate, not on every timeupdate. The seekto handler honours fastSeek by using fastSeek() for intermediate scrub events and a precise assignment for the final one. The guard against a NaN duration matters before loadedmetadata, because the specification rejects NaN with a TypeError.

function reportPosition() {
if (!('mediaSession' in navigator) || !('setPositionState' in navigator.mediaSession)) return;
if (!Number.isFinite(audio.duration) && audio.duration !== Infinity) return; // metadata not loaded yet
navigator.mediaSession.setPositionState({
duration: audio.duration,
playbackRate: audio.playbackRate,
position: Math.min(audio.currentTime, audio.duration),
});
}
for (const event of ['loadedmetadata', 'play', 'seeked', 'ratechange']) {
audio.addEventListener(event, reportPosition);
}
if ('mediaSession' in navigator) {
try {
navigator.mediaSession.setActionHandler('seekto', ({ seekTime, fastSeek }) => {
if (fastSeek && 'fastSeek' in audio) {
audio.fastSeek(seekTime);
return;
}
audio.currentTime = seekTime;
reportPosition();
});
} catch {
// seekto unsupported: the OS shows no scrubber, on-page seeking still works
}
}

Clamping position to duration avoids the TypeError that an ended event can otherwise trigger when currentTime overshoots by a few milliseconds.

Specifications

SpecificationStatus
Media Session Standard: setActionHandler() methodW3C draft
Media Session Standard: setPositionState() methodW3C draft
Media Session Standard: MediaMetadata constructorW3C draft