Why are my WebVTT subtitle tracks not in sync with the video?

WebVTT is a common way to provide subtitles for video content. It contains time windows when a certain subtitle has to be shown, and is synchronized to the video content. The timing information in the WebVTT track gets converted into a timestamp value by the player.

However, synchronisation can be done in different ways, so it depends on the player and the technology that is used. E.g. the native player in Safari, exclusively relies on timestamp information, while HTML5 players typically align subtitles based on the current playback time.
In case of the former, the MPEGTS HLS content sometimes is 10 seconds in front of the time your subtitles are shown. This is probably because the PTS (PresentationTimeStamp) of your MPEGTS HLS content starts at 10 seconds. This is a common approach to properly align audio and video tracks to each other.

How can I align my subtitles again?

In order to provide a player which relies on the timestamp data with this information about this offset, the X-TIMESTAMP-MAP can be used as described in the HLS specification. So, if your WebVTT subtitle file already contains this information, it would start like this:


The value of MPEGTS actually describes an PTS offset of 10 seconds. The default timescale for MPEG-TS is 90,000. In order to achieve an offset of 10 seconds you multiply it by the timescale, which results in 900,000.