Self-hosted videos with HLS: subtitles

Vincent Bernat

In a pre­vi­ous ar­ti­cle, I de­scribed a so­lu­tion to self-host videos while of­fer­ing a de­liv­ery adapted to each user’s band­width, thanks to HLS and hls.js. Sub­ti­tles1 were not part of the game. While they can be de­clared in­side the HLS man­i­fest or em­bed­ded into the video, it is eas­ier to in­clude them di­rectly in the <video> el­e­ment, us­ing the WebVTT format:

<video poster="poster.jpg"
       controls preload="none">
  <source src="index.m3u8"
          type="application/vnd.apple.mpegurl">
  <source src="progressive.mp4"
          type='video/mp4; codecs="avc1.4d401f, mp4a.40.2"'>
  <track src="de.vtt"
         kind="subtitles" srclang="de" label="Deutsch">
  <track src="en.vtt"
         kind="subtitles" srclang="en" label="English">
</video>

Watch the fol­low­ing demon­stra­tion, fea­tur­ing Agent 327: Op­er­a­tion Bar­ber­shop, a video cre­ated by Blender An­i­ma­tion Stu­dio and cur­rently re­leased un­der the Cre­ative Com­mons At­tri­bu­tion No De­riv­a­tives 2.0 license:

You may want to jump to 0:12 for the first sub­ti­tle. Most browsers should dis­play a wid­get to tog­gle sub­ti­tles. This works just fine with Chromium but Fire­fox will not show the menu un­til the video starts play­ing, un­less you en­able preload­ing. An­other an­noy­ance: there is no sim­ple way to spec­ify safe mar­gins for sub­ti­tles and they get stuck at the bot­tom. These two is­sues seem mi­nor enough to not war­rant pulling hun­dreds of kilo­bytes of Java­Script for a cus­tom player.

Up­date (2019-12)

If sub­ti­tles are served from an­other do­main, crossorigin="anonymous" at­tribute needs to be added to the <video> tag and sub­ti­tles need to han­dle CORS head­ers. On some browsers, this also en­ables CORS for the video and the poster.

Up­date (2020-09)

The is­sue with Fire­fox and the sub­ti­tle menu is fixed in Fire­fox 76. On An­droid, sub­ti­tles work from Firefox 80.

Up­date (2026-11)

I have switched to Video.js for chap­ters and au­dio track se­lec­tion. Na­tive play­ers still lack them. Video.js is also much smaller than in 2019: the whole player, in­clud­ing its own HLS en­gine, is less than the size of hls.js alone.