Livestreaming

In this guide, we’re going to see how we can watch a livestream using Stream Video’s React SDK. We will also show you how to implement other common livestream features, such as displaying the number of watchers, how to allow users to wait before the livestream started, handle different states and much more.

Watching a livestream

In this guide we will see how to watch a WebRTC livestream. We also support HLS and RTMP-out.

Let’s do a quick overview of these three technologies:

• WebRTC is ideal for real-time, low-latency streaming such as video calls or live auctions.
• HLS (HTTP Live Streaming) is great for large-scale distribution, offering broad compatibility and adaptive bitrate streaming. However, it typically has higher latency (5–30 seconds), making it less suitable for interactive use cases.
• RTMP (Real-Time Messaging Protocol) was once the standard for low-latency streaming to platforms like YouTube or Twitch. While it’s being phased out in favor of newer protocols, it’s still commonly used for ingesting streams due to its reliability and low latency (~2–5 seconds).

We will show you how to watch the WebRTC livestream and implement some common livestreaming features.

We also offer a default component, LivestreamPlayer, that comes with a predefined UI, in case it fits your use-case.

Integrating the default livestream player is very simple, you just need the call type and id:

import { LivestreamPlayer } from "@stream-io/video-react-sdk";

// Use the component in your app
<LivestreamPlayer callType="livestream" callId="your_call_id" />;

The rest of the guide will be focused on building your own livestream player view.

Livestream states

A livestream can be in different states, which your UI needs to handle appropriately:

• Backstage - The livestream is created but not yet started
• Live - The livestream is active and viewers can watch
• Ended - The livestream has finished

The React SDK provides hooks to detect these states:

import { useCallStateHooks } from "@stream-io/video-react-sdk";

const LivestreamContent = () => {
  const { useCallEndedAt, useIsCallLive } = useCallStateHooks();
  const endedAt = useCallEndedAt();
  const isLive = useIsCallLive();

  return (
    <View>
      {!isLive && <Backstage />}
      {endedAt != null && <CallEnded />}
      {endedAt == null && <CallLiveContent />}
    </View>
  );
};

This won’t compile for now, since we also need to define the child components.

First, let’s describe the different states:

• When isLive is false, the call is still not started (it’s in backstage). By default, only hosts with the capability join-backstage can join a call in this state. You can also override the join_ahead_time_seconds setting to allow any user to join the livestream before it’s started.
• If endedAt is not null, it means that the livestream has already finished.
• If it’s not ended or in backstage, then the livestream is live. In this state, we will show the host’s video and other relevant data.

Backstage mode

While in backstage, you can show a countdown, or the start date. By listening to the useIsCallLive hook from useCallStateHooks, you can also automatically render the video track as soon as it’s available.

Here’s an example on how to handle the backstage mode, by showing the start date and the number of participants that are waiting to join the livestream:

import React from "react";
import { useCallStateHooks } from "@stream-io/video-react-sdk";

export const Backstage = () => {
  const { useCallSession, useCallStartsAt } = useCallStateHooks();
  const startsAt = useCallStartsAt();
  const session = useCallSession();

  // viewers who have joined the call before it went live
  const waitingCount = session?.participants_count_by_role["user"] ?? 0;

  return (
    <div className="backstage">
      {startsAt ? (
        <div className="starts-at">
          Livestream starting at {new Date(startsAt).toLocaleDateString()}
        </div>
      ) : (
        <div className="starts-at">Livestream starting soon</div>
      )}

      {waitingCount > 0 && (
        <div className="waiting-count">{waitingCount} viewers waiting</div>
      )}
    </div>
  );
};

Call Ended

When a livestream has ended, its endedAt property is updated with the date and time when the livestream has finished. You can use this to show a message to the users, and additionally show them recordings of the call, if available.

import type { CallRecording } from "@stream-io/video-react-sdk";

export const CallEnded = () => {
  const call = useCall();
  const [recordings, setRecordings] = useState<CallRecording[]>([]);

  useEffect(() => {
    let cancel = false;

    call.queryRecordings(call.state.session?.id).then(({ recordings }) => {
      if (!cancel) {
        setRecordings((prev) => [...prev, ...recordings]);
      }
    });

    const unsubscribe = call.on("call.recording_ready", (event) => {
      setRecordings((prev) => [...prev, event.call_recording]);
    });

    return () => {
      cancel = true;
      unsubscribe();
      setRecordings([]);
    };
  }, [call]);

  return (
    <div className="call-ended">
      <h2>The livestream has ended</h2>

      {recordings.length > 0 && (
        <>
          <h3>Watch recordings</h3>
          <ul>
            {recoridngs.map((recording) => {
              <a key={recording.start_time} href={recording.url}>
                {recording.start_time} - {recording.end_time}
              </a>;
            })}
          </ul>
        </>
      )}
    </div>
  );
};

Call Live View

Let’s provide an example implementation for the component used when the livestream is active. As shown in LivestreamContent above, this state is represented by the CallLiveContent component:

import React, { useEffect, useState } from "react";
import { useCallStateHooks, ParticipantView } from "@stream-io/video-react-sdk";

export const CallLiveContent = () => {
  const { useParticipants, useCallSession } = useCallStateHooks();
  const participants = useParticipants();
  const host = participant.find((p) => p.roles.includes("host"));

  const session = useCallSession();
  const [duration, setDuration] = useState(() => {
    if (!session || !session.live_started_at) {
      return 0;
    }
    const liveStartTime = new Date(session.live_started_at);
    return Math.floor((Date.now() - liveStartTime.getTime()) / 1000);
  });

  const viewerCount = session?.participants_count_by_role["user"] ?? 0;

  const formatDuration = (durationInMs: number) => {
    const durationInSeconds = Math.floor(durationInMs / 1000);
    const minutes = Math.floor(durationInSeconds / 60);
    const seconds = durationInSeconds % 60;
    return `${minutes}:${seconds.padStart(2, "0")}`;
  };

  useEffect(() => {
    const handle = setInterval(() => {
      setDuration((d) => d + 1);
    }, 1000);

    return () => {
      clearInterval(handle);
    };
  }, []);

  return (
    <div className="live">
      {host && <ParticipantView participant={host} trackType={"videoTrack"} />}
      <div className="duration">{formatDuration(duration)}</div>
      <div className="viewer-count">{viewerCount} viewers</div>
    </div>
  );
};

Next, let’s break down the implementation details of the code snippet above.

Rendering the livestream track

Finding and rendering the participant whose video track is shown depends on your use-case - whether it supports only one streamer, whether you want to limit this functionality by role or you have any other special requirements. In the example above, we’re trying to find a user with the host role.

This example uses our ParticipantView component for rendering the host participant.

Livestream Information

You can show various information about the livestream, such as the duration and the participant count:

• To calculate the total participant count (including anonymous users):

const { useParticipants, useAnonymousParticipantCount } = useCallStateHooks();
const participants = useParticipants();
const anonymousParticipantCount = useAnonymousParticipantCount();
const totalParticipantCount = participants.length + anonymousParticipantCount;

• Frequently, the call duration is also presented in a livestream. This information can be calculated from the call session using the useCallSession(), as you can see in the CallLiveContent snippet above.

You can also watch queried calls, as explained here. This allows you to present participant count (and other call data), even without joining a call.

Error states

Livestreaming depends on many factors, such as the network conditions on both the user publishing the stream, as well as the viewers.

A proper error handling is needed, to be transparent to the potential issues the user might be facing.

When the network drops, the SDK tries to reconnect the user to the call. However, if it fails to do that, the callingState in the CallState becomes RECONNECTING_FAILED. This gives you the chance to show an alert to the user and provide some custom handling (e.g. a message to check the network connection and try again).

Here’s an example how to do that:

const ConnectionStatus = () => {
  const { useCallCallingState } = useCallStateHooks();
  const callingState = useCallCallingState();

  let statusMessage;

  switch (callingState) {
    case CallingState.RECONNECTING:
      statusMessage = "Reconnecting, please wait";
      break;
    case CallingState.RECONNECTING_FAILED:
      statusMessage = "Cannot join livestream. Try again later";
      break;
    case CallingState.OFFLINE:
      statusMessage = "You are disconnected";
      break;
    default:
      statusMessage = "A connection error occurred";
  }

  return <>{statusMessage}</>;
};