W3cubDocs

/Web APIs

VTTCue

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
VTTCue 33 79 31 No 20 8 4.4.3 33 31 20 8 2.0
VTTCue 23 12 31 10 ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
align 23 79 31 No ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
getCueAsHTML 23 12 31 10 ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
line 23 79 31 No ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
lineAlign No No 31 No No 14.1 No No 31 No 14.5 No
position 23 79 31 No ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
positionAlign No No 31 No No 14.1 No No 31 No 14.5 No
region No No 59 No No 14.1 No No 59 No 14.5 No
size 23 79 31 No ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
snapToLines 23 79 31 No ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
text 23 12 31 10 ≤12.1 6 4.4 25 31 ≤12.1 8 1.5
vertical 23 79 31 No 15 6 4.4 25 31 14 8 1.5

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/VTTCue