video.js/docs/guides/video-tracks.md

Video Tracks

Note: While video tracks are a standard, there are no compatible implementations at this time. This is an experimental technology!

Video tracks are a feature of HTML5 video for providing alternate video tracks to the user, so they can change the type of video they want to watch. Video.js offers a cross-browser implementation of video tracks.

Table of Contents

• Caveats
• Working with Video Tracks
  • Add a Video Track to the Player
  • Listen for a Video Track Becoming Enabled
  • Removing an Video Track from the Player
• API
  • videojs.VideoTrack
    • id
    • kind
    • label
    • language
    • selected

Caveats

• It is not possible to add video tracks through HTML like you can with text tracks. They must be added programmatically.
• Video.js only stores track representations. Switching video tracks for playback is not handled by Video.js and must be handled elsewhere.

Working with Video Tracks

Add a Video Track to the Player

// Create a player.
var player = videojs('my-player');

// Create a track object.
var track = new videojs.VideoTrack({
  id: 'my-alternate-video-track',
  kind: 'commentary',
  label: 'Director\'s Commentary',
  language: 'en'
});

// Add the track to the player's video track list.
player.videoTracks().addTrack(track);

Listen for a Video Track Becoming Enabled

When a track is enabled or disabled on an VideoTrackList, a change event will be fired. You can listen for that event and do something with it.

NOTE: The initial VideoTrack selection (usually the main track that is selected) should not fire a change event.

// Get the current player's VideoTrackList object.
var videoTrackList = player.videoTracks();

// Listen to the "change" event.
videoTrackList.addEventListener('change', function() {

  // Log the currently enabled VideoTrack label.
  for (var i = 0; i < videoTrackList.length; i++) {
    var track = videoTrackList[i];

    if (track.enabled) {
      videojs.log(track.label);
      return;
    }
  }
});

Removing an Video Track from the Player

Assuming a player already exists and has an video track that you want to remove, you might do something like the following:

// Get the track we created in an earlier example.
var track = player.videoTracks().getTrackById('my-alternate-video-track');

// Remove it from the video track list.
player.videoTracks().removeTrack(track);

API

For more complete information, refer to the Video.js API docs, specifically:

• Player#videoTracks
• VideoTrackList
• VideoTrack

videojs.VideoTrack

This class is based on the VideoTrack standard and can be used to create new video track objects.

Each property below is available as an option to the VideoTrack constructor.

id

standard definition

A unique identifier for this track. Video.js will generate one if not given.

kind

standard definition

Video.js supports standard kind values for VideoTracks:

• "alternative": A possible alternative to the main track.
• "captions": The main video track with burned in captions
• "main": The main video track.
• "sign": The main video track with added sign language overlay.
• "subtitles": The main video track with burned in subtitles.
• "commentary": The main video track with burned in commentary.
• "" (default): No explicit kind, or the kind given by the track's metadata is not recognized by the user agent.

label

standard definition

The label for the track that will be shown to the user. For example, in a menu that lists the different captions available as alternate video tracks.

language

standard definition

The valid BCP 47 code for the language of the video track, e.g. "en" for English or "es" for Spanish.

For supported language translations, please see the languages folder (/lang) folder located in the Video.js root and refer to the languages guide for more information on languages in Video.js.

selected

standard definition

Whether or not this track should be playing. Only one video track may be selected at a time.