4.7 KiB
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.
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 achange
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
A unique identifier for this track. Video.js will generate one if not given.
kind
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
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
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) folder located in the Video.js root and refer to the languages guide for more information on languages in Video.js.
enabled
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.