Dynamic TextTrack Objects

You can add closed-caption TextTrack and TextTrackCue objects dynamically to your HTML5 video apps using new media methods.

Internet Explorer 11 now supports three new methods to add TextTrack and TextTrackCue objects directly from your app, as outlined in the W3C HTML5 specification. The new methods are:

MethodDescription
addTextTrack Adds a TextTrack object to the current video.
addCue Adds a new TextTrackCue object to a TextTrack.
removeCue Removes a TextTrackCue object from the TextTrack object.

 

In Internet Explorer 10, you add closed-captions to a video by creating a Timed Text Markup Language (TTML) or Web Video Text Track (WebVTT) file and loading it with the Track element. This worked well if you had your cues created ahead of time, but you couldn't change the text once the file was loaded. IE11 brings more flexibility by letting you add tracks and cues to a video without requiring a file. This opens up more apps to captioning for several reasons. When you send a TTML or WebVTT file from a web server, the correct mime type must be transmitted. It's common for servers to be set up for video mime types, but not for text track mime types. A caption file can be sent to the client as a simple text file using XMLHttpRequest (XHR), bypassing the need for a TTML or WebVTT mime type. Cues can be sent that just contain the starting and ending time, and the message, and then added to a track created at run time on the client.

You can also create captioning tools that allow you to write captions as you watch a video, similar to HTML5 Video Caption Maker. As you create new cues, you can add them to the text track and test them immediately with the video.

Add TextTrack and TextTrackCue objects

To add TextTrack and TextTrackCue objects, first create a TextTrack programmatically. Use the addTextTrack method to create an empty TextTrack that's attached to the video element. You can add captions to the TextTrack by calling addCue with the start and end times, and the text message to display as parameters.

Note  You can only add cues to a TextTrack that was created using addTextTrack. IE11 throws an InvalidStateError if applied to a TextTrack loaded by file with the Track element .

The video element in the following example uses controls, autoplay, and muted attributes to provide the built-in playback controls, start the video when it loads, and turn the sound off. These attributes are true if present, false if not, so you don't need to assign values. Use the source element to set the video source file. The example specifies a generic video file, so you can substitute any mp4 video.

The start time, end time, and a simple caption message for the TextTrackCue objects are created in a loop. The start and end time are set so that each message shows for five seconds. For more info about using HTML5 video, see How to use HTML5 to play video files on your webpage.


<!DOCTYPE html >

<html >
  <head>
    <title>Add Text Tracks example</title>
</head>
<body>

<video id="video1" controls="controls" muted="muted">
     <!-- change to your own mp4 video file -->
  <source src="http://ie.microsoft.com/testdrive/Videos/BehindIE9ModernWebStandards/Video.mp4" />   
  HTML5 Video not supported 
</video>

 <script>
   var video = document.getElementById("video1");
   var startTime, endTime, message;
   var newTextTrack = video.addTextTrack("captions", "sample");
   newTextTrack.mode = newTextTrack.SHOWING; // set track to display
   // create some cues and add them to the new track 
   for (var i = 0; i < 30; i++) {
     startTime = i * 5;
     endTime = ((i * 5) + 5);
     message = "This is number " + i;
     newTextTrack.addCue(new TextTrackCue(startTime, endTime, message));
   }
   video.play();
  </script>
</body>
</html>


Remove a TextTrackCue from a TextTrack object

You can remove an existing TextTrackCue using removeCue. This example starts playing the video, and retrieves each cue for display. When it sees the second cue, it deletes it using removeCue before it is displayed.


<!DOCTYPE html >
<html >
  <head>
    <title>Remove Cue example</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
</head>
<body>

<video id="video1" controls muted autoplay>
    <source src="video.mp4">
    HTML5 Video not supported 
</video>

 <script type="text/javascript">
    var video = document.getElementById("video1");
    var beginTime, endTime, message; 
    var newTextTrack = video.addTextTrack("captions", "sample");
    newTextTrack.mode = newTextTrack.SHOWING; // set track to display
    // create some cues and add them to the new track 
    for(var i=0;i<10;i++){
        beginTime =  i * 5 ;
        endTime = ( (i * 5) +  5);
        message =  "This is number " + i; 
        newTextTrack.addCue(new TextTrackCue(beginTime, endTime, message));
    }
    //  Watch for cue change events
    newTextTrack.addEventListener("cuechange", function () {
            // get current cue, and remove it if it's number 2
            var currentCue = newTextTrack.activeCues[0];             
            if (currentCue.text == "This is number 2") {
                newTextTrack.removeCue(currentCue)
            }            
        },false);
     
  </script>
</body>
</html>


When you use the removeCue method, the TextTrackCue object must match a TextTrackCue on the text track, or you'll get a NotFoundError exception.

Related topics

How to use HTML5 to play video files on your webpage
TextTrackCue
addTextTrack
removeCue
addCue

 

 

Show:
© 2015 Microsoft