Transmitting subtitles for HLS live internet streams

This page describes how FAB Subtitler BCAST can transmit subtitles for HLS internet live streams.

Introduction to transmitting subtitles for live internet streams

FAB Subtitler BCAST can generate data that is necessary in order to add subtitles to the internet video/audio streams in HLS format. FAB Subtitler monitors the video .m3u8 playlist from the video encoder and the video chunks and generates the subtitle .m3u8 playlist and the subtitle chunks which are then distributed through a CDN in the same way as video/audio and the master playlist. The master playlist has to be modified in a way that it includes additional data necessary in order for the players to be able to identify and display the subtitles.

The following diagram shows the system design:

FAB Subtitler is monitoring the video HLS playlist and is generating the subtitle playlist and subtitle chunks in real time. Those chunks and playlist for subtitles are then distributed preferably through the same CDN where video and audio are distributed.

FAB Subtitler BCAST can monitor the video playlist in two ways:

  • Solution 1 (PUSH MODE): By accepting the playlist.m3u8 and video chunks over http which are POSTed by a video encoder to the IP address of FAB Subtitler
  • Solution 2 (PULL MODE): By downloading the playlist.m3u8 and video chunks from an URL

Configuration of FAB Subtitler BCAST

To activate real time generation of subtitle HLS playlist and chunks, one HLS Live Streaming output has to be added in the System/Network part of the configuration of FAB Subtitler BCAST for every video stream as can be seen on the following picture:

The configuration of HLS Live Streaming output is shown on the following picture:

  • For solution 1 (PUSH MODE): accepting the playlist.m3u8 and video chunks over http POSTed by a video encoder

  • For solution 1 (PULL MODE): downloading the playlist.m3u8 and video chunks

“Video playlist URL” is the URL that the FAB Subtitler will use to fetch the video playlist. This should not be the master playlist, but should be the video playlist with the lowest bitrate. FAB subtitler requires unencripted video, so a playlist without DRM has to be specified here. If necessary, an additional non-DRM output has to be configured on the HLS encoder that would only be accessible for the FAB Subtitler but not from other networks.

One possibility to find the correct video playlist is to look for it in the master playlist:

Look for the one with the smallest bandwidth value or for the one with the smallest resolution if the bandwidth is not specified. Use the URL path of the master playlist and append the name of the video playlist as shown in the example above. Instead of using direct link to the playlist you might consider using another link that would enable you to direct the request to the correct HLS encoder.

“Delay” is the time the subtitles will be delayed after FAB Subtitler receives them. Normally this delay is necessary to compensate for the video/audio delay in the encoding path. The best is to start with a delay of above 10 seconds (10000 ms). Then observe the subtitle offset to the correct position and correct the delay value in the FAB subtitler configuration accordingly.

“URL suffix for subtitle playlist” is a string that will be appended to the URL on the host on which FAB Subtitler is running. The full resulting URL is displayed next to the entry field. Subtitle playlist and chunks are accessible through that URL.

“Subtitle format” can be TTML- Timed Text XML or WebVTT (.m4s) or WebVTT (.webvtt). All formats are supported by most HLS players.

“Timed text format TTML” enables you to select which type of TTML you would like to use. Not all HLS players support all TTML features so depending on the players used, you might have to use a different TTML type.

“Remove tt namespace”: The EBU has specified that tt namespace shall be used for EBU-TT compliant TTML subtitles. There are almost no players that support using namespace, so you might consider removing tt namespace from the TTML used.

FAB Subtitler can publish the subtitle playlist and subtitle chunks in the following ways:

  • Push subtitles using HTTP(s) POST/PUT ta a configurable URL
  • Push subtitles using file copy to a network folder
  • Only make subtitles available over internal web server so that they can be downloaded

Please note that FAB Subtitler will synchronize files on the network folder with locally produced subtitle playlist and chunks. Therefore all files starting with subt will be deleted on the destination.

Adapting the master playlist

There are some additional entries that have to be added to the master playlist in order to enable the players to find and display subtitles. If you are not able to modify the master playlist that is coming from the HLS encoder, just make a copy of that master playlist, modify that one and let the players use that one instead of the one that is generated by the HLS encoder.

In the following picture the necessary modifications are marked yellow:

The #EXT-X-VERSION should be at least 6.

It’s recommended to include the line #EXT-X-INDEPENDENT-SEGMENTS.

There should be one line #EXT-X-MEDIA:TYPE=SUBTITLES… for each subtitling language or type. Set name and language as required. The URI should point to the place where the subtitle playlist and chunks are accessible from the outside. Normally this URI will point to CDN.

For each video stream add ,stpp.ttml.im1t in the CODECS list. At the end of the line append ,SUBTITLES=“subs”

Checklist for setting up subtitles for HLS live stream

  • Decide whether you will use solution 1 (PUSH MODE) or solution 2 (PULL MODE)
  • Define the URL where FAB Subtitler must push the m3u8 playlist and chunks with subtitles
  • Configure FAB Subtitler as described above
  • For solution 1 configure the HLS live streaming encoder to push the m3u8 playlist and video chunks to the IP/URL of FAB Subtitler
  • For solution 2 configure the correct PULL URL for the m3u8 playlist and video chunks
  • Adapt the master playlist to include subtitles so that the player will display them
  • Run the HLS live stream and FAB Subtitler to transmit subtitles and check if the player displays them correctly.

This page was last updated on 2023-05-09