MediaSessionActionDetails

The Media Session API'MediaSessionActionDetails dictionary is the type used by the sole input parameter into the callback which is executed when a media session action occurs. It specifies the type of action which needs to be performed as well as the data needed to perform the action.

Properties

action
A string from the MediaSessionAction enumerated type, indicating which type of action needs to be performed. See Media action types below for possible values.
fastSeek Optional
An seekto action may optionally include this property, which is a Boolean value indicating whether or not to perform a "fast" seek. A "fast" seek is a seek being performed in a rapid sequence, such as when fast-forwarding or reversing through the media, rapidly skipping through it. This property can be used to indicate that you should use the shortest possible method to seek the media. fastSeek is not included on the final action in the seek sequence in this situation.
seekOffset Optional
If the action is either seekforward or seekbackward and this property is present, it is a floating point value which indicates the number of seconds to move the play position forward or backward. If this property isn't present, those actions should choose a reasonable default distance to skip forward or backward (such as 7 or 10 seconds).
seekTime Optional
If the action is seekto, this property must be present and must be a floating-point value indicating the absolute time within the media to move the playback position to, where 0 indicates the beginning of the media. This property is not present for other action types.

Media action types

Each of the actions is a common media session control request. You should implement each of these to perform the requested action. The actions are specified using one of the following values from the MediaSessionAction enumerated type:

nexttrack
Advance playback to the next track.
pause
Pause playback of the media.
play
Begin (or resume) playback of the media.
previoustrack
Move back to the previous track.
seekbackward
Seek backward through the media from the current position.
seekforward
Seek forward from the current position through the media.
seekto
Movethe playback position to the specified time within the media.
skipad
Skip 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
Halt playback entirely.

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', 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);
});

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.

Specifications

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

Browser compatibility

No compatibility data found. Please contribute data for "api.MediaSessionActionDetails" (depth: 1) to the MDN compatibility data repository.