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
propertyseekOffset
specifies the amount of time to seek backward. seekforward
- Seeks forward from the current position through the media. The
MediaSessionActionDetails
propertyseekOffset
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
propertyseekTime
. If you intend to perform multipleseekto
operations in rapid succession, you can also specify theMediaSessionActionDetails
propertyfastSeek
property with a value oftrue
. 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 StandardThe definition of 'Media Session action types' in that specification. | Draft | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Media Session action types |
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
nexttrack
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
pause
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
play
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
previoustrack
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
seekbackward
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 76 Full support 76 Disabled' From version 76: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
seekforward
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 76 Full support 76 Disabled' From version 76: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
seekto
|
Chrome
Full support 77 |
Edge
Full support ≤79 |
Firefox Full support 80 Full support 80 Disabled' From version 80: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 77 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
skipad
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 80 Full support 80 Disabled' From version 80: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
stop
|
Chrome
Full support 73 |
Edge
Full support ≤79 |
Firefox Full support 71 Full support 71 Disabled' From version 71: this feature is behind the |
IE
? |
Opera
No support No |
Safari
? |
WebView Android
No support No |
Chrome Android
Full support 57 |
Firefox Android
No support No |
Opera Android
No support No |
Safari 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.
Media Session action types by Mozilla Contributors is licensed under CC-BY-SA 2.5.