1. API
  2. Audio Tracks

API

Audio Tracks

In this section, we'll look at how audio tracks can be tracked and configured with Vidstack Player.

INFO

Audio tracks are currently only supported by the HLS Provider.

Tracks List

The read-only audioTracks property on the player returns a AudioTrackList object that contains AudioTrack objects

Similar to text tracks, the returned list is live; that is, as tracks are added to and removed from the player, the list's contents change dynamically. Once you have a reference to the list, you can monitor it for changes to detect when new tracks are added or existing ones are removed by listening to list events.

        const player = document.querySelector('media-player');

// Length
const hasItems = player.audioTracks.length;

// Index
const track = player.audioTracks[0];

// Get by ID
const track = player.audioTracks.getById('...');

// Iterating
for (const track of player.audioTracks) {
}

// Map to array
player.audioTracks.toArray();

      

The AudioTrack interface contains the following shape:

        interface AudioTrack {
  /**
   * A string which uniquely identifies the track within the media.
   */
  id: string;
  /**
   * A human-readable label for the track, or an empty string if unknown.
   */
  label: string;
  /**
   * A string specifying the audio track's primary language, or an empty string if unknown. The
   * language is specified as a BCP 47 (RFC 5646) language code, such as "en-US" or "pt-BR".
   */
  language: string;
  /**
   * A string specifying the category into which the track falls. For example, the main audio
   * track would have a kind of "main".
   *
   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioTrack/kind}
   */
  kind: string;
}

      

Selecting

The selected property can be used to set the current audio track like so:

        const firstTrack = player.audioTracks[0];
firstTrack.selected = true;

const secondTrack = player.audioTracks[1];
// this statement will set `firstTrack` to false.
secondTrack.selected = true;

      

Once set, the underlying provider will update the audio track.

List Events

The AudioTrackList object is an EventTarget which dispatches the following events:

  • add: Fired when an audio track has been added to the list.
  • remove: Fired when an audio track has been removed from the list.
  • change: Fired when the selected audio track changes.
        player.audioTracks.addEventListener('add', (event) => {
  const newTrack = event.detail; // `AudioTrack`
  // ...
});

player.audioTracks.addEventListener('change', (event) => {
  const { prev, current } = event.detail; // Audio Tracks
  // ...
});

      

Media Store

The following audio track related properties are available on the media store:

  • audioTracks: An array containing the current list of AudioTrack objects.
  • audioTrack: The current AudioTrack object or null if none is available.
          
        

Media Remote

The changeAudioTrack method on the media remote can be used to dispatch requests to update the current audio track like so:

          
        

Media Events

The following audio track related events are available on the player:

  • audio-tracks-change: Fired when the available list of audio tracks has changed.
  • audio-track-change: Fired when the selected audio track has changed.