Media Session action types

To support an action on a media session, such as seeking, pausing, or changing tracks, you need to call the MediaSession interface's setActionHandler() method to establish a handler for that action. The specific type of media session action to be handled on a MediaSession is identified using a string from the MediaSessionAction enumerated type.

Syntax

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:

nexttrack
Advances playback to the next track.
pause
Pauses playback of the media.
play
Begins (or resumes) playback of the media.
previoustrack
Moves back to the previous track.
seekbackward
Seeks backward through the media from the current position. The MediaSessionActionDetails property seekOffset specifies the amount of time to seek backward.
seekforward
Seeks forward from the current position through the media. The MediaSessionActionDetails property seekOffset specifies the amount of time to seek forward.
seekto
Moves the playback position to the specified time within the media. The time to which to seek is specified in the MediaSessionActionDetails property seekTime. If you intend to perform multiple seekto operations in rapid succession, you can also specify the MediaSessionActionDetails property fastSeek property with a value of true. This lets the browser know it can take steps to optimize repeated operations, and is likely to result in improved performance.
skipad
Skips past the currently playing advertisement or commercial. This action may or may not be available, depending on the platform and user agent, or may be disabled due to subscription level or other circumstances.
stop
Halts playback entirely.

Description

A media session action may be generated by any media session action source; these sources include anything from UI widgets within the browser itself to media control keys on the user's keyboard to buttons on the user's headset or earbuds.

Examples

Adding action handlers

This example implements seek forward and backward actions for an audio player by setting up the seekforward and seekbackward action handlers.

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

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

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

In this case, both the seekforward and seekbackward handlers are using a fixed distance, ignoring the time specified by the MediaSessionActionDetails passed into the handler.

Supporting multiple actions in one handler function

You can also, if you prefer, use a single function to handle multiple action types, by checking the value of the MediaSessionActionDetails object's action property:

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;
  }
}

Here, the handleSeek() function handles both seekbackward and seekforward actions.

Using data provided by MediaSessionActionDetails

In this example, instead of seeking a specified distance, the seekforward and seekbackward handlers use the time specified in the MediaSessionActionDetails object's seekOffset property.

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

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

Specifications

Specification Status Comment
Media Session Standard
The definition of 'Media Session action types' in that specification.
Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Media Session action types
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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
nexttrackChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
pauseChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
playChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
previoustrackChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
seekbackwardChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
seekforwardChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
seektoChrome Full support 77Edge Full support ≤79Firefox Full support 80
Disabled
Full support 80
Disabled
Disabled From version 80: 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 77Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
skipadChrome Full support 73Edge Full support ≤79Firefox Full support 80
Disabled
Full support 80
Disabled
Disabled From version 80: 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0
stopChrome 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 ? Opera No support NoSafari ? WebView Android No support NoChrome Android Full support 57Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android Full support 7.0

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.
User must explicitly enable this feature.
User must explicitly enable this feature.