VTTCue

Baseline Widely available

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

The VTTCue interface—part of the API for handling WebVTT (text tracks on media presentations)—describes and controls the text track associated with a particular <track> element.

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: Returns an enum representing the cue writing direction.
VTTCue.snapToLines: Returns true if the VTTCue.line attribute is an integer number of lines or a percentage of the video size.
VTTCue.line: Returns 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: Returns an enum representing the alignment of the VTTCue.line.
VTTCue.position: Returns the indentation of the cue within the line. This can be the string auto or a number representing the percentage of the VTTCue.region, or the video size if VTTCue.region is null.
VTTCue.positionAlign: Returns 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: Returns a double representing the size of the cue, as a percentage of the video size.
VTTCue.align: Returns an enum representing the alignment of all the lines of text within the cue box.
VTTCue.text: Returns a string with 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

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);

Specifications

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

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
VTTCue
VTTCue() constructor
align
getCueAsHTML
line
lineAlign
position
positionAlign
region
size
snapToLines
text
vertical