Root

This is a comprehensive example of how the Player elements can fit together to build an advanced video player. This does not only show the Root Player, but how the Root can be used to provide a state store to all of its children.

Features

Pure React Context provider to pass the media store state to all components

Anatomy

Import the components and piece the parts together.

import * as Player from "@livepeer/react/player";

export default () => (
  <Player.Root>
    {/* All child components which use the state store. */}
  </Player.Root>
);

Compatibility

The compatibility table below applies to the Player broadly, since the Root component is only a React context.

Browser	Version
Chrome	102+
Chrome for Android	105+
iOS Safari	12.2+
Edge	103+
Safari	13.1+
Firefox	103+
Opera	89+
Samsung Internet	17+
UC Browser	13.4+
Firefox Android	104+
Opera Mini	all

We aim to support ~93% of browsers tracked on caniuse. We use browserslist to track compatibility.

Usage

The Player.Root component is a React Context wrapper which passes the player state store down to all of the child components. It is responsible for creating the Zustand state store which is consumed by the children, and listens for media/browser events and keeps state in sync.

The Player automatically handles different source types, such as WebRTC, MP4, and HLS. These are seamlessly integrated so that playback has low latency under all network conditions.It is compatible with WebRTC WHEP endpoints, HLS (and low latency HLS), or typical media file playable by an HTML5 video element (MP4, WebM).

Props

`src`

Defines the source for the Player. It accepts Src[], which can be derived from various sources like Livepeer playback info, Cloudflare stream data, Mux URLs, or simple strings. See getSrc for docs on how to easily generate this parameter.

`autoPlay` and `volume`

Sets the video to autoplay when the content comes into focus on the webpage. If autoPlay is specified, volume is highly recommended to be set to 0. Autoplay will not work in many modern browsers without setting mute to 0.

`aspectRatio`

Specifies the aspect ratio of the content. Recommended for an optimal broadcasting experience to minimize Cumulative Layout Shift. The default value is 16 / 9. Set to null to disable the aspect ratio container (see Container).

<Player.Root aspectRatio={16 / 9}>{...}</Player.Root>

`hotkeys`

Enables keyboard hotkeys for controlling the player. Enabled by default (true). It’s recommended to follow ARIA guidelines by keeping this enabled unless you’re implementing custom hotkeys or there’s a conflict with existing ones.

<Player.Root hotkeys={false}>{...}</Player.Root>

`viewerId`

Sets the viewer ID for the broadcast, useful for metrics and viewership API integration.

<Player.Root viewerId="viewer123">{...}</Player.Root>

`onError`

An optional callback for handling broadcasting errors. It’s called with null when the previous error is resolved. The callback receives the parameter:

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

<Player.Root onError={(error) => console.log(error)}>{...}</Player.Root>

`jwt` or `accessKey`

These define ways to play back a video which has a playback policy applied to it. Your application can prevent playback unless the user meets application-specific requirements. This can be done either with JWTs or webhooks.

Defines the JSON Web Token (JWT) or access key used to access media gated by a jwt or webhook playback policy respectively. It’s crucial for implementing application-specific access control like restricting viewership based on certain criteria (e.g., having an activated account, etc.).

<Player.Root jwt={jwt}>{...}</Player.Root>
<Player.Root accessKey="access-key">{...}</Player.Root>

`lowLatency`

Enables low-latency playback for live streams via WebRTC by default. If set to "force", it forces WebRTC playback and disables fallback to HLS. This is ideal for applications requiring low latency and can tolerate possible connectivity issues inherent to WebRTC. Defaults to true. If this does not succeed in playing back (commonly due to a slow network or connectivity issues), the Player will automatically fall back to HLS playback. Also, if the stream contains B-frames (bidirectional frames, which are common for users streaming with OBS or other streaming apps), the Player will automatically switch to HLS, so that out-of-order frames are not displayed.

OBS users should be instructed to use the Livepeer stream profile, or to manually turn off B-frames in their stream. See our Stream from OBS docs for more information.

<Player.Root lowLatency="force">{...}</Player.Root>

`timeout`

Sets the timeout duration for playback before switching to the next source, including SDP negotiation for WebRTC, waiting for WebRTC to play, and server responses. The default is 10000 milliseconds.

<Player.Root timeout={15000}>{...}</Player.Root>

`storage`

Configures the storage option for saving persistent states like volume and video quality. The default is localStorage in the browser. Set to null to disable storage.

<Player.Root storage={null}>{...}</Player.Root>

Overview

Server-side SDKs

React Components

Features

Anatomy

Compatibility

Usage

Props

`src`

`autoPlay` and `volume`

`aspectRatio`

`hotkeys`

`viewerId`

`onError`

`jwt` or `accessKey`

`lowLatency`

`timeout`

`storage`

Overview

Server-side SDKs

React Components

​Features

​Anatomy

​Compatibility

​Usage

​Props

​src

​autoPlay and volume

​aspectRatio

​hotkeys

​viewerId

​onError

​jwt or accessKey

​lowLatency

​timeout

​storage

Features

Anatomy

Compatibility

Usage

Props

`src`

`autoPlay` and `volume`

`aspectRatio`

`hotkeys`

`viewerId`

`onError`

`jwt` or `accessKey`

`lowLatency`

`timeout`

`storage`