## video-tracks

# 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.