Root

​

Features

• Pure React Context provider to pass the broadcast and media state store to all components
• Automatic SDP negotiation with a WebRTC WHIP endpoint

​

Anatomy

Import the components and piece the parts together.

import * as Broadcast from "@livepeer/react/broadcast";

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

​

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.

​

Props

​

ingestUrl

Configures the WHIP WebRTC ingest URL for the Broadcast component. You can create the ingestUrl by passing getIngest a string (interpreted as a Livepeer Studio stream key or URL), Livepeer Studio stream data, or Cloudflare stream data. Broadcast is compatible with all WHIP playback endpoints.

<Broadcast.Root ingestUrl={getIngest(streamKey)}>{...}</Broadcast.Root>

​

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).

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

​

forceEnabled

Determines whether the WebRTC stream should start immediately after the user allows access to their video/audio input. The default is false, which previews the video first, then streams media to the server upon activation.

<Broadcast.Root forceEnabled={true}>{...}</Broadcast.Root>

​

audio

Controls whether audio is enabled initially for the broadcast. The default is true. Set to false to start the broadcast without requesting an audio track.

This can be an object that adheres to the structure of MediaTrackConstraints, which will constrain the audio track used in the broadcast.

<Broadcast.Root audio={false}>{...}</Broadcast.Root>

​

video

Controls whether video is enabled initially for the broadcast. The default is true. Set to false to start the broadcast without requesting a video track.

This can be an object that adheres to the structure of MediaTrackConstraints, which will constrain the video track used in the broadcast. This is usually used to limit the resolution of the video and improve bandwidth usage.

<Broadcast.Root video={{
  width: {
    ideal: 1920,
  },
  height: {
    ideal: 1080,
  },
}}>{...}</Broadcast.Root>

​

hotkeys

Enables keyboard hotkeys for controlling the broadcast. 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.

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

​

creatorId

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

<Broadcast.Root creatorId="creator123">{...}</Broadcast.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;
};

<Broadcast.Root onError={(error) => console.log(error)}>{...}</Broadcast.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.

<Broadcast.Root timeout={15000}>{...}</Broadcast.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.

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