# 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](https://developer.mozilla.org/en-US/docs/Web/API/MediaSource) API must be available in the browser, except on the iOS, macOS, and iPadOS platforms, which offer native HLS support.

Info
* **HLS** refers to the HTTP Live Streaming protocol in our documentation, while `hls` denotes the library and API namespace.
* Other examples of loader plugins include the [MPEG-DASH](http://localhost:3000/docs/wowza-flowplayer/plugins/mpeg-dash/) and [RTS](http://localhost:3000/docs/wowza-flowplayer/plugins/rts/) plugins. The [Wowza Video Platform Integration](/docs/wowza-flowplayer/plugins/wowza-video-platform-integration/) and [Playlist](/docs/wowza-flowplayer/plugins/playlist/) plugins are also considered loader plugins since they're responsible for setting the player's source. However, they don't control media playback.


## Before you start

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

* Read about [embedding the core player](/docs/wowza-flowplayer/player/embed/embed-with-standalone/) in your site by adding the minimum CSS and JavaScript player components.
* Make sure you have a player token. For more, see [Token configuration](/docs/wowza-flowplayer/player/configure/#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](/docs/wowza-flowplayer/player/embed/embed-with-standalone/#use-npm) or our [TypeScript guide](/docs/wowza-flowplayer/guides/add-the-player-using-typescript/).


## Install the plugin

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


```html
<!-- 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>
```


```js
// 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

embed
## 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.

| Property | Description |
|  --- | --- |
| `native` *boolean* | A `false` value (default) forces the use of hls.js for HLS streaming instead of the browser's native implementation. With `true`, you can take advantage of the browser's native HLS implementation if the browser supports it (for example, in Safari). Playback isn't prevented in cases where hls.js is loaded and native HLS is not implemented by the browser. |
| `adaptive_buffer_control` *boolean* *object* | The default boolean value for this property is `false`, which disables adaptive buffering for how much video data is preloaded into the playback buffer based on network conditions. If set to `true`, adaptive buffering is enabled and playback starts with a smaller buffer, using the default values for `initial_buffer_length` (10 seconds) and `restore_buffer_player_time_threshold` (10 seconds). When set to an object, you can customize values for the `initial_buffer_length` and `restore_buffer_player_time_threshold` properties: `initial_buffer_length`(number) - Defines the initial buffer length at startup in seconds. Default value is **10** seconds.`restore_buffer_player_time_threshold` (number) - Defines the threshold value in seconds to determine when the buffer length is restored. The default value is **10** seconds. Once playback passes this threshold, the buffer is restored to the default `maxBufferLength` set by the hls.js library.For more, see this [configuration example](/docs/wowza-flowplayer/plugins/hls/#examples). |


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.

Info
* Using the browser's native HLS implementation disables manual quality selection and any custom hls.js API settings.
* Some older browsers, such as Safari on iOS, may not support the MSE API. In those cases, you will automatically switch to the native browser HLS experience. This means you may lose some features and the ability to get details about the underlying stream. The Quality Selection plugin is not available in that context.
* When debug mode `(hls: { debug: true })` is enabled to log internal activity and errors, hls.js disables exception handling in event callbacks. Uncaught errors in these callbacks stop the affected event from running and may interrupt playback.


#### 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. The `adaptive_buffer_control` object applies custom adaptive buffer settings to dynamically adjust how much video data is preloaded into the playback buffer.


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

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.


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


```js
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](/docs/wowza-flowplayer/plugins/about-plugins/#plugin-events).

| CDN event | npm event | Description |
|  --- | --- | --- |
| `flowplayer.hls.events.ATTACHED` | `HLS.events.ATTACHED` | Fires when the hls.js library attaches to the `<video>` element, allowing it to handle HLS playback. |


info
This event is not available in native HLS implementations, such as those on iOS.

#### 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.


```js
// 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);
  });
});
```


```js
// 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);
  });
});
```