Introduction
WebVTT subtitles and captions can be carried as a text track inside an ISO base media
file: an MP4, a fragmented MP4 or a CMAF segment. This is a separate format from a
plain .vtt file: the cues are not lines of text in
a file but boxes inside the samples of a track, and the file is an
MP4. The way of carrying them is defined by
ISO/IEC 14496-30, a paid standard. It has no file extension of its own. The sample
entry type of its tracks is wvtt, which this page uses as its name.
This page describes the boxes as the MP4RA registry lists them and as three open-source programs read and write them. None of that is the standard itself, so what only the standard says is listed under Not described.
Structure
stsd (sample description of a text track)
wvtt sample entry
vttC configuration: the WebVTT header lines
vlab optional source label
mdat samples, each a run of these boxes:
vttc one cue
vsid optional cue source ID
iden optional cue identifier
ctim optional cue current time
sttg optional cue settings
payl cue text
vtta optional additional text (a peer of vttc)
vtte empty cue: nothing to show in this interval
The tree is the one the programs below read and write. The MP4RA registry gives each box a one-line description; the table says where that wording comes from.
Boxes
| Box | Where | MP4RA registry entry | Contents, from the open-source code |
|---|---|---|---|
wvtt | in stsd | “WebVTT data”, sample-entries.csv, type Text, specification ISO-Text | The sample entry of a WebVTT track. It is a sample entry: 6 reserved bytes, a 16-bit data_reference_index, then child boxes. An MPEG-4 bit rate box may follow (Shaka Packager notes it as optional and does not handle it). |
vttC | in wvtt | “WebVTTConfigurationBox”, sample-entries-boxes.csv, type Text | A string with exactly the lines of the file’s header: the text up to but not including the two or more line terminators that end the header (Shaka Packager’s comment, citing 14496-30:2014 7.5). A minimal writer stores WEBVTT. Shaka Packager notes that the standard defines no place for STYLE or REGION blocks and drops them. |
vlab | in wvtt | “WebVTT Source Label” (sample-entries-boxes.csv, type Text); also “WebVTT specific box in a codec-specific sample entry” (unlisted.csv) | A string naming the source of the track. Shaka Packager’s code has a to-do to put the source file URI there and writes the placeholder source_label, so that the box exists for samples with overlapping cues. |
vttc | in a sample | “VTTCueBox only present in WebVTT sample payload” (unlisted.csv) | One cue shown during the sample’s time interval. It holds the five boxes below, in this order, all but payl optional (Shaka Packager’s reader). |
vsid | in vttc | “inner CueSourceIDBox in the VTTCueBox” (unlisted.csv) | A signed 32-bit integer, the cue source ID. Shaka Packager uses −1 for “not set” (its comment: “It is very unlikely that 2^31 cues happen at once”) and then leaves the box out. What the numbers identify is under Unknown. |
iden | in vttc | No entry in the registry files read (unlisted.csv, boxes.csv, sample-entries.csv, sample-entries-boxes.csv) | The cue identifier, a string: the identifier line of a file cue. Named CueIDBox by Shaka Packager, which leaves it out when the cue has no identifier. GPAC lists it as a child of vttc. |
ctim | in vttc | “inner CueTimeBox in the VTTCueBox” (unlisted.csv) | A string holding a WebVTT timestamp, which Shaka Packager’s comment describes as “the VTT timestamp associated with the start time of sample”, for cues that have timestamp tags inside their text. Shaka Packager has a to-do for writing it and does not write it yet. |
sttg | in vttc | “inner CueSettingsBox in the VTTCueBox” (unlisted.csv) | The cue settings string, as written on a timing line after the two timestamps (for example line:10% align:start). Left out when empty. |
payl | in vttc | “inner CuePayloadBox in the VTTCueBox” (unlisted.csv) | The cue text, with the same tags and character references as the cue text of a .vtt file. The only child that is always written. |
vtta | in a sample | “VTTAdditionalTextBox only present in WebVTT sample payload” (unlisted.csv) | Additional text outside any cue. GPAC fills it from the text that comes before a cue (pre_text) and writes it ahead of that cue’s vttc. |
vtte | in a sample | “VTTEmptyCueBox only present in WebVTT sample payload” (unlisted.csv) | A box with no content, only its 8-byte header. GPAC writes it for a sample that has no cues; Shaka Packager writes it for the intervals in which no cue is displayed. |
The registry files are in the default branch, CENC, of
github.com/mp4ra/mp4ra.github.io, folder data.
Strings and timing
Every string box holds raw UTF-8 up to the end of its box, with no length field and
no terminating zero (the readers in Shaka Packager’s box_definitions.cc
read to the end of the box). GPAC removes trailing white space before it writes a
string and leaves out an empty one. A cue’s start and end are not stored in boxes:
they are the time and duration of the sample in the track’s own time scale. Shaka
Packager works out, from the cues’ start and end times, the intervals in which the set
of visible cues does not change, and writes each interval as a sample with one
vttc per visible cue. A reader that does not understand a peer of
vttc skips it by its size: Media3’s Mp4WebvttParser skips
every top-level box but vttc and ignores every child of
vttc but sttg and payl.
Not described
This page is taken from the MP4RA registry and from open-source code, all read 2026-11-19, not from ISO/IEC 14496-30 itself, which is not freely available.
Unknown
- Reference: what the
vsidcue source ID number identifies, and the normative rules for when each box must or may be written, appear only in the paid standard. The registry gives only “inner CueSourceIDBox in the VTTCueBox”. Shaka Packager defines the box as a signed 32-bit integer with −1 for not set but its handler never sets it; the GPAC fileswebvtt.candbox_funcs.chave novsidbox, and Media3 ignores every child ofvttcbutsttgandpayl. - Reference: the exact byte layout of the sample entry beyond what the code shows (the optional boxes that may follow
vlab), and how the standard treats theSTYLEandREGIONblocks of a.vttfile, other than Shaka Packager’s comment that it defines no place for them. - Viewer: the explorer has no WebVTT-specific view of these boxes; an MP4 file opens as an MP4.
See also
Links
Developers
- GPAC – multimedia framework whose
src/media_tools/webvtt.candsrc/isomedia/box_funcs.cread and write these boxes (C) - Shaka Packager – media packager whose
packager/media/formats/mp4/box_definitions.ccdefines them (C++) - AndroidX Media3 – its
Mp4WebvttParserreadsvttc,sttgandpayl(Java, Android)
Reference
- MP4 Registration Authority – the registry of box and sample entry codes; the data files are in the
CENCbranch, folderdata - ISO/IEC 14496-30 – the standard that defines timed text and other visual overlays in ISO base media files (paid)
- WebVTT: The Web Video Text Tracks Format – the W3C specification of the cues themselves