VTTCue

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.

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.

<video controls src="/shared-assets/videos/friday.mp4"></video>

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

Result

Specifications

Browser compatibility