useMediaContext
The useMediaContext hook lets you build custom components which interact directly with the media state store.
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
useStorehooks
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;