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

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

import { Broadcast } from '@livepeer/react';
 
function BroadcastComponent() {
  return (
    <Broadcast
      streamKey="abcd-dcba-1234-4321"
    />
  );
};

Demo

You can try the in-browser broadcasting below - see how easy it is to go live!

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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab)). 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 (opens in a new tab) 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 />.

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 (opens in a new tab) 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 (opens in a new tab) 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.