What is Media Session API?

Mon Mar 27 2023

4 min read

If you've ever been struggling with complex audio players or unintuitive video controls, the Media Session API is the solution you've been looking for.

The Media Session API is an incredible tool that makes controlling media playback on websites easier. Let's explore how this API can help you create seamless media playback experiences on the web.

Media Session API

The Media Session API is a Web API that allows us to control media playback and customize media notifications. This means we can define media metadata, like the title, artist, album, and artwork, and respond to media-related events, like play, pause, next, and previous.

When media playback is detected on a website using the Media Session API, the metadata and playback controls are displayed on the user's device. This makes it very simple for users to control media playback without leaving the website.

Basic Concepts

Let's dive into the key concepts of the Media Session API that are most closely related: the Media Session Interface and Media Metadata.

Media Session

The Media Session Interface is an object that represents the current media session and holds all the metadata and playback controls. This interface allows us to control media playback by providing media-related events, actions, and metadata.

It is mainly responsible for providing access to the current state of the media session, such as whether it's playing or paused, and for firing events when the user interacts with the media controls.

Media Metadata

Media Metadata, on the other hand, is all the information about the media, such as its title, artist, album, and artwork. This metadata is used to populate the media controls on the user's device, making it easier for the user to control media playback without switching tabs or opening a new window.


Let's look at a simple example of how to use the Media Session API to play audio on a website.

Step #1: Create an HTML audio element

First, create an HTML audio element in our HTML file like this:

<audio id="my-audio" src="audio.mp3"></audio>

Step #2: Define media metadata

Then define the media metadata using the MediaMetadata constructor. After that, set the metadata using navigator.mediaSession.setMetadata().

const audio = document.getElementById('my-audio');
// Define media metadata
const metadata = new MediaMetadata({
title: 'Audio File',
artist: 'John Doe',
album: 'Running up the hill',
// Set media metadata

Step #3: Add event listeners

Next, we add event listeners for the play and pause events using navigator.mediaSession.setActionHandler(). When the play event is triggered, we call the play() method on our audio element, and when the pause event is triggered, we call the pause() method.

// Add event listeners
navigator.mediaSession.setActionHandler('play', function() {
navigator.mediaSession.setActionHandler('pause', function() {

Step #4: Handle tracks

Finally, we can add event listeners for the previous and next track events as needed.

navigator.mediaSession.setActionHandler('previoustrack', function() {
// Handle previous track event
navigator.mediaSession.setActionHandler('nexttrack', function() {
// Handle next track event


Most modern web browsers, including Google Chrome, Mozilla Firefox, Microsoft Edge, and Safari, support the Media Session API.

Wrap up

The Media Session API is a powerful tool for enhancing the media playback experience in web applications. With just a few lines of code, you can add advanced metadata and controls to your songs or videos, giving your users more control and interactivity.

If you want to learn more about API especially API management, we have a written a guide on Rapid API Studio. It is all-in-one API management that you can use to test manage, test, and monetize APIs.

Loading component...