DEV Community

Cover image for Lock-Screen Controls for a Web Soundboard: the Media Session API, Honest Metadata and Handlers Only for What You Support
Abid Ali
Abid Ali

Posted on

Lock-Screen Controls for a Web Soundboard: the Media Session API, Honest Metadata and Handlers Only for What You Support

Most of the clips on a soundboard are over before anyone could reach for a lock screen. A one-second "bruh" does not need a media card on the phone's notification shade. But a soundboard is rarely only one-second clips. People loop a background track, play a long reaction audio, or leave a board open in a tab while they switch apps. That is when the operating system's media controls start to matter, and when a soundboard that ignores them feels unfinished.

This post walks through the Media Session API from the point of view of a grid of soundboard buttons: when the page should claim the session at all, what the card should say, which hardware and lock-screen buttons it should answer, and how to leave nothing stale behind when the clip ends.

The helpers are plain ES modules. They take the browser objects as arguments, so I could test the logic in Node 20+ with node:test and small fakes. The tests check the decisions, not the audio. What actually appears on a lock screen, a smartwatch or a headset button still depends on the browser and the operating system, and you should check it on the devices you care about.

What the Media Session API does

navigator.mediaSession is the page's way of telling the browser, and through it the operating system, three things:

  1. What is playing. You set navigator.mediaSession.metadata to a new MediaMetadata({ title, artist, album, artwork }). That is the text and image on the media card.
  2. Which controls work. You call navigator.mediaSession.setActionHandler(action, handler) for actions such as play, pause, seekto or nexttrack. Passing null removes a handler.
  3. Where playback is. playbackState can be "playing", "paused" or "none", and setPositionState({ duration, playbackRate, position }) describes the progress bar.

The browser decides when to show a media card. Your page does not get to force one onto the screen, and very short sounds may never get one. What you control is whether the card, when it does appear, tells the truth.

Decide when the board should claim the session

A board full of short clips is a strange fit for a media card. If every tap replaced the metadata, the card would flicker between titles faster than anyone could read it. If you register a nexttrack handler, the headset's skip button now does something on a page that has no idea what "next" means.

So the first decision is not about metadata at all. It is about which plays deserve a session:

  • Long clips. A full reaction audio, a song snippet, an ambient loop.
  • Loop mode. Anything the person set to repeat, because they will want to stop it from outside the tab.
  • Not one-shots. A short hit that ends on its own does not need a pause button on the lock screen.

In the helper below that becomes shouldClaimSession({ duration, loop }). The default threshold is eight seconds. That number is a design choice for this sketch, not a browser rule, so set your own after watching how people use your board.

Honest metadata

The card shows a title, a secondary line and an image. For a sound button the mapping I use is:

  • title: the sound's own name, trimmed, with a readable fallback such as "Untitled sound" instead of an empty string.
  • artist: the site or board name. It answers "where is this coming from?" when the tab is hidden.
  • album: the category the sound sits in, so "Memes" or "Games" rather than a made-up album.
  • artwork: only images with an absolute https URL and a sizes value such as 512x512. A path that depends on the current page, or an image without sizes, is skipped rather than guessed.

Resist the urge to put marketing on the card. "Vine boom" is more useful than "Vine boom - the best free sounds online". The card is a control surface, and it is read at a glance on a locked phone.

Register only the actions you can honour

This is the part that is easiest to get wrong. The API lets you register many actions, and it is tempting to register all of them "just in case". Each one you register is a promise: the button on the headset or the lock screen will now do something.

For a soundboard clip that is playing in loop mode, the honest set is usually small:

  • play and pause, because a looping clip should be stoppable from outside the tab.
  • stop, where the browser supports it, so the card can go away.
  • seekbackward, seekforward and seekto if your player can actually seek. For a short loop, a two-second step is enough.
  • previoustrack and nexttrack only if the board has a real queue, such as a playlist mode. A grid of unrelated buttons usually does not.

There is one more detail: browsers do not all support the same actions, and some of them throw when you register one they do not know. Wrapping each setActionHandler call in its own try means one unsupported action does not stop the others from being registered.

The helpers

Here is the module. It does not touch the DOM or create audio. It decides what to tell the session and wires actions to a small player object that you provide.

// Media Session helpers for a browser soundboard. Plain ES modules, no dependencies.
// The browser objects (navigator.mediaSession, MediaMetadata, HTMLAudioElement) are passed in,
// so the logic can be tested in Node with small fakes.

export const ACTIONS = ["play", "pause", "stop", "seekbackward", "seekforward", "seekto", "previoustrack", "nexttrack"];

/** Build the plain object you pass to `new MediaMetadata(...)` for one sound. */
export function metadataFor(sound, { board = "Soundboard", site = "", artwork = [] } = {}) {
  const title = String(sound.title || "").trim() || "Untitled sound";
  const art = artwork
    .filter((a) => a && /^https:\/\//.test(a.src) && /^\d+x\d+$/.test(a.sizes || ""))
    .map((a) => ({ src: a.src, sizes: a.sizes, type: a.type || "image/png" }));
  return { title, artist: site, album: sound.board || board, artwork: art };
}

/** Clamp numbers so setPositionState() never throws (position must stay within 0..duration, rate must not be 0). */
export function positionStateFor(duration, position, playbackRate = 1) {
  if (!Number.isFinite(duration) || duration <= 0) return null;
  const rate = Number.isFinite(playbackRate) && playbackRate !== 0 ? playbackRate : 1;
  const pos = Math.min(Math.max(Number.isFinite(position) ? position : 0, 0), duration);
  return { duration, playbackRate: rate, position: pos };
}

/** Map an <audio> event name to navigator.mediaSession.playbackState. */
export function playbackStateFor(eventName) {
  if (eventName === "playing" || eventName === "play") return "playing";
  if (eventName === "pause") return "paused";
  return "none"; // ended, emptied, error
}

/**
 * Register only the handlers the board can honour. Unsupported actions throw in some browsers,
 * so each call is wrapped. Returns the actions that were actually registered.
 */
export function installHandlers(session, player, { allowSkip = false, seekStep = 2 } = {}) {
  const wanted = {
    play: () => player.play(),
    pause: () => player.pause(),
    stop: () => player.stop(),
    seekbackward: (d) => player.seekBy(-(d && d.seekOffset ? d.seekOffset : seekStep)),
    seekforward: (d) => player.seekBy(d && d.seekOffset ? d.seekOffset : seekStep),
    seekto: (d) => player.seekTo(d.seekTime),
  };
  if (allowSkip) {
    wanted.previoustrack = () => player.previous();
    wanted.nexttrack = () => player.next();
  }
  const registered = [];
  for (const action of ACTIONS) {
    const fn = wanted[action] || null;
    try {
      session.setActionHandler(action, fn);
      if (fn) registered.push(action);
    } catch {
      // the browser does not know this action; leave it alone
    }
  }
  return registered;
}

/** Remove everything when the board is closed or the clip ends, so the lock screen does not show a stale card. */
export function clearSession(session) {
  session.metadata = null;
  session.playbackState = "none";
  for (const action of ACTIONS) {
    try { session.setActionHandler(action, null); } catch { /* unsupported */ }
  }
}

/** Short clips rarely need a lock-screen card. Claim the session only for long clips or loop mode. */
export function shouldClaimSession({ duration, loop = false }, minSeconds = 8) {
  return Boolean(loop) || (Number.isFinite(duration) && duration >= minSeconds);
}
Enter fullscreen mode Exit fullscreen mode

A few choices in there are worth calling out:

  • positionStateFor() clamps the position into 0..duration and replaces a zero playback rate with 1. setPositionState() throws when the position is past the duration or the rate is zero, which is easy to hit with a looping clip that reports its time a little late. Returning null for a duration that is not a finite positive number lets the caller simply skip the call.
  • installHandlers() registers null for actions the board does not want. That clears handlers left over from an earlier clip, which matters when the same tab plays a long track and then a short one.
  • clearSession() resets the metadata, the playback state and every handler. Call it when the clip ends, when loop mode is turned off and the clip finishes, or when the board is closed.

Wiring it to an audio element

In the browser the glue is short. This sketch uses an HTMLAudioElement; the same idea works with an AudioBufferSourceNode if your player exposes play, pause, stop and seeking.

import { metadataFor, positionStateFor, playbackStateFor, installHandlers, clearSession, shouldClaimSession } from "./media-session.mjs";

const session = "mediaSession" in navigator ? navigator.mediaSession : null;
const audioEl = document.querySelector("#board-audio");

function startSound(audio, sound, { loop = false } = {}) {
  audio.loop = loop;
  audio.src = sound.src;
  const playing = audio.play(); // call play() inside the tap handler, before any await

  if (!session) return playing;
  if (!shouldClaimSession({ duration: sound.duration, loop })) {
    clearSession(session);
    return playing;
  }

  session.metadata = new MediaMetadata(metadataFor(sound, {
    site: "My Soundboard",
    artwork: [{ src: "https://example.com/icons/board-512.png", sizes: "512x512" }],
  }));

  installHandlers(session, {
    play: () => audio.play(),
    pause: () => audio.pause(),
    stop: () => { audio.pause(); audio.currentTime = 0; clearSession(session); },
    seekBy: (s) => { audio.currentTime = Math.max(0, audio.currentTime + s); },
    seekTo: (t) => { audio.currentTime = t; },
  });
  return playing;
}

// call startSound(audioEl, sound, { loop }) from each button's pointerdown or click handler
for (const name of ["playing", "pause", "ended"]) {
  audioEl.addEventListener(name, () => {
    if (!session) return;
    session.playbackState = playbackStateFor(name);
    if (name === "ended" && !audioEl.loop) clearSession(session);
  });
}

audioEl.addEventListener("timeupdate", () => {
  if (!session || !session.setPositionState) return;
  const state = positionStateFor(audioEl.duration, audioEl.currentTime, audioEl.playbackRate);
  if (state) session.setPositionState(state);
});
Enter fullscreen mode Exit fullscreen mode

Two things in that glue are easy to miss.

First, audio.play() is called inside the tap handler before anything else. The session setup can happen after it. If you await something first, some browsers will no longer treat the call as part of the user's gesture.

Second, setPositionState is feature-checked. It is newer than the rest of the API, and calling a missing method throws.

The tests

The fakes are deliberately dull: a session object that records handlers and throws for actions named as unsupported, and a player that records calls.

import test from "node:test";
import assert from "node:assert/strict";
import { metadataFor, positionStateFor, playbackStateFor, installHandlers, clearSession, shouldClaimSession } from "./media-session.mjs";

function fakeSession(unsupported = []) {
  const handlers = {};
  return {
    handlers, metadata: undefined, playbackState: "none",
    setActionHandler(action, fn) {
      if (unsupported.includes(action)) throw new TypeError(`unsupported ${action}`);
      handlers[action] = fn;
    },
  };
}
function fakePlayer() {
  const calls = [];
  const rec = (name) => (...a) => calls.push([name, ...a]);
  return { calls, play: rec("play"), pause: rec("pause"), stop: rec("stop"), seekBy: rec("seekBy"),
           seekTo: rec("seekTo"), previous: rec("previous"), next: rec("next") };
}

test("metadata keeps only absolute https artwork with sizes", () => {
  const m = metadataFor({ title: "  Vine boom ", board: "Memes" }, { site: "Example Board", artwork: [
    { src: "https://example.com/a-512.png", sizes: "512x512" },
    { src: "/icons/board-96.png", sizes: "96x96" },
    { src: "https://example.com/b.png" },
  ] });
  assert.equal(m.title, "Vine boom");
  assert.equal(m.album, "Memes");
  assert.deepEqual(m.artwork, [{ src: "https://example.com/a-512.png", sizes: "512x512", type: "image/png" }]);
});

test("metadata falls back to a readable title", () => {
  assert.equal(metadataFor({ title: "" }).title, "Untitled sound");
});

test("position state is clamped and never uses a zero rate", () => {
  assert.deepEqual(positionStateFor(2.5, 3.1, 0), { duration: 2.5, playbackRate: 1, position: 2.5 });
  assert.deepEqual(positionStateFor(2.5, -1), { duration: 2.5, playbackRate: 1, position: 0 });
  assert.equal(positionStateFor(NaN, 0), null);
  assert.equal(positionStateFor(0, 0), null);
});

test("audio events map to playbackState", () => {
  assert.equal(playbackStateFor("playing"), "playing");
  assert.equal(playbackStateFor("pause"), "paused");
  assert.equal(playbackStateFor("ended"), "none");
});

test("unsupported actions are skipped, not fatal", () => {
  const s = fakeSession(["stop", "seekto"]);
  const p = fakePlayer();
  const reg = installHandlers(s, p);
  assert.deepEqual(reg, ["play", "pause", "seekbackward", "seekforward"]);
  s.handlers.seekbackward({});
  s.handlers.seekforward({ seekOffset: 5 });
  assert.deepEqual(p.calls, [["seekBy", -2], ["seekBy", 5]]);
});

test("track buttons are only offered when the board can skip", () => {
  const s = fakeSession();
  assert.ok(!installHandlers(s, fakePlayer()).includes("nexttrack"));
  assert.equal(s.handlers.nexttrack, null);
  assert.ok(installHandlers(s, fakePlayer(), { allowSkip: true }).includes("nexttrack"));
});

test("clearSession removes metadata and handlers", () => {
  const s = fakeSession(["stop"]);
  installHandlers(s, fakePlayer());
  s.metadata = { title: "x" }; s.playbackState = "playing";
  clearSession(s);
  assert.equal(s.metadata, null);
  assert.equal(s.playbackState, "none");
  assert.equal(s.handlers.play, null);
});

test("short one-shot clips do not claim the session", () => {
  assert.equal(shouldClaimSession({ duration: 1.4 }), false);
  assert.equal(shouldClaimSession({ duration: 1.4, loop: true }), true);
  assert.equal(shouldClaimSession({ duration: 30 }), true);
});
Enter fullscreen mode Exit fullscreen mode

Output from Node:

✔ metadata keeps only absolute https artwork with sizes (1.402085ms)
✔ metadata falls back to a readable title (0.125806ms)
✔ position state is clamped and never uses a zero rate (0.259309ms)
✔ audio events map to playbackState (0.11789ms)
✔ unsupported actions are skipped, not fatal (0.38821ms)
✔ track buttons are only offered when the board can skip (0.189353ms)
✔ clearSession removes metadata and handlers (0.147715ms)
✔ short one-shot clips do not claim the session (0.098102ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 57.243399
Enter fullscreen mode Exit fullscreen mode

These tests prove the decisions: which actions get registered, what gets cleared, how numbers are clamped. They do not prove that a particular phone shows the card the way you expect. For that, open the board on the devices you support, play a long clip, lock the screen and press every control the card shows. If a button appears that your board cannot honour, remove its handler.

Checks before you ship

A short list I run when a board gains lock-screen controls:

  1. Tap a one-second clip. No media card should appear, or if the browser shows one anyway, it should disappear when the clip ends.
  2. Start a loop, lock the phone, press pause. The loop stops. Press play. It resumes from the same place.
  3. Press the skip buttons on a headset. If the board has no queue, nothing should happen.
  4. Switch from a long clip to a short one. The old title should not stay on the card.
  5. Close the tab. The card goes away.
  6. Look at the artwork. It loads from an absolute https URL and is not a stretched favicon.

Where this fits

Lock-screen controls do not make short sound buttons faster or funnier. They make the longer, looping and background uses of a board behave like the rest of the person's media. The work is mostly restraint: claim the session only when the play deserves it, describe it in plain words, answer only the buttons you can honour, and clean up when you are done.

If you keep those four rules, the API is small. The helpers above are under a hundred lines, and most of that is the code that says no.

Top comments (0)