Contents

Delivering WebVTT subtitles and captions in HLS

Add WebVTT subtitle and caption tracks to your HTTP Live Streaming (HLS) streams, and declare their absence when a stream doesn’t carry captions.

Overview

WebVTT (Web Video Text Tracks) is the standard format for delivering captions and subtitles in HLS streams. Apple devices running iOS, iPadOS, macOS, and tvOS play WebVTT tracks and support multiple languages.

When your media stream or interstitial doesn’t include subtitles or captions, add CLOSED-CAPTIONS=NONE to every #EXT-X-STREAM-INF tag in your HLS multivariant playlist.

The following sample stream variant declares that no closed captions are available:

#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS="avc1.4d401f,mp4a.40.2",CLOSED-CAPTIONS=NONE

Configure subtitle tracks in the multivariant playlist

The following attributes apply to EXT-X-MEDIA tags with TYPE=SUBTITLES in your multivariant playlist:

#

Attribute

Purpose

Required

Example Value

1

TYPE

Media type identifier

Yes

SUBTITLES

2

GROUP-ID

Groups related subtitle tracks

Yes

"subtitles"

3

NAME

Display name for subtitle track

Yes

"English"

4

LANGUAGE

ISO 639-1/639-2 language code

Yes

"en"

5

URI

Path to playlist that contains WebVTT segments

Yes

"subtitles/en.m3u8"

6

DEFAULT

Sets default caption track

No, but recommended

YES/NO

7

AUTOSELECT

Auto-selects based on device language

No, but recommended

YES/NO

8

FORCED

Indicates forced subtitles

If applicable

YES/NO

Synchronize subtitle timing with video segments

Follow these guidelines to keep subtitle cues aligned with the audio and video timeline:

Segment alignment

Ensure subtitle timing aligns with video segments.

Overlap handling

Avoid overlapping cue times.

Precision

Align cue start and end times to the actual audio boundaries; WebVTT timestamps use millisecond precision (HH:MM:SS.mmm).

Format caption text for readability

Follow these general accessibility guidelines when you author caption text, as targets rather than hard HLS requirements:

Line length

Maximum 32 characters per line for mobile devices.

Reading speed

160–180 words per minute maximum.

Duration

Minimum 1.5 seconds, maximum 7 seconds per caption.

Line count

Maximum 2 lines per caption for optimal readability.

See Also