## audio-tracks

# Audio Tracks

Audio tracks are a feature of HTML5 video for providing alternate audio track selections to the user, so that a track other than the main track can be played. Video.js offers a cross-browser implementation of audio tracks.

## Table of Contents

- Caveats
- Working with Audio Tracks
  - Add an Audio Track to the Player
  - Listen for a Video Track Becoming Enabled
  - Removing an Audio Track from the Player
- API
  - videojs.AudioTrack
    - id
    - kind
    - label
    - language
    - enabled

## Caveats

- It is not possible to add audio tracks through HTML like you can with text tracks. They must be added programmatically.
- Video.js only stores track representations. Switching audio tracks for playback is not handled by Video.js and must be handled elsewhere - for example, videojs-contrib-hls handles switching audio tracks to support track selection through the UI.

## Working with Audio Tracks

### Add an Audio Track to the Player

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

    // Create a track object.
    var track = new videojs.AudioTrack({
      id: 'my-spanish-audio-track',
      kind: 'translation',
      label: 'Spanish',
      language: 'es'
    });

    // Add the track to the player's audio track list.
    player.audioTracks().addTrack(track);

### Listen for a Video Track Becoming Enabled

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

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

    // Get the current player's AudioTrackList object.
    var audioTrackList = player.audioTracks();

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

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

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

### Removing an Audio Track from the Player

Assuming a player already exists and has an audio 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.audioTracks().getTrackById('my-spanish-audio-track');

    // Remove it from the audio track list.
    player.audioTracks().removeTrack(track);

## API

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

- `Player#audioTracks`
- `AudioTrackList`
- `AudioTrack`

### `videojs.AudioTrack`

This class is based on the `AudioTrack` standard and can be used to create new audio track objects.

Each property below is available as an option to the `AudioTrack` 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 `AudioTracks`:

- `"alternative"`: A possible alternative to the main track.
- `"descriptions"`: An audio description of a video track.
- `"main"`: The primary audio track for this video.
- `"main-desc"`: The primary audio track, mixed with audio descriptions.
- `"translation"`: A translated version of the main audio track.
- `"commentary"`: Commentary on the primary audio track, e.g. a director's 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 languages available as alternate audio tracks.

#### `language`

> standard definition

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

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

#### `enabled`

> standard definition

Whether or not this track should be playing.

In Video.js, we only allow one track to be enabled at a time; so, if you enable more than one, the last one to be enabled will end up being the only one. While the spec allows for more than one track to be enabled, Safari and most implementations only allow one audio track to be enabled at a time.