MediaSession.setActionHandler()

The setActionHandler() property of the MediaSession interface sets an event handler for a media session action. These actions let a web app receive notifications when the user engages a device's built-in physical or onscreen media controls, such as play, stop, or seek buttons.

Syntax

navigator.mediaSession.setActionHandler(type, callback)

Parameters

type

A DOMString representing an action type to listen for. It will be one of play, pause, seekbackward, seekforward, seekto, skipad,previoustrack, or nexttrack. Further details on the action types can be found below under Media session actions.

callback

A function to call when the specified action type is invoked. The callback receives no input parameters, and should not return a value.

Return value

undefined.

Description

To remove a previously-established action handler, call setActionHandler() again, specifying null as the callback.

The action handler receives as input a single parameter: an object conforming to the MediaSessionActionDetails dictionary, which provides both the action type (so the same function can handle multiple action types), as well as data needed in order to perform the action.

Media session actions

A media session action's type is specified using a string from the MediaSessionAction enumerated type.

Values

Each of the actions is a common media session control request. Implement support for each of these in order to allow that type of action to be performed. The following strings identify the currently available types of media session action:

let skipTime = 10; // Time to skip in seconds

navigator.mediaSession.setActionHandler('seekforward', evt => {
 // User clicked "Seek Forward" media notification icon.
 audio.currentTime = Math.min(audio.currentTime + skipTime,  
               audio.duration);
});

navigator.mediaSession.setActionHandler('seekbackward', evt => {
 // User clicked "Seek Backward" media notification icon.
 audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

let skipTime = 7;

navigator.mediaSession.setActionHandler("seekforward", handleSeek);
navigator.mediaSession.setActionHandler("seekbackward", handleSeek);

function handleSeek(details) {
  switch(details.action) {
    case "seekforward":
      audio.currentTime = Math.min(audio.currentTime + skipTime,
              audio.duration);
      break;
    case "seekbackward":
      audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
      break;
  }
}

Examples

The following example creates a new media session and assigns action handlers (which don't do anything) to it.

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.setActionHandler('play', function() {});
 navigator.mediaSession.setActionHandler('pause', function() {});
 navigator.mediaSession.setActionHandler('seekbackward', function() {});
 navigator.mediaSession.setActionHandler('seekforward', function() {});
 navigator.mediaSession.setActionHandler('previoustrack', function() {});
 navigator.mediaSession.setActionHandler('nexttrack', function() {});
}

This example uses appropriate action handlers to allow seeking in either direction through the playing media.

let skipTime = 10; // Time to skip in seconds

navigator.mediaSession.setActionHandler('seekbackward', evt => {
 // User clicked "Seek Backward" media notification icon.
 audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

navigator.mediaSession.setActionHandler('seekforward', evt => {
 // User clicked "Seek Forward" media notification icon.
 audio.currentTime = Math.min(audio.currentTime + skipTime,
               audio.duration);
});

To remove a media action handler, assign it to null.

navigator.mediaSession.setActionHandler('nexttrack', null);

Specifications

Browser compatibility