HLS plugin

The HLS plugin consists of an HTTP Live Streaming (HLS) loader plugin capable of playing M3U8 source files. Loader plugins handle the src property of the player configuration, getting the video source into the player's HTML5 <video> element and assisting with playback.

Since most web browsers don't natively support the HLS protocol, the HLS plugin solves this gap. With the help of the hls.js library, the plugin transmuxes MPEG-TS (Transport Stream) segments into the fragmented MP4 (fMP4) format when necessary, then passes these segments directly to the browser for playing via Media Source Extensions (MSE) and the <video> tag.

The HLS plugin has the same caveats as the hls.js library. The MediaSource API must be available in the browser, except on the iOS, macOS, and iPadOS platforms, which offer native HLS support.

Before you start

Before you use this plugin with the standalone player, we recommend the following steps:

• Read about embedding the core player in your site by adding the minimum CSS and JavaScript player components.
• Make sure you have a player token. For more, see Token configuration . Tokens aren't needed for local development.
• The instructions on this page generally assume you're using the Wowza Flowplayer CDN to embed the player in your site. If you're using npm, see our npm instructions or our TypeScript guide .

Install the plugin

To install the HLS plugin, load it next to the core player:

<!-- Load standard player skin -->
<link rel="stylesheet" href="https://cdn.flowplayer.com/releases/native/3/stable/style/flowplayer.css">
<!-- Load player script -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>

<!-- Load plugin -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/hls.min.js"></script>

// Import player library and basic CSS for player
import flowplayer from "@flowplayer/player";
import "@flowplayer/player/flowplayer.css";

// Import plugin
import HLS from "@flowplayer/player/plugins/hls";

Add HTML elements

Add the HTML components to render the player elements on your page:

<div id="player"></div>

Configure the plugin

The plugin can be set up at the top-level configuration under the hls namespace. Configuration properties are listed in this section.

All other configuration properties under the hls namespace are propagated to the hls constructor. When forcing the use of hls.js for HLS streaming, this means you can also pass these hls.js fine-tuning parameters. We also expose all properties and methods of the Hls class and the properties of the HlsConfig object.

Examples

The following code snippet handles the stream with the hls.js library. Setting startLevel: -1 allows hls.js to automatically pick the initial quality level based on the available bandwidth, device capabilities, and other network conditions. With the testBandwidth: true property, a fragment of the lowest level is downloaded to establish a bandwidth estimate before selecting the first auto-level.

const player = flowplayer("#player",
  { 
    src: "//edge.flowplayer.org/bauhaus.m3u8",
    token: "[your-player-token]",
    hls : {
      native: false,
      startLevel: -1,
      testBandwidth: true
    }
  });

When using either of the following code samples, you can add custom functions like XHR headers for signed cookies or custom headers. These code examples only work for devices that support Media Source Extensions and hls.js. Therefore, they won't work during playback on iPhones.

hls: {
  // Send (signed) cookies
  xhrSetup: (xhr) => { xhr.withCredentials = true }
}

hls: {
  // Send custom request headers
  xhrSetup: xhr => {
    xhr.setRequestHeader("id", 1)
    xhr.setRequestHeader("token", 456)
  }
}

Listen to plugin events

This section describes the events you can capture to control and manage your HLS player instance.

We recommend listening to the ATTACHED event handler before you work with the player.hls instance. This guarantees that you can best access the HLS instance and enables you to better manipulate the underlying implementation for custom integrations. To understand event handling differences between CDN or npm implementations, see Plugin events.

Example

The following example sets up an event listener to capture when the HLS.js instance is attached to the media element and the player is ready to handle the stream. Inside the event callback, we log the user configuration and bandwidth estimate. When the user seeks the player, we log the entire event object and the current playback time.

// Listen for the HLS plugin ATTACHED event, triggered when the HLS media is attached to the player
player.on(flowplayer.hls.events.ATTACHED, (ev) => {
  console.log(ev.detail.hls.userConfig);
  console.log(ev.detail.hls.bandwidthEstimate);
   
  // Leverage a core player seeking event
  player.on(flowplayer.events.SEEKING, (ev) => {
    console.log(ev.type, ev);
    console.log(player.currentTime);
  });
});

// Listen for the HLS plugin ATTACHED event, triggered when the HLS media is attached to the player
player.on(HLS.events.ATTACHED, (ev) => {
  console.log(ev.detail.hls.userConfig);
  console.log(ev.detail.hls.bandwidthEstimate);

  // Leverage a core player seeking event
  player.on(flowplayer.events.SEEKING, (ev) => {
    console.log(ev.type, ev);
    console.log(player.currentTime);
  });
});