VTTCue

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

The VTTCue interface of the WebVTT API represents a cue that can be added to the text track associated with a particular video (or other media).

A cue defines the text to display in a particular timeslice of a video or audio track, along with display properties such as its size, alignment, and position.

EventTarget TextTrackCue VTTCue

Constructor

VTTCue()

Returns a newly created VTTCue object that covers the given time range and has the given text.

Instance properties

This interface also inherits properties from TextTrackCue.

VTTCue.region

A VTTRegion object describing the video's sub-region that the cue will be drawn onto, or null if none is assigned.

VTTCue.vertical

An enum representing the cue writing direction.

VTTCue.snapToLines

true if the VTTCue.line attribute indicates an integer number of lines or false if it represents a percentage of the video size. This is true by default.

VTTCue.line

Represents the line positioning of the cue. This can be the string auto or a number whose interpretation depends on the value of VTTCue.snapToLines.

VTTCue.lineAlign

An enum representing the alignment of the VTT cue.

VTTCue.position

Represents the indentation of the cue within the line. This can be the string auto, a number representing the percentage of the VTTCue.region, or the video size if VTTCue.region is null.

VTTCue.positionAlign

An enum representing the alignment of the cue. This is used to determine what the VTTCue.position is anchored to. The default is auto.

VTTCue.size

Represents the size of the cue, as a percentage of the video size.

VTTCue.align

An enum representing the alignment of all the lines of text within the cue box.

VTTCue.text

A string representing the contents of the cue.

Instance methods

getCueAsHTML()

Returns the cue text as a DocumentFragment.

Example

HTML

The following example adds a new TextTrack to the video, then adds cues using the TextTrack.addCue() method, with a VTTCue object as the value.

html
<video
  controls
  src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/friday.mp4"></video>

CSS

css
video {
  width: 420px;
  height: 300px;
}

JavaScript

js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";
track.addCue(new VTTCue(0, 0.9, "Hildy!"));
track.addCue(new VTTCue(1, 1.4, "How are you?"));
track.addCue(new VTTCue(1.5, 2.9, "Tell me, is the lord of the universe in?"));
track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor"));
track.addCue(new VTTCue(4.3, 6, "Somebody must've stolen the crown jewels"));
console.log(track.cues);

Result

Specifications

Specification
WebVTT: The Web Video Text Tracks Format
# the-vttcue-interface

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
VTTCue
VTTCue() constructor
align
getCueAsHTML
line
lineAlign
position
positionAlign
region
size
snapToLines
text
All HTML character references allowed.
vertical

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.