Integrate captions into your HLS manifest

Timbra can produce a HLS multivariant playlist with WebVTT captions that you can integrate into your HLS stream. You can follow the steps below to integrate the subtitle tracks into your stream, or use the modified playlist from Timbra.

Understand the structure of a multivariant playlist

A typical HLS multivariant playlist (M3U8) references different media playlists (for different bitrates or resolutions). For example:

#EXTM3U
#EXT-X-VERSION:3

# High-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
high.m3u8

# Medium-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2"
medium.m3u8

# Low-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"
low.m3u8

This multivariant playlist contains multiple video stream options (high, medium, low). You’ll add subtitle references to this file next.

Add EXT-X-MEDIA tags for subtitles

In order to add segmented WebVTT files for subtitles, you need to use the EXT-X-MEDIA tag in your multivariant playlist. This tag allows you to define additional media, such as subtitles or audio tracks.

#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",LANGUAGE="en",AUTOSELECT=YES,DEFAULT=YES,URI="<url>"

TYPE=SUBTITLES: Specifies that this is a subtitle track.
GROUP-ID: A unique identifier for the group of subtitles (e.g., "subs").
NAME: The name of the track as it appears in the player (e.g., "English").
LANGUAGE: The language code (e.g., "en" for English).
AUTOSELECT: If set to YES, the player automatically selects this subtitle track if the user’s language preferences match.
DEFAULT: If set to YES, this track is the default if no other track is selected.
URI: The URL to the playlist for the segmented WebVTT file

Here’s an example of a multivariant playlist with video streams and an added subtitle track:

#EXTM3U
#EXT-X-VERSION:3

# High-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2",SUBTITLES="subs"
high.m3u8

# Medium-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2",SUBTITLES="subs"
medium.m3u8

# Low-quality video stream
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2",SUBTITLES="subs"
low.m3u8

# Subtitle track (English)
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",LANGUAGE="en",AUTOSELECT=YES,DEFAULT=YES,URI="<url-from-captionhub>"

Obtaining the subtitle playlist URLs

Once you’ve created a project in CaptionHub, you can find the playlist URLs on the HLS integration tab, under Add tracks to a HLS playlist.

They are also available via the API via output_details > hls_output > playlist_tracks.