Modify Media Notifications with Media Sessions API

Written By Christian Nwamba, Guest Author Aug-09-2022 7 Min Read

The Media Sessions API provides a way to customize media notifications. Let’s imagine this scenario. You have multiple tabs opened with audio and videos playing on each of them and let’s say you want to pause the tab playing “N.Y State of Mind by Nas”, and you don’t want to go to that specific tab to pause the audio. You wished you had a way to control media playback right? That’s where Media Sessions API come in.

The Media Sessions API customizes media notifications by providing metadata for display by the user agent for the media your web app is playing. The API provides us with two interfaces namely;

MediaSession
MediaMetadata

The MediaSession interface is what allows the user to control media playback actions such as play, pause, previoustrack, nexttrack, etc. The MediaMetadata interface as it name implies, allows us to add metadata of the media we want to play. It creates a MediaMetadata object that consists of the following properties;

MediaMetadata.title
MediaMetadata.artist
MediaMetadata.album
MediaMetadata.artwork

In this article, we’ll be building a media controller for audio tracks using the Media Sessions API and Cloudinary for the audio files.

Pre-requisites

To flow with this tutorial, you’ll need the following:

Knowledge of JavaScript
A code editor (VS Code preferably)

The complete code and demo is here on Codesandbox.

Building the Media Controller

Firstly, if you want to follow through with the article, you should create a cloudinary account, and upload some mp3 files and images in seperate folders. This is how it looks on my end:

I have a music folder
Inside the music folder, i have two more folders for individual artists
Each of the folders contain an audio file and images of different sizes

Now we’ve set up the folder structure on cloudinary, let’s go ahead and build the media controller. Create a folder, i’ll call mine media-notifications-controller, open it with your code editor and create an index.html. Add these lines of code to the HTML file:

//index.html
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>MediaSession API for Audio</title>
    </head>
    <body>
        <div>
            <h1> Media Session API for Audio </h1>
            <button id="playButton">Start Playlist</button>
        </div>
        <script src="/main.js"></script>
    </body>
</html>
Code language: HTML, XML (xml)

Here, we have a button with an id playButton, we’ll be using that id soon in the main.js JavaScript file. So let’s go ahead and create a main.js. Add these lines of code:

    //main.js
let audio = document.createElement('audio');
const button = document.getElementById('playButton')
button.addEventListener('click', onPlayButtonClick)
let playlist = getAwesomePlaylist();
let index = 0;
function onPlayButtonClick() {
    playAudio();
}
Code language: JavaScript (javascript)

Firstly, we are creating an audio element (we’ll get to it very soon). Then we say, whenever a user clicks the START PLAYLIST button, it should invoke the onPlayButtonClick() function. The onPlayButtonClick() calls another function called playAudio(). Let’s now create the playAudio() function. Add these lines of code:

//main.js
function playAudio() {
    audio.src = playlist[index].src;
    audio.play()
        .then(_ => updateMetadata())
        .catch(error => console.log(error));
}
Code language: JavaScript (javascript)

The first thing that happens here is assigning playlist audio source (we’ll be creating soon) to the HTML audio element we created earlier. Next, we invoked the audio.play() method and then we return a Promise to invoke the updateMetadata() function if successful, if not, we print the error to our browser console. Let’s now create the updateMetadata(). Add these lines of code:

//main.js

function updateMetadata() {
    let track = playlist[index];
        console.log('Playing ' + track.title + ' track...');
    navigator.mediaSession.metadata = new MediaMetadata({
        title: track.title,
        artist: track.artist,
        album: track.album,
        artwork: track.artwork
    });
    updatePositionState();
}
Code language: JavaScript (javascript)

Here, we introduce the MediaMetadata interface of the Media Sessions API. This will enable us add information such as title, artist, album and artwork to the Media Controller. We invoke a updatePositionState() function, this enables us to set playback position. It’s important to know that the position state is a combination of the media playback rate, duration, and current time. Let’s go ahead and create that function. Add these lines of code:

//main.js
function updatePositionState() {
    if ('setPositionState' in navigator.mediaSession) {
        console.log('Updating position state...');
        navigator.mediaSession.setPositionState({
            duration: audio.duration,
            playbackRate: audio.playbackRate,
            position: audio.currentTime
        });
    }
}
Code language: JavaScript (javascript)

You will notice that setPositionState accepts duration, playbackRate and position as arguments and we are getting the values from our audio element. Next, we’ll handle actions. To handle actions we will use the MediaSession interface method setActionHandler(). Let’s create the action handler for playing previous track. Add these lines of code:

//main.js
navigator.mediaSession.setActionHandler('previoustrack', function () {
    console.log('You clicked "Previous Track" icon.');
    index = (index - 1 + playlist.length) % playlist.length;
    playAudio();
});
Code language: JavaScript (javascript)

The action handler for next track. Add these lines of code:

//main.js
navigator.mediaSession.setActionHandler('nexttrack', function () {
    console.log('> You clicked "Next Track" icon.');
    index = (index + 1) % playlist.length;
    playAudio();
});
Code language: JavaScript (javascript)

The action handler for when a track has ended.

audio.addEventListener('ended', function () {
    index = (index - 1 + playlist.length) % playlist.length;
    playAudio();
});
Code language: JavaScript (javascript)

When a track ends, this action handler enables the controller to play the next track automatically.

Typically, a media controller will have fast forward and backwards buttons. Let’s create the action handlers for each of them. The action handler to go backwards. Add these lines of code:

//main.js
let defaultSkipTime = 10; /* Time to skip in seconds by default */
    navigator.mediaSession.setActionHandler('seekbackward', function (event) {
    console.log('You clicked "Seek Backward" icon.');
    const skipTime = event.seekOffset || defaultSkipTime;
    audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
    updatePositionState();
});
Code language: JavaScript (javascript)

The action handler to fast forward. Add these lines of code:

    //main.js
navigator.mediaSession.setActionHandler('seekforward', function (event) {
    console.log('You clicked "Seek Forward" icon.');
    const skipTime = event.seekOffset || defaultSkipTime;
    audio.currentTime = Math.min(audio.currentTime + skipTime, audio.duration);
    updatePositionState();
});
Code language: JavaScript (javascript)

Next, we’ll create action handlers for play and pause buttons. Add these lines of code:

//main.js
navigator.mediaSession.setActionHandler('play', async function () {
    console.log('You clicked "Play" icon.');
    await audio.play();
});
Code language: JavaScript (javascript)

//main.js
navigator.mediaSession.setActionHandler('pause', function () {
    console.log('You clicked "Pause" icon.');
    audio.pause();
});
Code language: JavaScript (javascript)

Sometimes when fast forwarding or loading a track, the browser may consider the webpage to not be playing the audio track, we have to override this behavior. Add these lines of code to do that:

//main.js
audio.addEventListener('play', function () {
    navigator.mediaSession.playbackState = 'playing';
});
audio.addEventListener('pause', function () {
    navigator.mediaSession.playbackState = 'paused';
});
Code language: JavaScript (javascript)

Let’s create one last action handler. This will be for the stop action. Add these lines of code:

//main.js

try {
    navigator.mediaSession.setActionHandler('stop', function () {
        console.log('> User clicked "Stop" icon.');
    });
} catch (error) {
    console.log('Warning! The "stop" media session action is not supported.');
}
Code language: JavaScript (javascript)

Awesome! We are almost done. Let’s now go ahead and create the getAwesomePlaylist function. This function will return the track data. Add these lines of code:

//main.js
    
function getAwesomePlaylist() {
    const BASE_URL = 'https://res.cloudinary.com/sammy365/video/upload/v1658489677/music/';
    const IMG_BASE_URL = 'https://res.cloudinary.com/sammy365/image/upload/v1658489645/music/';

return [{
    src: BASE_URL + 'Asake/Asake-PBUY.mp3',
    title: 'PBUY',
    artist: 'Asake',
    album: 'Asake Reloaded',
    artwork: [
        { src: IMG_BASE_URL + 'Asake/asake-96.png', sizes: '96x96', type: 'image/png' },
        { src: IMG_BASE_URL + 'Asake/asake-128.png', sizes: '128x128', type: 'image/png' },
        { src: IMG_BASE_URL + 'Asake/asake-192.png', sizes: '192x192', type: 'image/png' },
        { src: IMG_BASE_URL + 'Asake/asake-384.png', sizes: '384x384', type: 'image/png' },
        { src: IMG_BASE_URL + 'Asake/asake-512.png', sizes: '512x512', type: 'image/png' },
    ]
    },
    {
    src: BASE_URL + 'olamide/Bad_Boy_Timz_-_Skelele_Official_Audio_ft._Olamide.mp3',
    title: 'Skelele',
    artist: 'Olamide',
    album: 'Olamide Reloaded',
    artwork: [
        { src: IMG_BASE_URL + 'olamide/olamide-96.png', sizes: '96x96', type: 'image/png' },
        { src: IMG_BASE_URL + 'olamide/olamide-128.png', sizes: '128x128', type: 'image/png' },
        { src: IMG_BASE_URL + 'olamide/olamide-192.png', sizes: '192x192', type: 'image/png' },
        { src: IMG_BASE_URL + 'olamide/olamide-384.png', sizes: '384x384', type: 'image/png' },
        { src: IMG_BASE_URL + 'olamide/olamide-512.png', sizes: '512x512', type: 'image/png' },
    ]
    }
];
}
Code language: JavaScript (javascript)

Yep! that’s it. Open the website with Live Server and you should see something like this:

https://www.dropbox.com/s/202qnwf49e34dc4/mediaSession.webm?dl=0

Conclusion

In this article, we explored the MediaSessions API. We discussed about it’s two interfaces namely; MediaSession and MediaMetadata. We went ahead to build a media controller with JavaScript using the MediaSessions API. I hope you’ve picked up a thing or two from this article.

Modify Media Notifications with Media Sessions API

Pre-requisites

Building the Media Controller

Conclusion

The Pros and Cons of AI Chatbots in Dev Tool Docs

Products

Solutions

Developers

Company

Contact Us

Pre-requisites

Building the Media Controller

Conclusion

Featured Post