Media Session

Tells the browser what's playing through the Media Session API, and lets the system's media controls drive the player. Press Play in the demo, then try your system's media controls. The line under the player shows what the browser has been told.

"use client";import { useEffect, useState } from "react";import { mediaSession } from "react-video-kit/media-session";import { VideoPlayer } from "react-video-kit/player";const plugins = [  mediaSession({    metadata: {      title: "First light",      artist: "react-video-kit",      artwork: [{ src: "/media/poster.jpg", sizes: "1280x720", type: "image/jpeg" }],    },  }),];export default function MediaSessionDemo() {  const [session, setSession] = useState("not available in this browser");  // The Media Session API has no change event, so this reads it twice a second.  useEffect(() => {    if (!("mediaSession" in navigator)) return;    const read = () => {      const { metadata, playbackState } = navigator.mediaSession;      setSession(`${playbackState}, title: ${metadata?.title ?? "none"}`);    };    read();    const timer = setInterval(read, 500);    return () => clearInterval(timer);  }, []);  return (    <div className="flex flex-col gap-3">      <VideoPlayer src="/media/sample-720.mp4" poster="/media/poster.jpg" plugins={plugins} load="visible" />      <div className="flex flex-col gap-1 text-sm text-current opacity-80">        <p>          Press Play, then look at your system&apos;s media controls or lock screen, or press a media key.          The player tells the browser what&apos;s playing, and the browser decides what to show.        </p>        <p>What the browser has been told: {session}</p>      </div>    </div>  );}

Usage

import { mediaSession } from "react-video-kit/media-session";import { VideoPlayer } from "react-video-kit/player";const plugins = [  mediaSession({    metadata: {      title: "First light",      artist: "Ridge Films",      album: "The long ridge",      artwork: [{ src: "/art.jpg", sizes: "512x512", type: "image/jpeg" }],    },  }),];<VideoPlayer src="/video.mp4" plugins={plugins} />;

seekStep sets how many seconds the system's skip buttons move, and defaults to 10:

mediaSession({ seekStep: 30 });

metadata can also be a function of the source. It runs when the player claims the session, and again each time the source changes while the player owns it:

mediaSession({  metadata: (source) => ({ title: source.src }),});

What the system gets

The browser decides how much of this to show.

• What's playing: the title, artist, album, and artwork you give it.
• Whether it's playing: playbackState, as playing or paused.
• Where it is: duration, rate, and position, updated when the duration, rate, or seeking state changes. Streams with no finite duration, such as live ones, don't send this.
• What it can do: handlers for play, pause, seekbackward, seekforward, and seekto. The skip buttons use the offset the system sends, or seekStep if it sends none. The seek handlers do nothing when the player can't seek, as on plain live or during an ad, though the system may still show the buttons.

There are no handlers for previoustrack or nexttrack, so these buttons don't move through a playlist.

Behaviour

• Nothing changes in the browser until a player first plays. Then that player claims the session.
• A page has one media session, so the player that most recently played owns it. The other players stay as they are.
• A player with no metadata clears what the previous owner set.
• When the owning player unmounts, it clears its handlers and metadata and sets the state to none.
• Actions a browser doesn't know are skipped, and so are positions it rejects.
• Where the API doesn't exist, the plugin does nothing and the player works as usual.
• Actions go through the player's commands, so they respect anything locking them, such as an ad.

API

Options

State

This plugin has no state of its own.

Commands

This plugin has no commands of its own.