Broadcast

The Broadcast component provides an easy way to livestream video or audio, including camera and screen sources. It automatically handles WebRTC connection and allows extremely low latency livestreaming.

Usage

React Native
React Native

import { Broadcast } from '@livepeer/react';

The following example assumes a stream was created via useCreateStream, and the streamKey was passed to the Broadcast component.

import { Broadcast } from '@livepeer/react';

function BroadcastComponent() {
  return (
    <Broadcast
      streamKey="abcd-dcba-1234-4321"
    />
  );
};

Configuration

streamKey

function BroadcastComponent() {
  return <Broadcast streamKey="abcd-dcba-1234-4321" />;
}

The streamKey passed to the Broadcast component is used to connect to the WebRTC ingest URL.

title

The title for the content. This is highly recommended, since it is used for accessibility labels in the Broadcast. If you do not want to show the title visually, see showTitle.

function BroadcastComponent() {
  return <Broadcast title="You, Live" streamKey="abcd-dcba-1234-4321" />;
}

showTitle

Enables/disables the title component.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      showTitle={false}
    />
  );
}

displayMediaOptions

The display media stream options to use when requesting screen share. This is usually a set of audio and video MediaTrackConstraints which are passed to the browser to limit the sources available to the user.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      displayMediaOptions={{
        video: {
          width: {
            ideal: 1280,
          },
        },
      }}
    />
  );
}

aspectRatio

Sets the aspect ratio for the content. Highly recommended for a great broadcasting experience (for more information, see Cumulative Layout Shift). Defaults to 16to9.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      aspectRatio="1to1"
    />
  );
}

controls

Configures the timeout for autohiding controls, default volume, and (only on web) if keyboard hotkeys for controlling the broadcast are enabled.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      controls={{ autohide: 0, hotkeys: false, defaultVolume: 0.6 }}
    />
  );
}

muted

Sets the video to muted when the broadcast started.

function BroadcastComponent() {
  return <Broadcast title="You, Live" streamKey="abcd-dcba-1234-4321" muted />;
}

objectFit

Sets the video’s object fit property. Defaults to contain. cover is usually used when there is a guarantee that the aspectRatio matches the content displayed in the Broadcast.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      aspectRatio="1to1"
      objectFit="cover"
    />
  );
}

showPipButton

Shows the Picture-in-Picture button to the left of the fullscreen button. Defaults to false. See children for an example on how to use the underlying <PictureInPictureButton />.

We support both the w3c standard (which most modern browsers support), as well as the older Safari/iOS spec. See the browsers which support Picture-in-Picture on caniuse.

import { Player } from "@livepeer/react";

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      showPipButton
    />
  );
}

theme

Sets the Player-specific theme overrides. It is recommended to use LivepeerConfig for any global app styles, and the theme prop to override those styles on a per-Broadcast basis.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      theme={{
        borderStyles: {
          containerBorderStyle: "hidden",
        },
        colors: {
          accent: "#00a55f",
        },
        space: {
          controlsBottomMarginX: "10px",
          controlsBottomMarginY: "5px",
          controlsTopMarginX: "15px",
          controlsTopMarginY: "10px",
        },
        radii: {
          containerBorderRadius: "0px",
        },
      }}
    />
  );
}

children

Overrides the custom controls for the Player. See the Broadcast default controls for more details on how the ControlsContainer component is used. This can be used alongside renderChildrenOutsideContainer to render the children outside of the aspect ratio container. This is used for custom controls, so children of the Player can use useMediaController without any parent elements.

mediaElementRef

Sets the React callback ref passed to the underlying media element. Useful when integrating with third party tools, or when access to the underlying video element is needed (usually it isn’t!). Simple refs are not supported - only callback refs (which will be called when the underlying media element is set/updated on initial render).

onPlaybackStatusUpdate

Callback called when the Broadcast store status updates. This should be used with playbackStatusSelector to limit state updates. This allows developers to use the underlying state of the Broadcast component in their UI.

function BroadcastComponent() {
  return (
    <Broadcast
      title="You, Live"
      streamKey="abcd-dcba-1234-4321"
      onPlaybackStatusUpdate={(muted) => console.log(muted)}
      playbackStatusSelector={(state) => state.muted}
    />
  );
}

Technical Details

WebRTC Broadcasting

The Broadcast component uses WebRTC for broadcasting. This always uses STUN/TURN servers for the WebRTC connection, to allow the broadcast to circumvent corporate firewalls and other port blocks. We use the WHIP/WHEP standards for ingest/egress SDP negotiation, so this means that the Broadcast component can be used with any WHIP/WHEP ingest endpoint - not only the providers we have.

Overview

Server-side SDKs

React Components

Usage

Configuration

streamKey

title

showTitle

displayMediaOptions

aspectRatio

controls

muted

objectFit

showPipButton

theme

children

mediaElementRef

onPlaybackStatusUpdate

Technical Details

WebRTC Broadcasting

​Usage

​Configuration

​streamKey

​title

​showTitle

​displayMediaOptions

​aspectRatio

​controls

​muted

​objectFit

​showPipButton

​theme

​children

​mediaElementRef

​onPlaybackStatusUpdate

​Technical Details

​WebRTC Broadcasting

Usage

Configuration

streamKey

title

showTitle

displayMediaOptions

aspectRatio

controls

muted

objectFit

showPipButton

theme

children

mediaElementRef

onPlaybackStatusUpdate

Technical Details

WebRTC Broadcasting