Watching a Livestream

This guide demonstrates how to build advanced UIs for watching livestreams in your Flutter applications using Stream's Video SDK.

Overview

Stream's Video SDK supports two methods for watching livestreams:

1. HLS (HTTP Live Streaming) - enables reliable large-scale broadcasting with broad device compatibility and adaptive quality. While it has higher latency (5-30 seconds), it excels at reaching large audiences with stable playback
2. WebRTC - provides ultra-low latency streaming (sub-second) - perfect for interactive experiences like live auctions or Q&As where real-time engagement is critical

HLS Streaming

We can then obtain the HLS URL by querying the hlsPlaylistURL from call.state:

final url = call.state.value.egress.hlsPlaylistUrl;

To view HLS streaming with quality selection and playback controls, we recommend using the lecle_yoyo_player package.

WebRTC Streaming

For WebRTC livestreams, you can either:

• Use our pre-built LivestreamPlayer component
• Create your own custom implementation

Using the LivestreamPlayer

Our LivestreamPlayer widget provides a complete livestreaming experience with these built-in features:

• Live indicator showing when the stream is active
• Real-time livestream duration display
• Viewer/participant counter
• Full-screen mode toggle
• Multiple hosts support with configurable layouts
• Screen sharing with spotlight or grid mode
• Handling various livestream states (backstage, ended, not connected, reconnecting)
• Recordings list displayed when the livestream has ended
• Picture-in-picture support

Basic Implementation

To use the LivestreamPlayer, simply provide a Call instance:

LivestreamPlayer(call: call);

Join Behaviour

The LivestreamPlayer supports three join behaviours via the joinBehaviour property:

Customization Options

The LivestreamPlayer supports extensive customization:

Minimal Player Example

To create a minimal player without the default controls panel:

LivestreamPlayer(
  call: call,
  startInFullscreenMode: true,
  livestreamControlsWidgetBuilder: (context, call) => const SizedBox.shrink(),
)

This configuration preserves the built-in handling of backstage mode and ended states, while hiding the default controls panel. This gives you complete flexibility to build custom controls and overlays on top of the video player.

Multiple Hosts

To display multiple hosts in a grid layout:

LivestreamPlayer(
  call: call,
  showMultipleHosts: true,
  layoutMode: ParticipantLayoutMode.grid,
);

When showMultipleHosts is false (the default), only the first streaming participant is shown.

You can also provide a custom filter to select which participants are treated as hosts:

LivestreamPlayer(
  call: call,
  showMultipleHosts: true,
  livestreamHostsParticipantsFilter: (participants) {
    return participants.where((p) => p.roles.contains('host')).toList();
  },
);

Screen Sharing

The LivestreamPlayer supports screen sharing with two display modes:

• LivestreamScreenShareMode.spotlight (default) — the screen share is displayed as a separate spotlight view
• LivestreamScreenShareMode.grid — the screen share replaces the host's video in the grid layout

LivestreamPlayer(
  call: call,
  showMultipleHosts: true,
  screenShareMode: LivestreamScreenShareMode.spotlight,
);

Handling Livestream States

The LivestreamPlayer handles several connection and lifecycle states. You can customize the UI for each:

LivestreamPlayer(
  call: call,
  livestreamBackstageWidgetBuilder: (context, call) {
    return const Center(child: Text('The host is preparing. Stay tuned!'));
  },
  livestreamEndedWidgetBuilder: (context, call) {
    return const Center(child: Text('This livestream has ended.'));
  },
  livestreamNotConnectedBuilder: (context, properties) {
    if (properties.isReconnecting) {
      return const Center(child: Text('Reconnecting...'));
    }
    return const Center(child: CircularProgressIndicator());
  },
  livestreamHostsUnavailableBuilder: (context, properties) {
    return const Center(child: Text('Waiting for a host to start streaming...'));
  },
);

Building a Custom Livestream Player

You can create your own livestream player component for complete control. Use PartialCallStateBuilder for efficient state-driven UI that only rebuilds when the specific state you observe changes:

@override
Widget build(BuildContext context) {
  return SafeArea(
    child: PartialCallStateBuilder(
      call: _call,
      selector: (state) => (
        isBackstage: state.isBackstage,
        hasEnded: state.endedAt != null,
      ),
      builder: (context, data) {
        if (data.hasEnded) {
          return const Center(child: Text('Livestream has ended'));
        }

        if (data.isBackstage) {
          return const Center(
            child: Text('Host is backstage. Stream will begin soon.'),
          );
        }

        return _buildLivestreamContent(context);
      },
    ),
  );
}

Accessing Livestream Tracks

To render the actual livestream video, you need to have access to the livestream track (or tracks).

If there is only one video track (you only have one person livestreaming), you can get it with the following code:

final streamingParticipant =
          callState.callParticipants.firstWhere((e) => e.isVideoEnabled);

If you have multiple hosts that are livestreaming, and you want to show them all, you can fetch the hosts by role:

final streamingParticipants = callState.callParticipants
    .where((p) => p.roles.contains('host'))
    .toList();

To render the video track you can use our StreamCallParticipant widget:

StreamCallParticipant(
  key: ValueKey(participant.uniqueParticipantKey),
  call: call,
  participant: streamingParticipant,
  showConnectionQualityIndicator: false,
  showParticipantLabel: false,
  showSpeakerBorder: false,
)

Additional Resources

For more Video SDK examples, check out our Flutter Cookbook samples on GitHub.