navigator.mediaSession returns a MediaSession object so your site can show “now playing” info and respond to OS / keyboard media keys. Learn MediaMetadata, playbackState, setActionHandler, five examples, and try-it labs.
Read-only property
MediaSession
Widely available
MediaMetadata
playbackState
setActionHandler
When you play a podcast or song in the browser, the phone lock screen and laptop media keys should show the title and let users pause without opening the tab.
navigator.mediaSession is how a web app shares that information. You set metadata (title, artist, artwork), declare playbackState ("playing" or "paused", and register action handlers so hardware play/pause buttons control your player.
Media Session does not replace your <audio> / <video> element — it connects your existing player to the device’s standard media controls.
mediaSession PropertyThink of it as a bridge between your web player and the operating system’s “now playing” panel.
MediaSession object for the current document.MediaMetadata instance (title, artist, album, artwork)."none", "paused", or "playing".setPositionState() for duration / position progress (where supported).General form of the property:
navigator.mediaSessionMediaSession object used to share playback metadata and handle media control actions.// MDN-style metadata update:
if ("mediaSession" in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: "Podcast Episode Title",
artist: "Podcast Host",
album: "Podcast Name",
artwork: [{ src: "podcast.jpg" }]
});
}
navigator.mediaSession.playbackState = "playing";| Goal | Code |
|---|---|
| Get the API object | navigator.mediaSession |
| Feature detect | "mediaSession" in navigator |
| Set now-playing info | navigator.mediaSession.metadata = new MediaMetadata({…}) |
| Declare play/pause | navigator.mediaSession.playbackState = "playing" |
| Handle media keys | navigator.mediaSession.setActionHandler("play", fn) |
| Status (MDN) | Baseline Widely available |
Four facts to remember about navigator.mediaSession.
MediaSessionAPI entry
widelySince ~Sep 2021
metadataTitle · art
actionssetActionHandler
mediaSession vs <audio> / <video>mediaSession | Media element | |
|---|---|---|
| Job | OS / lock-screen metadata & media keys | Actual decode and playback |
| Plays sound? | No — coordinates with your player | Yes |
| User sees | Notification / lock screen / keyboard UI | Your page UI |
| Combine? | Yes — play with the element; mirror state into mediaSession | |
Examples follow MDN Media Session patterns. Prefer Try It Yourself. Lock-screen artwork appears when real media is playing in a supporting browser.
Detect the API and set podcast-style metadata (MDN sample).
Check whether navigator.mediaSession exists before using it.
const supported = "mediaSession" in navigator;
console.log(supported
? "Media Session API available"
: "Media Session API missing");MDN’s own sample starts with this check so older browsers fail gracefully.
MediaMetadata (MDN)Share title, artist, album, and artwork with the browser / OS.
if ("mediaSession" in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: "Podcast Episode Title",
artist: "Podcast Host",
album: "Podcast Name",
artwork: [{ src: "podcast.jpg" }]
});
console.log("title: " + navigator.mediaSession.metadata.title);
console.log("artist: " + navigator.mediaSession.metadata.artist);
} else {
console.log("Media Session API missing");
}Artwork entries can include sizes and type. Provide a few image sizes for crisp lock-screen art.
Playback state, media-key handlers, and a reusable setup helper.
playbackStateTell the OS whether media is currently playing or paused.
if ("mediaSession" in navigator) {
navigator.mediaSession.playbackState = "playing";
console.log("state: " + navigator.mediaSession.playbackState);
navigator.mediaSession.playbackState = "paused";
console.log("state: " + navigator.mediaSession.playbackState);
} else {
console.log("Media Session API missing");
}Keep playbackState in sync with your audio/video element’s play and pause events.
setActionHandler for Play / PauseRespond when the user presses keyboard or lock-screen media buttons.
if ("mediaSession" in navigator) {
const log = [];
navigator.mediaSession.setActionHandler("play", function () {
log.push("play");
navigator.mediaSession.playbackState = "playing";
// audio.play();
});
navigator.mediaSession.setActionHandler("pause", function () {
log.push("pause");
navigator.mediaSession.playbackState = "paused";
// audio.pause();
});
console.log("handlers registered: play, pause");
console.log("Press media keys while a track is active to fire them");
} else {
console.log("Media Session API missing");
}Pass null as the handler to clear an action. Common actions include previoustrack, nexttrack, and seek actions.
Feature-detect, set metadata, playback state, and basic handlers in one place.
function setupMediaSession(info) {
if (!("mediaSession" in navigator)) {
return { ok: false, reason: "unsupported" };
}
navigator.mediaSession.metadata = new MediaMetadata({
title: info.title,
artist: info.artist,
album: info.album || "",
artwork: info.artwork || []
});
navigator.mediaSession.playbackState = info.playing ? "playing" : "paused";
navigator.mediaSession.setActionHandler("play", info.onPlay || null);
navigator.mediaSession.setActionHandler("pause", info.onPause || null);
return {
ok: true,
title: navigator.mediaSession.metadata.title,
playbackState: navigator.mediaSession.playbackState
};
}
console.log(JSON.stringify(setupMediaSession({
title: "Morning Mix",
artist: "CodeToFun Radio",
album: "Demo",
playing: true,
onPlay: function () {},
onPause: function () {}
})));Call the helper whenever the track changes so lock-screen info stays accurate.
navigator.mediaSession WorksAn audio/video element (or Web Audio) starts playback.
Set metadata, playbackState, and action handlers.
Lock screen / notification / keyboard controls update.
Your handlers pause, seek, or skip tracks.
navigator.mediaSession (MDN, since about September 2021).navigator.mediaSession is Baseline Widely available across modern browsers (MDN: since about September 2021). Always feature-detect, and verify lock-screen / media-key behavior on your target devices.
Share now-playing metadata and handle OS media controls from your web player.
Bottom line: Detect mediaSession, set MediaMetadata + playbackState, register action handlers, and keep them synced with your player.
navigator.mediaSession connects your web media to the device’s standard controls. Set MediaMetadata, keep playbackState accurate, and use setActionHandler so play/pause and track skips work from the lock screen and keyboard.
Continue with mimeTypes, mediaDevices, or the JavaScript hub.
"mediaSession" in navigatorplaybackState with play/pause eventsmediaSessionBaseline Media Session entry — metadata, playback state, and media-key handlers.
MediaSession
EntryMediaMetadata
Now playingplaybackState
HintsetActionHandler
ControlsBaseline
WideMDN’s podcast example is intentionally tiny: feature-detect, then assign new MediaMetadata({ title, artist, album, artwork }). That alone is enough for many lock screens to show your episode art.
Learn the MimeTypeArray and modern hard-coded PDF entries.
8 people found this page helpful