# HTML Subtitles plugin

The HTML Subtitles plugin allows the display of styled WebVTT subtitles in Wowza Flowplayer. When you configure this plugin, you can include numerous tracks to display subtitles in different languages.

With version 3.10.0 of the player, we also added plugin enhancements to improve accessibility for a broader audience. The player includes out-of-the-box functionality to allow viewers to adjust various subtitle options, such as font size, font family, font color, and font opacity. Additionally, background color and opacity, as well as character edge styling can be managed from the player's user interface.

You can play the following video to see the HTML Subtitles plugin in action. You can also view this demo.

video
source
info
Subtitle settings are saved in each site's `localStorage` browser property. Therefore, viewers using non-incognito mode get the same settings for all site videos until the local storage is cleared.

## Supported formats

This plugin supports [webVTT](https://en.wikipedia.org/wiki/WebVTT) text track files as well as embedded WebVTT in an HLS m3u8 manifest, plus CEA-608 and SCTE embedded captions. For all embedded types, you do not need to configure the `tracks` object. All configuration comes from the stream. This also means you cannot override the label or default.

Info
* Support for embedded captions in native HLS implementations may vary.
* SRT subtitles are not officially supported by the HTML5 `<video>` standard. Please use one of the converters listed in the [More resources](#more-resources) section to convert to WebVTT.


## 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 HTML Subtitles 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 subtitles plugin -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/subtitles.min.js"></script>
<!-- Load playlist plugin if you need subtitles in playlists-->
<script src="//cdn.flowplayer.com/releases/native/3/stable/3/plugins/playlist.min.js"></script>
```


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

// Import plugins
// Import playlist plugin if you need subtitles in playlists
import Subtitles from "@flowplayer/player/plugins/subtitles";
import Playlist from "@flowplayer/player/plugins/playlist";
```

## Add HTML elements

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


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

## Configure the plugin

Subtitles are configured using the player-level `subtitles` object and the `tracks` child object, which can contain multiple subtitle tracks in different languages. You can also include the [Playlist plugin](/docs/wowza-flowplayer/plugins/playlist/) and initialize your player instance with a playlist while specifying a `src` property that defines the URL for each video and subtitle file.

### Subtitle properties

| Property | Description |
|  --- | --- |
| `native`*boolean* | Default value is `false`. Required only if using WebVTT inline styles. When set to `true`, enables native rendering of subtitles by the browser. Helpful when injecting CSS rules or defining subtitle styles directly in WebVTT files. |
| `show` *boolean* | Disables existing subtitles with `subtitles: {show: false}`. |
| `tracks` *array* | Required for side-loaded WebVTT files. Contains one or multiple track source objects with the properties from the [Track options](/docs/wowza-flowplayer/plugins/html-subtitles/#track-properties) table. |


### Track properties

| Property | Description |
|  --- | --- |
| `crossorigin`*string* | Adds a `crossorigin` attribute to the  element. Possible values include `use-credentials` and `anonymous`. |
| `default`*boolean* | Defines which track to show as default, one per `tracks` array. If set, this track will be on at player start. |
| `id`*string* | Specifies ID of the subtitle. |
| `kind`*string* | Identifies the kind of subtitles. Possible values are `captions`, `subtitles`, or `descriptions`. |
| `label`*string* | Required. Determines label to show in the menu. |
| `lang`*string* | Identifies the language of the subtitle (two-letter BCP47 code). |
| `src`*string* | Required. Specifies the WebVTT file url. |


#### Example without Playlist plugin

The following example initializes the player with a video source and adds subtitle tracks for English, Swedish, and Russian. The source files for the subtitles are public WebVTT files. It requires that the MPEG-DASH and Subtitles plugin are enabled. For more, see this demo in our Wowza Flowplayer sandbox.


```js
const player = flowplayer("#player",
  {
    src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4",
    token: "[your-player-token]",
    subtitles: {
      // Add an array of subtitle tracks in different languages
      tracks: [
        {
          src: "https://raw.githubusercontent.com/videojs/video.js/refs/heads/main/docs/examples/elephantsdream/captions.en.vtt",
          label: "English",
          id: "English-en",
          default: true,
          crossorigin: "anonymous"
        },
        {
          src: "https://raw.githubusercontent.com/videojs/video.js/refs/heads/main/docs/examples/elephantsdream/captions.sv.vtt",
          label: "Swedish",
          id: "Swedish-sv",
          default : false,
          crossorigin: "anonymous"
        },
        {
          src: "https://raw.githubusercontent.com/videojs/video.js/refs/heads/main/docs/examples/elephantsdream/captions.ru.vtt",
          label: "Russian",
          id: "Russian-ru",
          default : false,
          crossorigin: "anonymous"
        }
      ]
    }
});
```

#### Example with Playlist plugin

The following example initializes the player with a playlist of videos that contain subtitle tracks or various languages. The source files for the subtitles are public WebVTT files. IT requires that the MPEG-DASH, Subtitles, and Playlist plugins are enabled. For more, see this demo in our Wowza Flowplayer sandbox.


```js
const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: {
    type: "flowplayer/playlist",
    items: [
      {
        src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4",
        title: "Elephants Dream",
        subtitles: {
          tracks: [
            {
              src: "https://raw.githubusercontent.com/videojs/video.js/refs/heads/main/docs/examples/elephantsdream/captions.en.vtt",
              label: "English",
              default: true
            },
            {
              src: "https://raw.githubusercontent.com/videojs/video.js/refs/heads/main/docs/examples/elephantsdream/captions.sv.vtt",
              label: "Swedish",
              default: false
            }
          ]
        }
      },
      {
        src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/Sintel.mp4",
        title: "Sintel",
        subtitles: {
          tracks: [
            {
              src: "https://raw.githubusercontent.com/elyseko/web-vtt-example/refs/heads/master/src/captions/sintel-en-us.vtt",
              label: "English",
              default: true
            },
            {
              src: "https://raw.githubusercontent.com/elyseko/web-vtt-example/refs/heads/master/src/captions/sintel-fr.vtt",
              label: "French",
              default: false
            }
          ]
        }
      }
    ]
  }
});
```

## Check the generated HTML

When the subtitles render in the player, the HTML consists of three main components:

* An external wrapper `<div>` with the class `.fp-captions`.
* An internal `<pre>` with the class `.fp-cue`.
* The html from the `VTTCue` which is dependent on the browser's implementation of [`getCueAsHTML()`](https://w3c.github.io/webvtt/#dom-vttcue-getcueashtml).


This is a raw HTML example:


```html
<div class="fp-captions">
  <pre class="fp-cue">
    Todo mundo quer mais da vida ..
    Esta é uma segunda linha
    E um terceiro
  </pre>
</div>
```

With player versions before version 3.10.0, you must style the subtitles with custom CSS:


```css
/* make the subtitles bigger, fonts full black on a white background */
.fp-captions .fp-cue {font-size: 2em; color: black; background-color: white;}
```

## Listen to plugin events

This section describes the events you can capture to control and manage subtitles within your player instance. 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.subtitles.events.TRACK_UPDATED` | `Subtitles.events.TRACK_UPDATED` | Emitted when a different track is selected from the menu and loaded by the player. Returns the `textTrack` which was selected. Empty if subtitles are disabled in the menu. Introduced with v3.4.1 of the player. |


info
There are two additional events that are bound to the subtitles menu web component and emitted when new text tracks are added to the menu or selected. For more, see [Web components subtitle events](/docs/wowza-flowplayer/player/web-components/component-events#subtitles-menu).

#### Example

The following example uses the `TRACK_UPDATED` event to capture when a different subtitle track is selected from the captions menu. It outputs the value of the selected track in the console.


```js
player.on(flowplayer.subtitles.events.TRACK_UPDATED, (event) => {
  console.log("Track updated to", event.detail.id)
});
```


```js
player.on(Subtitles.events.TRACK_UPDATED, (event) => {
  console.log("Track updated to", event.detail.id)
});
```

## More resources

Below is a list of useful resources to learn about, create, convert, and manage WebVTT subtitles.

#### Specifications and documentation

* [WebVTT EduTech wiki](http://edutechwiki.unige.ch/en/WebVTT)
* [Video subtitling and WebVTT](http://html5doctor.com/video-subtitling-and-webvtt/)
* [Conversion of 608/708 captions to WebVTT](https://dvcs.w3.org/hg/text-tracks/raw-file/default/608toVTT/608toVTT.html)
* [Learning center: Media accessibility information, guidelines, and research](https://dcmp.org/learn/213#CiY_resources)
* [BCP47 language subtag lookup](https://r12a.github.io/app-subtags/)


#### Validator and converter tools

* [Online WebVTT validator](https://quuz.org/webvtt/)
* [Javascript validator tool](https://github.com/annevk/webvtt) (source code)
* [Subtitles tools commercial site](https://subtitletools.com/)
* [Desktop SRT converter tool - CLI](https://github.com/nwoltman/srt-to-vtt-cl) (source code and Windows, macOS binaries)
* [Desktop SRT converter tool - Windows GUI](https://github.com/nwoltman/srt-to-vtt-converter)
* [Windows subtitle editor](https://www.nikse.dk/SubtitleEdit/) (source code)
* [EIA-608 to WebVTT Ruby Gem](https://gitlab.com/pkerling/subconv) (source code)