This document intends to describe how to use the HLSSubscriber client included with the SDK to playback HLS content native in a browser (currently only available in Mobile and Desktop Safari).

HLS content playback from Red5 is still supported in browser with non-native HLS support by using a 3rd-Party HLS library. We recommend using HLS.js.

• HLSSubscriber
  • Usage
  • Init Configuration
  • Events

HLSSubscriber

The HLSSubscriber available from the SDK provides an easy way to setup HLS playback of a stream from Red5 in a browser that supports native HLS playback (i.e., Mobile and Desktop Safari).

Usage

The follow example demonstrates the usage of HLSSubscriber from the SDK loaded in a browser as a script dependency. The example is easily transferrable to one in which the SDK is loaded as a module – either through NPM dependency – or as a script declaration – using import.

Cloud Red5 Server

If your app is targeting a Cloud-based deployment of Red5 Server (such as from https://cloud.red5.net) you will need to rely on remote storage for live and VOD HLS stream content. This could be a storage bucket in a cloud environment or an NFS mount.

Such storage parameters can be set in your Red5 Cloud deployment if using https://cloud.red5.net or refer to the NFS documentation from our site.

Because of Cross-Origin policies in browsers, you will not be able to load HLS files that would reside in an Origin node served over HTTP. As such, you will need to know the remote location of the HLS manifest (.m3u8) file and provide the full URL as the endpoint value of the init configuration:

...
<video id="red5pro-subscriber" controls autoplay playsinline></video>
...

const { HLSSubscriber } = red5prosdk;

const startHLSSubscriber = async () => {
  try {
    const subscriber = new HLSSubscriber();
    await subscriber.init({
      endpoint:
        "https://nfs.myred5-deployment.cloud.red5.net/live/mystream.m3u8",
      streamName: "mystream",
    });
    await subscriber.subscribe();
  } catch (error) {
    // Handle error.
    // Most likely due to non-native HLS Playback support in browser.
    // Integration with 3rd-Party library - such as HLS.js - is recommended in such a scenario.
  }
};

startHLSSubscriber();

Standalone Red5 Server

If your app is targeting a standalone self-deployed version of the Red5 Server, the following example demonstrates native playback of HLS using HLSSubscriber:

...
<video id="red5pro-subscriber" controls autoplay playsinline></video>
...

const { HLSSubscriber } = red5prosdk;

const startHLSSubscriber = async () => {
  try {
    const subscriber = new HLSSubscriber();
    subscriber.on("*", (event) => {
      const { type, data } = event;
      console.log(type, data);
    });
    await subscriber.init({
      protocol: "https",
      port: 443,
      host: "my-red5-server.com",
      streamName: "mystream",
    });
    await subscriber.subscribe();
  } catch (error) {
    // Handle error.
    // Most likely due to non-native HLS Playback support in browser.
    // Integration with 3rd-Party library - such as HLS.js - is recommended in such a scenario.
  }
};

startHLSSubscriber();

Init Configuration

The following are the available properties that can be defined in the init configuration provided to the HLSSubscriber client:

Events

The following describe the various events that can be listened for on the HLSSubscriber and enumerated on the SubscriberEventTypes object:

Listening for Events

The HLSSubscriber included in the SDK is an event emitter that provides a basic API to subscribe and unsubscribe to events either by name or by wildcard.

To subscribe to all events from a subscriber:

const handleSubscriberEvent = (event) => {
  // The name of the event:
  const { type } = event;
  // The dispatching subscriber instance:
  const { subscriber } = event;
  // Optional data releated to the event (not available on all events):
  const { data } = event;
};

const subscriber = new HLSSubscriber();
subscriber.on("*", handleSubscriberEvent);

The * type assignment is considered a “Wildcard” subscription – all events being issued by the subscriber instance will invoke the assign event handler.

To unsubscribe to all events from a subscriber after assinging an event handler:

subscriber.off("*", handleSubscriberEvent);

The following sections of this document describe the event types that can also be listened to directly, instead of using the * wildcard.