MediaSession.setPositionState()

The MediaSession method setPositionState() is used to update the current document's media playback position and speed for presentation by user's device in any kind of interface that provides details about ongoing media. This can be particularly useful if your code implements a player for type of media not directly supported by the browser.

Call this method on the navigator object's mediaSession object.

Syntax

navigator.mediaSession.setPositionState(stateDict);

Parameters

stateDict Optional
An object conforming to the MediaPositionState dictionary, providing updated information about the playback position and speed of the document's ongoing media. If the object is empty, the existing playback state information is cleared.

Return value

undefined.

Exceptions

TypeError

This error can occur in an array of circumstances:

Example

Below is a function which updates the position state of the current MediaSession track.

function updatePositionState() {
  navigator.mediaSession.setPositionState({
    duration: audioEl.duration,
    playbackRate: audioEl.playbackRate,
    position: audioEl.currentTime
  });
}

We can use this function when updating media session metadata and within callbacks for actions, such as below.

navigator.mediaSession.setActionHandler('seekbackward', details => {

  // our time to skip
  const skipTime = details.seekOffset || 10;

  // set our position
  audioEl.currentTime = Math.max(audioEl.currentTime - skipTime, 0);
  updatePositionState();

});

Specifications

Specification Status Comment
Media Session Standard
The definition of 'MediaSession.setPositionState()' in that specification.
Draft Initial definition.

Browser compatibility

BCD tables only load in the browser