> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcast

> The Broadcast component provides an easy way to livestream video or audio.

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

<Tabs>
  <Tab title="React Native">
    ```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    import { Broadcast } from '@livepeer/react';
    ```

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

    ```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    import { Broadcast } from '@livepeer/react';

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

  <Tab title="React Native">
    React Native is not supported yet.
  </Tab>
</Tabs>

## Configuration

### streamKey

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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](https://web.dev/semantics-aria/) in the Broadcast. If you
do not want to show the title visually, see [`showTitle`](#showtitle).

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
function BroadcastComponent() {
  return <Broadcast title="You, Live" streamKey="abcd-dcba-1234-4321" />;
}
```

### showTitle

Enables/disables the title component.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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`](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints)
which are passed to the browser to limit the sources available to the user.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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](https://web.dev/cls/)). Defaults to `16to9`.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
function BroadcastComponent() {
  return <Broadcast title="You, Live" streamKey="abcd-dcba-1234-4321" muted />;
}
```

### objectFit

Sets the video's
[object fit](https://developer.mozilla.org/en-US/docs/Web/CSS/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.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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](#children) for an example on how to use the
underlying `<PictureInPictureButton />`.

<Info>
  We support both the [w3c](https://w3c.github.io/picture-in-picture/) standard
  (which most modern browsers support), as well as the [older Safari/iOS
  spec](https://developer.apple.com/documentation/webkitjs/adding_picture_in_picture_to_your_safari_media_controls).
  See the browsers which support Picture-in-Picture on
  [caniuse](https://caniuse.com/picture-in-picture).
</Info>

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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`](/sdks/react/migration/3.x/LivepeerConfig) for any global app
styles, and the `theme` prop to override those styles on a per-Broadcast basis.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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](https://github.com/livepeer/react/blob/main/packages/react/src/components/media/Broadcast.tsx)
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`](https://reactjs.org/docs/refs-and-the-dom.html#callback-refs)
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.

```tsx theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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.