SSE Hooks

useMediaSession

Custom hook that interacts with the Media Session API. It allows you to customize media notifications and handle media control events (like play, pause, next track) from the system's notification area or lock screen.

Installation

npx sse-hooks add use-media-session

Usage

example.ts
import { useMediaSession } from "./{hooks file}";

const MyPlayer = () => {
  const { setMetadata, setPlaybackState } = useMediaSession({
    playbackState: "playing",
    metadata: {
      title: "Awesome Song",
      artist: "Cool Artist",
      album: "Best Hits",
      artwork: [
        { src: "/album-art.jpg", sizes: "512x512", type: "image/jpeg" },
      ],
    },
    actionHandlers: {
      play: () => console.log("Play clicked"),
      pause: () => console.log("Pause clicked"),
      nexttrack: () => console.log("Next track clicked"),
    },
  });

  return <div>Now Playing...</div>;
};

API

Parameters

Prop Default Type
options-

UseMediaSessionOptions

Initial configuration for the media session.

Returns

Return Value Default Type
clearActionHandlers-

() => void

Function to clear all registered action handlers.

isSupported-

boolean

Whether the Media Session API is supported in the current environment.

setActionHandler-

(action: MediaSessionAction, handler: MediaSessionActionHandler | null) => void

Function to set a specific action handler.

setMetadata-

(metadata: MediaMetadataInit) => void

Function to update the media metadata.

setPlaybackState-

(state: MediaSessionPlaybackState) => void

Function to update the playback state.

Types Aliases

No specific type aliases defined for this component.

Changelog

c165d — feat: enhance useRoleGuard and useSSR hooks with additional options and documentation

30da4 — feat: add new hooks and their metadata

b17e8 — feat: add computed and reactive hooks with support for audio recording and media session management

Built with Love • © 2026