Media Session API

The Media Session API provides a way to customize media notifications. It does this by providing metadata for display by the user agent for the media your web app is playing.

It also provides action handlers that the browser can use to access platform media keys such as hardware keys found on keyboards, headsets, remote controls, and software keys found in notification areas and on lock screens of mobile devices. So you can seamlessly control web-provided media via your device, even when not looking at the web page.

The aim is to allow users to know what's playing and to control it, without needing to open the specific page that launched it. To be able to support the Media Session API, a browser first needs a mechanism by which to access and be controlled by the OS-level media controls (such as Firefox's MediaControl).

Media Session concepts and usage

The MediaMetadata interface lets a web site provide rich metadata to the platform UI for media that is playing. This metadata includes the title, artist (creator) name, album (collection), and artwork. The platform can show this metadata in media centers, notifications, device lockscreens, etc.

The MediaSession interface lets users control playback of media through user-agent defined interface elements. Interaction with these elements triggers action handlers in the web page, playing the media. Since multiple pages may be simultaneously using this API, the user agent is responsible for calling the correct page's action handlers. The user agent provides default behaviors, when no page-defined behavior is available.

Accessing the Media Session API

The primary interface for the Media Session API is the MediaSession interface. Rather than creating your own MediaSession instance, you access the API using the navigator.mediaSession property. For example, to set the current state of the media session to playing:

navigator.mediaSession.playbackState = "playing";

Interfaces

MediaMetadata
Allows a web page to provide rich media metadata for display in a platform UI.
MediaSession
Allows a web page to provide custom behaviors for standard media playback interactions.

Dictionaries

MediaImage
MediaImage object contains information describing an image associated with the media. This might be a CD or DVD cover, a movie poster, a poster frame, or the like.
MediaPositionState
Used to contain information about the current playback position, playback speed, and overall media duration when calling the MediaSession method setPositionState() to establish the media's length, playback position, and playback speed.
MediaSessionActionDetails
Provides information needed in order to perform the action that has been requested, including the type of action to perform and any other information needed, such as seek distances or times.

Examples

The following example shows feature detection for the Media Session API. It then instantiates a metadata object for the session, and adds action handlers for the user control actions:

if ('mediaSession' in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: 'Unforgettable',
    artist: 'Nat King Cole',
    album: 'The Ultimate Collection (Remastered)',
    artwork: [
      { src: 'https://dummyimage.com/96x96',   sizes: '96x96',   type: 'image/png' },
      { src: 'https://dummyimage.com/128x128', sizes: '128x128', type: 'image/png' },
      { src: 'https://dummyimage.com/192x192', sizes: '192x192', type: 'image/png' },
      { src: 'https://dummyimage.com/256x256', sizes: '256x256', type: 'image/png' },
      { src: 'https://dummyimage.com/384x384', sizes: '384x384', type: 'image/png' },
      { src: 'https://dummyimage.com/512x512', sizes: '512x512', type: 'image/png' },
    ]
  });

  navigator.mediaSession.setActionHandler('play', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('pause', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('stop', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('seekbackward', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('seekforward', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('seekto', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('previoustrack', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('nexttrack', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('skipad', function() { /* Code excerpted. */ });
}

Some user agents disable autoplay for media elements on mobile devices and require a user gesture to start media. The following example adds a pointerup event to an on-page play button, which is then used to kick off the media session code:

playButton.addEventListener('pointerup', function(event) {
  var audio = document.querySelector('audio');

  // User interacted with the page. Let's play audio...
  audio.play()
  .then(_ => { /* Set up media session controls, as shown above. */ })
  .catch(error => { console.log(error) });
});

Specifications

Specification Status Comment
Media Session Standard Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
MediaSession
Experimental
Chrome Full support 73Edge Full support ≤79Firefox Full support 71
Disabled
Full support 71
Disabled
Disabled From version 71: this feature is behind the dom.media.mediasession.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 7.0
metadata
Experimental
Chrome Full support 73Edge Full support ≤79Firefox Full support 71
Disabled
Full support 71
Disabled
Disabled From version 71: this feature is behind the dom.media.mediasession.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 7.0
playbackState
Experimental
Chrome Full support 73Edge Full support ≤79Firefox Full support 76
Disabled
Full support 76
Disabled
Disabled From version 76: this feature is behind the dom.media.mediasession.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 7.0
setActionHandler()
Experimental
Chrome Full support 73Edge Full support ≤79Firefox Full support 71
Disabled
Full support 71
Disabled
Disabled From version 71: this feature is behind the dom.media.mediasession.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 7.0
setPositionState()
Experimental
Chrome Full support 73Edge Full support ≤79Firefox Full support 76
Disabled
Full support 76
Disabled
Disabled From version 76: this feature is behind the dom.media.mediasession.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support YesSafari No support NoWebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 7.0

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
User must explicitly enable this feature.
User must explicitly enable this feature.