Integrate captions into your HLS stream
Add HLS subtitle playlists to your master manifest
CaptionHub Live can produce a HLS manifest file 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 CaptionHub.
Understand the structure of a master playlist
A typical HLS master 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 master playlist (master.m3u8) 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 master 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="https://cdn.captionhub.com/live/public/<PROJECT_ID>/live-captions.m3u8?language=EN-US"
- 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, like
https://cdn.captionhub.com/live/public/<PROJECT_ID>/live-captions.m3u8?language=EN-US
Here’s an example of a master playlist (master.m3u8) 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="https://cdn.captionhub.com/live/public/<PROJECT_ID>/live-captions.m3u8?language=EN-US"
Obtaining the subtitle playlist URLs
Once you’ve created a project in CaptionHub, you can find the playlist URLs under “HLS integration”.
