useMediaSession

sensors

Installation

npx usehooks-cli@latest add use-media-session

Description

A hook for integrating with the Media Session API to control media playback from system UI, notifications, and hardware media keys. Allows setting metadata and handling media control actions.

Parameters

Name	Type	Default	Description
options?	UseMediaSessionOptions	-	Configuration options for media session

Parameter Properties

options properties:

Name	Type	Description
metadata?	MediaMetadataInit	Initial metadata for the media session
playbackState?	MediaSessionPlaybackState	Initial playback state ('none', 'paused', 'playing')
actionHandlers?	Partial<Record<MediaSessionAction, MediaSessionActionHandler>>	Initial action handlers for media controls

Return Type

UseMediaSessionReturn

Property	Type	Description
isSupported	boolean	Whether the Media Session API is supported
setMetadata	(metadata: MediaMetadataInit) => void	Set media metadata (title, artist, album, artwork)
setPlaybackState	(state: MediaSessionPlaybackState) => void	Set the current playback state
setActionHandler	(action: MediaSessionAction, handler: MediaSessionActionHandler \| null) => void	Set or remove an action handler for media controls
clearActionHandlers	() => void	Clear all action handlers

Examples

Basic Audio Player

Simple audio player with media session integration

import { useMediaSession } from '@usehooks/use-media-session';
import { useRef, useState } from 'react';

function AudioPlayer() {
  const audioRef = useRef<HTMLAudioElement>(null);
  const [isPlaying, setIsPlaying] = useState(false);
  const [currentTrack, setCurrentTrack] = useState(0);
  
  const tracks = [
    {
      title: 'Song One',
      artist: 'Artist Name',
      album: 'Album Name',
      src: '/audio/song1.mp3',
      artwork: [{ src: '/images/album1.jpg', sizes: '512x512', type: 'image/jpeg' }]
    },
    {
      title: 'Song Two',
      artist: 'Artist Name',
      album: 'Album Name',
      src: '/audio/song2.mp3',
      artwork: [{ src: '/images/album2.jpg', sizes: '512x512', type: 'image/jpeg' }]
    }
  ];

  const {
    isSupported,
    setMetadata,
    setPlaybackState,
    setActionHandler
  } = useMediaSession();

  const play = () => {
    audioRef.current?.play();
    setIsPlaying(true);
    setPlaybackState('playing');
  };

  const pause = () => {
    audioRef.current?.pause();
    setIsPlaying(false);
    setPlaybackState('paused');
  };

  const nextTrack = () => {
    const next = (currentTrack + 1) % tracks.length;
    setCurrentTrack(next);
    updateMetadata(next);
  };

  const prevTrack = () => {
    const prev = (currentTrack - 1 + tracks.length) % tracks.length;
    setCurrentTrack(prev);
    updateMetadata(prev);
  };

  const updateMetadata = (trackIndex: number) => {
    const track = tracks[trackIndex];
    setMetadata({
      title: track.title,
      artist: track.artist,
      album: track.album,
      artwork: track.artwork
    });
  };

  // Set up media session handlers
  React.useEffect(() => {
    if (isSupported) {
      setActionHandler('play', play);
      setActionHandler('pause', pause);
      setActionHandler('nexttrack', nextTrack);
      setActionHandler('previoustrack', prevTrack);
      
      // Set initial metadata
      updateMetadata(currentTrack);
    }
  }, [isSupported, currentTrack]);

  return (
    <div>
      <audio
        ref={audioRef}
        src={tracks[currentTrack].src}
        onPlay={() => {
          setIsPlaying(true);
          setPlaybackState('playing');
        }}
        onPause={() => {
          setIsPlaying(false);
          setPlaybackState('paused');
        }}
        onEnded={nextTrack}
      />
      
      <div>
        <h3>{tracks[currentTrack].title}</h3>
        <p>{tracks[currentTrack].artist} - {tracks[currentTrack].album}</p>
      </div>
      
      <div>
        <button onClick={prevTrack}>⏮</button>
        <button onClick={isPlaying ? pause : play}>
          {isPlaying ? '⏸' : '▶️'}
        </button>
        <button onClick={nextTrack}>⏭</button>
      </div>
      
      {!isSupported && (
        <p>Media Session API not supported</p>
      )}
    </div>
  );
}

Podcast Player

Podcast player with seek controls and chapter support

import { useMediaSession } from '@usehooks/use-media-session';
import { useRef, useState, useEffect } from 'react';

function PodcastPlayer() {
  const audioRef = useRef<HTMLAudioElement>(null);
  const [isPlaying, setIsPlaying] = useState(false);
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);

  const podcast = {
    title: 'Episode 42: React Hooks Deep Dive',
    artist: 'Tech Podcast',
    album: 'Season 3',
    src: '/audio/podcast-episode.mp3',
    artwork: [
      { src: '/images/podcast-cover.jpg', sizes: '512x512', type: 'image/jpeg' }
    ]
  };

  const {
    setMetadata,
    setPlaybackState,
    setActionHandler
  } = useMediaSession({
    metadata: podcast,
    playbackState: 'paused'
  });

  const play = () => {
    audioRef.current?.play();
    setIsPlaying(true);
    setPlaybackState('playing');
  };

  const pause = () => {
    audioRef.current?.pause();
    setIsPlaying(false);
    setPlaybackState('paused');
  };

  const seekBackward = () => {
    if (audioRef.current) {
      audioRef.current.currentTime = Math.max(0, audioRef.current.currentTime - 10);
    }
  };

  const seekForward = () => {
    if (audioRef.current) {
      audioRef.current.currentTime = Math.min(
        audioRef.current.duration,
        audioRef.current.currentTime + 30
      );
    }
  };

  const seekTo = (details: { seekTime?: number }) => {
    if (audioRef.current && details.seekTime !== undefined) {
      audioRef.current.currentTime = details.seekTime;
    }
  };

  // Set up media session handlers
  useEffect(() => {
    setActionHandler('play', play);
    setActionHandler('pause', pause);
    setActionHandler('seekbackward', seekBackward);
    setActionHandler('seekforward', seekForward);
    setActionHandler('seekto', seekTo);
  }, []);

  // Update time
  useEffect(() => {
    const audio = audioRef.current;
    if (!audio) return;

    const updateTime = () => setCurrentTime(audio.currentTime);
    const updateDuration = () => setDuration(audio.duration);

    audio.addEventListener('timeupdate', updateTime);
    audio.addEventListener('loadedmetadata', updateDuration);

    return () => {
      audio.removeEventListener('timeupdate', updateTime);
      audio.removeEventListener('loadedmetadata', updateDuration);
    };
  }, []);

  const formatTime = (time: number) => {
    const minutes = Math.floor(time / 60);
    const seconds = Math.floor(time % 60);
    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
  };

  return (
    <div style={{ maxWidth: '400px', margin: '0 auto', padding: '20px' }}>
      <audio
        ref={audioRef}
        src={podcast.src}
        onPlay={() => {
          setIsPlaying(true);
          setPlaybackState('playing');
        }}
        onPause={() => {
          setIsPlaying(false);
          setPlaybackState('paused');
        }}
      />
      
      <div style={{ textAlign: 'center', marginBottom: '20px' }}>
        <img
          src={podcast.artwork[0].src}
          alt="Podcast cover"
          style={{ width: '200px', height: '200px', borderRadius: '8px' }}
        />
        <h3>{podcast.title}</h3>
        <p>{podcast.artist}</p>
      </div>
      
      <div style={{ marginBottom: '20px' }}>
        <input
          type="range"
          min={0}
          max={duration || 0}
          value={currentTime}
          onChange={(e) => {
            const time = parseFloat(e.target.value);
            if (audioRef.current) {
              audioRef.current.currentTime = time;
            }
          }}
          style={{ width: '100%' }}
        />
        <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: '12px' }}>
          <span>{formatTime(currentTime)}</span>
          <span>{formatTime(duration)}</span>
        </div>
      </div>
      
      <div style={{ display: 'flex', justifyContent: 'center', gap: '10px' }}>
        <button onClick={seekBackward}>⏪ 10s</button>
        <button onClick={isPlaying ? pause : play} style={{ fontSize: '24px' }}>
          {isPlaying ? '⏸' : '▶️'}
        </button>
        <button onClick={seekForward}>30s ⏩</button>
      </div>
    </div>
  );
}

Dynamic Metadata Updates

Update media session metadata dynamically based on content

import { useMediaSession } from '@usehooks/use-media-session';
import { useState, useEffect } from 'react';

function DynamicMediaSession() {
  const [currentContent, setCurrentContent] = useState('music');
  const [isActive, setIsActive] = useState(false);

  const {
    isSupported,
    setMetadata,
    setPlaybackState,
    setActionHandler,
    clearActionHandlers
  } = useMediaSession();

  const contentTypes = {
    music: {
      title: 'Beautiful Song',
      artist: 'Amazing Artist',
      album: 'Great Album',
      artwork: [{ src: '/music-cover.jpg', sizes: '512x512', type: 'image/jpeg' }]
    },
    podcast: {
      title: 'Tech Talk Episode 15',
      artist: 'Tech Podcast Network',
      album: 'Season 2',
      artwork: [{ src: '/podcast-cover.jpg', sizes: '512x512', type: 'image/jpeg' }]
    },
    audiobook: {
      title: 'Chapter 3: The Journey Begins',
      artist: 'Famous Author',
      album: 'Epic Novel',
      artwork: [{ src: '/book-cover.jpg', sizes: '512x512', type: 'image/jpeg' }]
    }
  };

  const handlePlay = () => {
    setIsActive(true);
    setPlaybackState('playing');
    console.log('Playing:', currentContent);
  };

  const handlePause = () => {
    setIsActive(false);
    setPlaybackState('paused');
    console.log('Paused:', currentContent);
  };

  const handleStop = () => {
    setIsActive(false);
    setPlaybackState('none');
    console.log('Stopped:', currentContent);
  };

  // Update metadata when content type changes
  useEffect(() => {
    if (isSupported) {
      const metadata = contentTypes[currentContent as keyof typeof contentTypes];
      setMetadata(metadata);
    }
  }, [currentContent, isSupported]);

  // Set up action handlers
  useEffect(() => {
    if (isSupported) {
      setActionHandler('play', handlePlay);
      setActionHandler('pause', handlePause);
      setActionHandler('stop', handleStop);

      return () => {
        clearActionHandlers();
      };
    }
  }, [isSupported]);

  if (!isSupported) {
    return <div>Media Session API not supported</div>;
  }

  return (
    <div style={{ padding: '20px' }}>
      <h2>Dynamic Media Session</h2>
      
      <div style={{ marginBottom: '20px' }}>
        <label>Content Type: </label>
        <select
          value={currentContent}
          onChange={(e) => setCurrentContent(e.target.value)}
        >
          <option value="music">Music</option>
          <option value="podcast">Podcast</option>
          <option value="audiobook">Audiobook</option>
        </select>
      </div>

      <div style={{ marginBottom: '20px' }}>
        <h3>Current Metadata:</h3>
        <pre style={{ backgroundColor: '#f5f5f5', padding: '10px', borderRadius: '4px' }}>
          {JSON.stringify(contentTypes[currentContent as keyof typeof contentTypes], null, 2)}
        </pre>
      </div>

      <div>
        <button onClick={handlePlay} disabled={isActive}>
          Play
        </button>
        <button onClick={handlePause} disabled={!isActive}>
          Pause
        </button>
        <button onClick={handleStop}>
          Stop
        </button>
      </div>

      <p>Status: {isActive ? 'Active' : 'Inactive'}</p>
      <p>Use your device's media controls or notification to test the integration!</p>
    </div>
  );
}

Dependencies

react

Notes

•Only available in browsers that support the Media Session API (Chrome 57+, Firefox 82+)
•Requires active media element for full functionality
•Media controls appear in system notifications, lock screen, and hardware keys
•Artwork should be provided in multiple sizes for best compatibility
•Action handlers are automatically cleared on component unmount
•Some actions may not be available on all platforms

Implementation

'use client';

import { useEffect, useCallback, useRef } from "react";

interface MediaImage {
  src: string;
  sizes?: string;
  type?: string;
}

interface MediaMetadataInit {
  title?: string;
  artist?: string;
  album?: string;
  artwork?: MediaImage[];
}

type MediaSessionAction =
  | "play"
  | "pause"
  | "stop"
  | "seekbackward"
  | "seekforward"
  | "seekto"
  | "skipad"
  | "previoustrack"
  | "nexttrack";

type MediaSessionPlaybackState = "none" | "paused" | "playing";

type MediaSessionActionHandler = (details?: any) => void;

interface UseMediaSessionOptions {
  metadata?: MediaMetadataInit;
  playbackState?: MediaSessionPlaybackState;
  actionHandlers?: Partial<
    Record<MediaSessionAction, MediaSessionActionHandler>
  >;
}

interface UseMediaSessionReturn {
  isSupported: boolean;
  setMetadata: (metadata: MediaMetadataInit) => void;
  setPlaybackState: (state: MediaSessionPlaybackState) => void;
  setActionHandler: (
    action: MediaSessionAction,
    handler: MediaSessionActionHandler | null
  ) => void;
  clearActionHandlers: () => void;
}

const useMediaSession = (
  options?: UseMediaSessionOptions
): UseMediaSessionReturn => {
  const actionHandlersRef = useRef<Set<MediaSessionAction>>(new Set());

  const isSupported =
    typeof navigator !== "undefined" && "mediaSession" in navigator;

  const setMetadata = useCallback(
    (metadata: MediaMetadataInit) => {
      if (!isSupported) return;

      try {
        navigator.mediaSession.metadata = new MediaMetadata(metadata);
      } catch (error) {
        console.warn("Failed to set media metadata:", error);
      }
    },
    [isSupported]
  );

  const setPlaybackState = useCallback(
    (state: MediaSessionPlaybackState) => {
      if (!isSupported) return;

      try {
        navigator.mediaSession.playbackState = state;
      } catch (error) {
        console.warn("Failed to set playback state:", error);
      }
    },
    [isSupported]
  );

  const setActionHandler = useCallback(
    (action: MediaSessionAction, handler: MediaSessionActionHandler | null) => {
      if (!isSupported) return;

      try {
        navigator.mediaSession.setActionHandler(action, handler);
        if (handler) {
          actionHandlersRef.current.add(action);
        } else {
          actionHandlersRef.current.delete(action);
        }
      } catch (error) {
        console.warn(`Failed to set action handler for ${action}:`, error);
      }
    },
    [isSupported]
  );

  const clearActionHandlers = useCallback(() => {
    if (!isSupported) return;

    actionHandlersRef.current.forEach((action) => {
      try {
        navigator.mediaSession.setActionHandler(action, null);
      } catch (error) {
        console.warn(`Failed to clear action handler for ${action}:`, error);
      }
    });
    actionHandlersRef.current.clear();
  }, [isSupported]);

  // Set initial metadata if provided
  useEffect(() => {
    if (options?.metadata) {
      setMetadata(options.metadata);
    }
  }, [setMetadata, options?.metadata]);

  // Set initial playback state if provided
  useEffect(() => {
    if (options?.playbackState) {
      setPlaybackState(options.playbackState);
    }
  }, [setPlaybackState, options?.playbackState]);

  // Set initial action handlers if provided
  useEffect(() => {
    if (options?.actionHandlers) {
      Object.entries(options.actionHandlers).forEach(([action, handler]) => {
        if (handler) {
          setActionHandler(action as MediaSessionAction, handler);
        }
      });
    }

    // Cleanup function to clear all action handlers when component unmounts
    return () => {
      clearActionHandlers();
    };
  }, [setActionHandler, clearActionHandlers, options?.actionHandlers]);

  return {
    isSupported,
    setMetadata,
    setPlaybackState,
    setActionHandler,
    clearActionHandlers,
  };
};

export { useMediaSession };
export type {
  MediaImage,
  MediaMetadataInit,
  MediaSessionAction,
  MediaSessionPlaybackState,
  MediaSessionActionHandler,
  UseMediaSessionOptions,
  UseMediaSessionReturn,
};

useIsTablet

CLI Docs All Hooks

useNetworkInformation