Media Session API

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Media Session API provides a way to customize media notifications. It does this by providing metadata for display by the user agent of the media your web app is playing, and allows you to create event handlers, to define your own behaviors for a user-agent playback controls. The aim of this is allowing users to know what's playing, and to control it, without opening the specific page that launched it.

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 even trigger 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 event handlers. The user agent provides default behaviors, when no page-defined behavior is available.

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.

Examples

The following example shows feature detection for the Media Session API. It then instantiates a metadata object for the session, and adds event 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('seekbackward', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('seekforward', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('previoustrack', function() { /* Code excerpted. */ });
  navigator.mediaSession.setActionHandler('nexttrack', 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
The definition of 'metadata' in that specification.
Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic support
ExperimentalNon-standard
Chrome No support NoEdge ? Firefox ? IE ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Edge Mobile ? Firefox Android ? Opera Android No support NoSafari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.

Document Tags and Contributors

Contributors to this page: arib, HonzaTuron, jpmedley, david_ross
Last updated by: arib,