WebVTT in HTTP Live Streaming

OpenSaveStreamingWeb

How Apple's HTTP Live Streaming carries subtitles: a playlist, and the WebVTT files it lists, each a few seconds of the programme. A player fetches them as it plays, beside the video's own segments.

At a glance

Extension.m3u8
Media typeThe playlist: application/vnd.apple.mpegurl. Its segments: text/vtt.
SpecificationRFC 8216 (2017), and Apple's HLS Authoring Specification for Apple Devices. The segments are WebVTT.
Time precisionMilliseconds, in the segments' cues
Text encodingUTF-8, for the playlist and the segments alike
StylingWebVTT's: italic, bold, underline, and colours by class
PositioningWebVTT's cue settings
SpeakersWebVTT's voice tags: <v Thom>
In containersNone for WebVTT: plain text files on a web server. IMSC subtitles in HLS come in fragmented MP4.

Anatomy of a playlist

A list of segments, each with its length. The subtitles are in the files it names.

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6.000,
movie_segments/segment00000.vtt
#EXTINF:6.000,
movie_segments/segment00001.vtt
#EXTINF:2.000,
movie_segments/segment00002.vtt
#EXT-X-ENDLIST
  1. 1 · Header

    #EXTM3U first, always. Then the version, the first segment's number, and VOD: a programme whose segments are all there.

  2. 2 · Target duration

    Whole seconds that no segment's length, rounded, goes over.

  3. 3 · Length

    How long the segment after it lasts, in seconds.

  4. 4 · Address

    Where the segment is: beside the playlist here, or a web address.

  5. 5 · End

    Nothing more will come. A live stream leaves it out and keeps adding segments.

Anatomy of a segment

Each segment is a WebVTT file of its own, with one line more in its header.

WEBVTT
X-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:900000
 
00:00:04.000 --> 00:00:07.500
<v Celia>You're a jerk,
Thom.
 
00:00:08.000 --> 00:00:09.600
<v Thom><i>Celia!</i>
  1. 1 · Header

    WEBVTT, as in any WebVTT file.

  2. 2 · Timestamp map

    Which moment of the video a cue time stands for.

  3. 3 · Cues

    Every cue shown during the segment, each with its whole time, even the part outside the segment.

This is the second segment, from 6 to 12 seconds. Its first cue began in the first segment, at 4 seconds, and is in both: a player that starts here still shows it.

The timestamp map

The video's frames carry MPEG-2 timestamps, counted on a clock of 90,000 ticks a second. The map ties the two clocks together:

Part What it says
LOCAL:00:00:00.000 A cue time in this file
MPEGTS:900000 The video's timestamp at that time: 900,000 ticks, 10 seconds

Many encoders start a stream's clock at 10 seconds, so 900000 is the usual value. With the map, a cue at 00:00:04.000 is shown with the frame stamped 1,260,000. A segment without one is read as mapping 0 to 0.

A wrong map moves every subtitle. If the video's clock starts at 10 seconds and the map says 0, a player shows the subtitles 10 seconds late, or not at all. Write the value the video's encoder used.

Subtitles in a whole stream

A stream's main playlist lists its renditions: the video at several sizes, the audio, and the subtitles in each language, each with a playlist of its own.

#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME="English",LANGUAGE="en",DEFAULT=YES,URI="en.m3u8"
Attribute What it holds
TYPE SUBTITLES
LANGUAGE The subtitles' language, as a BCP 47 tag
DEFAULT YES for the one shown when the viewer has chosen none
URI The subtitles' own playlist, like the one above

HLS or a WebVTT file?

WebVTT file HLS
Files One A playlist and a segment every few seconds
Shown by A web page's <track>, players HLS players: Safari, iPhone, Apple TV, and hls.js on the web
Tied to the video by Times from the start The timestamp map, against the video's own timestamps
Live — Segments added as the programme goes on

HLS in Subtitld

Kept in the segments
  • Every subtitle's text and line breaks
  • Italic, bold, underline and colour, as WebVTT keeps them
  • Where it sits, as cue settings
  • Speakers, as voice tags
  • Start and end, to the millisecond
Nowhere to go
  • The language: Subtitld writes the subtitles' playlist, not a main playlist that names it
  • Translations beside the original
  • Dubs, speakers' faces and colours

Save a .usfx project to keep them.

Opening an HLS playlist

Open the .m3u8 file. Subtitld:

  • follows a main playlist to its subtitles: the rendition in the project's language, else the default one, else the first;
  • reads each segment the playlist lists, beside it or at an http or https address, and the part of a file a byte range names;
  • reads the segments as WebVTT, and moves each by its timestamp map, so that the first moment of the stream is 0;
  • keeps a cue that is repeated in the segments it spans once, and joins a cue a segmenter cut in two at a segment's edge;
  • reads IMSC segments in fragmented MP4, as CMAF carries them;
  • takes the rendition's language as the project's.

A file that does not begin with #EXTM3U, or a playlist with no subtitles in it, says so.

Exporting HLS

Subtitld's export dialog with HLS chosen, speakers as voice tags, segments of 6 seconds and the timestamp map at MPEGTS 900000

Export, then Subtitles and HLS, offers:

  • TextThe original, a translation, or both, the translation below.
  • Speaker namesLeft out, before the text (Thom: …), or as voice tags (<v Thom>).
  • FormattingKept, or removed.
  • Shift timesEvery subtitle earlier or later by the same amount.
  • Segment length2, 4, 6 or 10 seconds. 6 is what Apple recommends.
  • Timestamp mapMPEGTS:900000, 10 seconds, where most encoders start a stream's clock, or MPEGTS:0.

Subtitld writes the playlist, version 3, and a folder beside it named after it (movie.m3u8, movie_segments) with the segments, segment00000.vtt and on. Every segment lasts the same but the last, and has the same map, so its cue times are the programme's. The segments run for as long as the video does, empty ones included, or for as long as the subtitles do when there is no video. Saving again replaces the segments in the folder.

Add the playlist to your stream's main playlist with an #EXT-X-MEDIA:TYPE=SUBTITLES line, its language and its address.

Trivia

2009

Apple released HTTP Live Streaming in May 2009. It was published as RFC 8216 in August 2017, after years as an Internet-Draft.

26.5 h

How long the 90,000-tick clock of MPEG-2 timestamps runs before its 33 bits wrap round to zero. RFC 8216 asks players to cope when it does and cue times go on.

6 s

Apple's authoring specification says target durations should be 6 seconds, and that WebVTT subtitles must have a timestamp map.

Related formats

Have a .m3u8 to fix?

Open it in Subtitld with the video and retime it on the waveform.

Download Subtitld