JavaScript Navigator mediaSession Property

Beginner
5 min read
Updated: Nov 2026
5 examples
Property
Decorative image with the word MEDIASESSION

Definition

navigator.mediaSession is a read-only Navigator property that returns a MediaSession object (MDN). Share now-playing metadata with the OS and handle play / pause / seek / track controls from keyboards, lock screens, and system media UIs.

Read the notes below before you rely on this property. Prefer feature detection when support is limited.

Syntax

Use navigator.mediaSession. Start with this line.

JavaScript
navigator.mediaSession
CallWhat it does
navigator.mediaSessionPrimary signature.

Built into the browser. Read navigator.mediaSession on Navigator — no import required.

Library declarations
JavaScript
navigator.mediaSession

Parameters

ParameterDescription
setActionHandlerOptional. Respond to media keys / lock-screen buttons

Return Value

Return ValueDescription
*The current value of navigator.mediaSession.

JavaScript Examples

Example 1 — Feature Detection

Check whether navigator.mediaSession is exposed before using it.

JavaScript
const supported = "mediaSession" in navigator;
console.log(
  supported ? "Media Session API available" : "Media Session API missing"
);
Try It Yourself

How It Works

  1. Use in. MDN’s recommended guard before accessing the API.
  2. Branch early. Skip metadata/handlers when unsupported.
  3. Expect modern support. Property is Baseline since ~2021.
  4. Still try/catch actions. Some action names are not universal.

Example 2 — Set MediaMetadata (MDN)

Share podcast title, artist, album, and artwork with the browser/OS.

JavaScript
if (!("mediaSession" in navigator)) {
  console.log("Media Session API missing");
} else {
  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);
  console.log("album: " + navigator.mediaSession.metadata.album);
}
Try It Yourself

How It Works

  1. Guard the API. Skip when mediaSession is missing.
  2. Build MediaMetadata. Title/artist/album/artwork for platform UI.
  3. Assign to metadata. Browser can forward it to the OS.
  4. Read it back. Confirms the session stored your fields.

Example 3 — playbackState

Tell the platform whether media is currently playing or paused.

JavaScript
if (!("mediaSession" in navigator)) {
  console.log("Media Session API missing");
} else {
  navigator.mediaSession.playbackState = "playing";
  console.log("state: " + navigator.mediaSession.playbackState);

  navigator.mediaSession.playbackState = "paused";
  console.log("state: " + navigator.mediaSession.playbackState);
}
Try It Yourself

How It Works

  1. Set playing. Matches an active audio.play() / video play.
  2. Read it back. Valid values are none, paused, playing.
  3. Set paused. Keep OS controls in sync when the user pauses.
  4. Update on real events. Hook play / pause on your media element.

Example 4 — setActionHandler

Register play/pause handlers for keyboard or lock-screen media keys.

JavaScript
if (!("mediaSession" in navigator)) {
  console.log("Media Session API missing");
} else {
  const log = [];

  navigator.mediaSession.setActionHandler("play", () => {
    log.push("play");
    navigator.mediaSession.playbackState = "playing";
    console.log("events: " + log.join(", "));
  });

  navigator.mediaSession.setActionHandler("pause", () => {
    log.push("pause");
    navigator.mediaSession.playbackState = "paused";
    console.log("events: " + log.join(", "));
  });

  console.log("handlers registered: play, pause");
}
Try It Yourself

How It Works

  1. Register by action name. "play" and "pause" are the basics.
  2. Update your player inside the handler. Call audio.play() / pause() in real apps.
  3. Sync playbackState. Keeps the platform indicator correct.
  4. Test with media keys. Handlers fire from OS/keyboard controls, not from assigning them.

Example 5 — Setup Helper

Set metadata, playback state, and play/pause handlers in one small helper.

JavaScript
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: () => {},
      onPause: () => {}
    }),
    null,
    2
  )
);
Try It Yourself

How It Works

  1. Detect first. Return unsupported when the API is missing.
  2. Set metadata + state together. One place to update on track change.
  3. Wire play/pause. Pass null to clear a handler later.
  4. Return a summary. Easy to log or assert in demos.
Compatibility

Browser Support

navigator.mediaSession is Baseline Widely available (MDN). Evergreen browsers have shipped the property since about September 2021; some MediaSession methods still vary.

✓ Baseline · Widely available

Navigator.mediaSession

Supported in modern Chrome, Firefox, Safari, Edge, and Opera. Feature-detect and try/catch individual action handlers.

92% Modern browser support
Google Chrome Media Session · Desktop & Mobile
Full support
Microsoft Edge Media Session · Chromium
Full support
Apple Safari Media Session · modern versions
Full support
Mozilla Firefox Media Session · modern versions
Full support
Opera Media Session · modern versions
Full support
Internet Explorer No Media Session API
Unavailable
navigator.mediaSession Excellent

Bottom line: Safe for modern media apps. Detect the property, set metadata during playback, and register only the actions you implement.

Frequently Asked Questions

A read-only MediaSession object. Your page can share now-playing metadata (title, artist, artwork) and handle OS or keyboard media controls via setActionHandler() (MDN).
No. MDN marks the navigator.mediaSession property Baseline Widely available (since about September 2021). It is not Deprecated, Experimental, or Non-standard. Some MediaSession methods still vary by browser.
An object you assign to navigator.mediaSession.metadata with fields like title, artist, album, and artwork image URLs so lock screens and notification centers can show your track.
It registers callbacks for actions such as play, pause, previoustrack, nexttrack, seekbackward, and seekforward when the user presses hardware or OS media keys.
none, paused, or playing — so the platform UI can show the correct playback indicator.
The property itself is read-only (you get a MediaSession object). You do write that object’s fields, such as metadata and playbackState, and call its methods.

Next: mimeTypes

Learn how navigator.mimeTypes exposes the legacy plugin MIME type list.

mimeTypes tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Navigator mediaDevices Property JavaScript Navigator mimeTypes Property