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.

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

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

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

BCD tables only load in the browser