useMediaContext

The useStore hook is from zustand, and inherits all of the documentation for Zustand stores.

Features

Flexible interaction with the player state store
Based on Zustand’s useStore hooks

Anatomy

Import the components and piece the parts together.

import * as Player from "@livepeer/react/player";
import { useMediaContext, useStore } from "@livepeer/react/player";

export default () => (
  <Player.Root>
    {/** The `useMediaContext` hook can be used in any component,
    as long as it's inside the Player.Root React Context provider */}
    <CustomComponent />
  </Player.Root>
);

function CustomComponent({ __scopeMedia }: MediaScopedProps) {
  const context = useMediaContext("CustomComponent", __scopeMedia);

  const { currentSource } = useStore(context.store, ({ currentSource }) => ({
    currentSource,
  }));

  return currentSource?.type ?? null;
}

State

The useMediaContext hook returns a Zustand store, which contains the PlayerState.

`aria`

The ARIA text for the current state, providing accessible descriptions for media control actions.

type AriaText = {
  progress: string;
  pictureInPicture: string;
  fullscreen: string;
  playPause: string;
  clip: string | null;
  time: string;
};

aria: AriaText;

`buffered`

Current buffered end time for the media in seconds.

buffered: number;

`bufferedPercent`

Current buffered percent of the media, from 0 to 1.

bufferedPercent: number;

`canPlay`

Indicates if the media has loaded sufficiently and can be played.

`currentSource`

The current source that is playing.

type Src =
  | AudioSrc
  | HlsSrc
  | VideoSrc
  | Base64Src
  | WebRTCSrc
  | ImageSrc
  | VideoTextTrackSrc;

currentSource: Src | null;

`currentUrl`

The final playback URL for the media that is playing, after any redirects.

currentUrl: string | null;

`duration`

Current total duration of the media in seconds.

duration: number;

`error`

If the media has experienced an error, this property provides details.

type PlaybackError = {
  type: "offline" | "access-control" | "fallback" | "permissions" | "unknown";
  message: string;
};

error: PlaybackError | null;

`errorCount`

The number of consecutive errors that have occurred during the media playback, without resolution.

errorCount: number;

`stalled`

Indicates if the media playback is currently stalled.

`fullscreen`

Indicates if the media is being played in fullscreen mode.

`hasPlayed`

Indicates if the media has been played yet.

`hidden`

Indicates if all controls are currently hidden.

`live`

Indicates if the content is live media.

`loading`

Indicates if the media is currently loading.

`mounted`

Indicates if the video element is mounted on the DOM. This is used for initialization logic.

`playbackRate`

The current playback rate for the media. Defaults to 1. constant means playing WebRTC playback at a constant pace and not speeding up.

type PlaybackRate = number | "constant";

playbackRate: PlaybackRate;

`pictureInPicture`

Indicates if the media is in picture in picture mode.

`poster`

The poster image URL for the media. Any thumbnails are automatically parsed from the input Src[].

poster: string | null;

`progress`

Current progress of the media in seconds.

progress: number;

`playing`

Indicates if the media is currently trying to play or paused.

`sortedSources`

The sorted sources that were passed into the Player. These are the playback sources which will be tried, in order (e.g. WebRTC with a fallback to HLS).

sortedSources: Src[] | string | null;

`volume`

Current volume of the media. 0 if it is muted.

volume: number;

`waiting`

Indicates if the media is currently waiting for data.

`videoQuality`

The quality of the video playback.

type VideoQuality =
  | "1080p"
  | "720p"
  | "480p"
  | "360p"
  | "240p"
  | "144p"
  | "auto";

videoQuality: VideoQuality;

`ended`

Indicates if the media playback has ended.

`__controlsFunctions`

An object containing functions to manipulate the media’s state, such as toggling play/pause, seeking, and changing volume.

These functions are internal - please refer to the UI Kit source code before interacting with these functions.

__controlsFunctions: {
  setHidden: (hidden: boolean) => void;
  onCanPlay: () => void;
  onDurationChange: (duration: number) => void;
  onEnded: () => void;
  onError: (error: Error | null) => void;
  onFinalUrl: (url: string | null) => void;
  onLoading: () => void;
  onPause: () => void;
  onPlay: () => void;
  onProgress: (time: number) => void;
  onStalled: () => void;
  onWaiting: () => void;
  requestClip: () => void;
  requestMeasure: () => void;
  requestSeek: (time: number) => void;
  requestSeekBack: (difference?: number) => void;
  requestSeekDiff: (difference: number) => void;
  requestSeekForward: (difference?: number) => void;
  requestToggleFullscreen: () => void;
  requestToggleMute: () => void;
  requestTogglePictureInPicture: () => void;
  requestVolume: (volume: number) => void;
  setAutohide: (autohide: number) => void;
  setFullscreen: (fullscreen: boolean) => void;
  setHlsConfig: (hlsConfig: any) => void;
  setLive: (live: boolean) => void;
  setMounted: () => void;
  setPictureInPicture: (pictureInPicture: boolean) => void;
  setPlaybackRate: (rate: number | string) => void;
  setPoster: (poster: string | null) => void;
  setVideoQuality: (videoQuality: VideoQuality) => void;
  setSize: (size: Partial<MediaSizing>) => void;
  setVolume: (volume: number) => void;
  setWebsocketMetadata: (metadata: Metadata) => void;
  togglePlay: (force?: boolean) => void;
  updateBuffered: (buffered: number) => void;
  updateLastInteraction: () => void;
  updatePlaybackOffsetMs: (offset: number) => void;
};

`__device`

Information about the device’s capabilities and support for media features. This is an internal object used by Player/Broadcast, but can be used for detecting device capabilities.

type DeviceInformation = {
  version: string;
  isMobile: boolean;
  isIos: boolean;
  isAndroid: boolean;
  userAgent: string;
  screenWidth: number | null;
  /** If the media supports changing the volume */
  isVolumeChangeSupported: boolean;
  /** If the media supports PiP */
  isPictureInPictureSupported: boolean;
  /** If the media supports fullscreen */
  isFullscreenSupported: boolean;
  /** If the media supports HLS playback */
  isHlsSupported: boolean;
  /** If the media supports WebRTC */
  isWebRTCSupported: boolean;
};

__device: DeviceInformation;

`__controls`

Represents the state of various media control actions, such as play/pause and fullscreen changes. This is an internal object used by Player/Broadcast.

__controls: ControlsState;

`__initialProps`

The initial properties passed into the media component. This is an internal object used by Player/Broadcast.

__initialProps: InitialProps;

`__metadata`

Metadata related to the media, such as buffer window and frame rate. This is an internal object used by Player/Broadcast.

type Metadata = {
  bframes?: number;
  bufferWindow?: number;
};

__metadata: Metadata | null;

Overview

Server-side SDKs

React Components

Features

Anatomy

State

`aria`

`buffered`

`bufferedPercent`

`canPlay`

`currentSource`

`currentUrl`

`duration`

`error`

`errorCount`

`stalled`

`fullscreen`

`hasPlayed`

`hidden`

`live`

`loading`

`mounted`

`playbackRate`

`pictureInPicture`

`poster`

`progress`

`playing`

`sortedSources`

`volume`

`waiting`

`videoQuality`

`ended`

`__controlsFunctions`

`__device`

`__controls`

`__initialProps`

`__metadata`

Overview

Server-side SDKs

React Components

​Features

​Anatomy

​State

​aria

​buffered

​bufferedPercent

​canPlay

​currentSource

​currentUrl

​duration

​error

​errorCount

​stalled

​fullscreen

​hasPlayed

​hidden

​live

​loading

​mounted

​playbackRate

​pictureInPicture

​poster

​progress

​playing

​sortedSources

​volume

​waiting

​videoQuality

​ended

​__controlsFunctions

​__device

​__controls

​__initialProps

​__metadata

Features

Anatomy

State

`aria`

`buffered`

`bufferedPercent`

`canPlay`

`currentSource`

`currentUrl`

`duration`

`error`

`errorCount`

`stalled`

`fullscreen`

`hasPlayed`

`hidden`

`live`

`loading`

`mounted`

`playbackRate`

`pictureInPicture`

`poster`

`progress`

`playing`

`sortedSources`

`volume`

`waiting`

`videoQuality`

`ended`

`__controlsFunctions`

`__device`

`__controls`

`__initialProps`

`__metadata`