VideoTrackList — Schnittstelle · JavaScript-Referenz

Signatur

interface VideoTrackList extends EventTarget

Beschreibung

VideoTrackList ist eine Liste, die wie ein Array aufgebaut ist. Sie enthält alle VideoTrack-Objekte einer Mediendatei. Du bekommst sie über HTMLMediaElement.videoTracks, also z. B. video.videoTracks. Brauchbar ist sie vor allem bei Medien mit mehreren Videospuren, etwa verschiedenen Kamerawinkeln, einer Gebärdensprach-Einblendung oder alternativen Schnittfassungen in einer Datei.

Anders als bei AudioTrackList kann immer nur eine Videospur ausgewählt sein. Setzt du VideoTrack.selected = true, wird die bisher gewählte Spur automatisch abgewählt. Die Eigenschaft selectedIndex gibt den Index der aktiven Spur zurück, oder -1, wenn keine Spur ausgewählt ist.

Wichtige Bestandteile:

length: Anzahl der Spuren (nur lesbar).
selectedIndex: Index der aktuell gewählten Spur, sonst -1.
getTrackById(id): gibt die Spur mit der passenden id zurück, sonst null.
Zugriff über den Index (list[0]); die Liste ist mit for...of durchlaufbar.
Events: addtrack, removetrack und change, jeweils auch als onaddtrack, onremovetrack und onchange.

Die Liste ist live. Spuren kommen meist erst hinzu, wenn die Metadaten geladen sind. Lies videoTracks deshalb frühestens beim Event loadedmetadata aus oder reagiere auf addtrack.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Parameter von `getTrackById(id)`: die Kennung (`VideoTrack.id`) der gesuchten Spur.

Rückgabewert

Typ

VideoTrackList

Beschreibung

Wird von HTMLMediaElement.videoTracks zurückgegeben. getTrackById() liefert VideoTrack | null.

Beispiele

Spuren nach dem Laden der Metadaten auflisten

const video = document.querySelector('video');

video.addEventListener('loadedmetadata', () => {
  if (!('videoTracks' in video)) {
    console.log('VideoTrackList wird nicht unterstützt');
    return;
  }
  const tracks = video.videoTracks;
  console.log(`Spuren: ${tracks.length}, aktiv: ${tracks.selectedIndex}`);
  for (const track of tracks) {
    console.log(track.id, track.kind, track.label, track.language, track.selected);
  }
});

Spuren: 2, aktiv: 0 1 main Hauptkamera de true 2 alternative Seitenansicht de false

Kamerawinkel-Umschalter mit getTrackById

const video = document.querySelector('video');
const select = document.querySelector('#angle');

const buildMenu = () => {
  select.replaceChildren(
    ...Array.from(video.videoTracks, (t, i) =>
      new Option(t.label || `Spur ${i + 1}`, t.id, false, t.selected))
  );
};

video.videoTracks.addEventListener('addtrack', buildMenu);
video.videoTracks.addEventListener('removetrack', buildMenu);

select.addEventListener('change', () => {
  const track = video.videoTracks.getTrackById(select.value);
  if (track) track.selected = true; // wählt die anderen Spuren automatisch ab
});

Wechsel mit onchange verfolgen und Listener wieder entfernen

const tracks = document.querySelector('video').videoTracks;

tracks.onchange = () => {
  const active = tracks[tracks.selectedIndex];
  console.log('Aktive Spur:', active ? active.label : 'keine');
};

const onAdd = (event) => console.log('Neue Spur:', event.track.id);
tracks.addEventListener('addtrack', onAdd);

// Später aufräumen
tracks.removeEventListener('addtrack', onAdd);
tracks.onchange = null;

Aktive Spur: Seitenansicht

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Safari unterstützt videoTracks standardmäßig. In Chrome und Edge ist es hinter dem Flag „Experimental Web Platform features“ versteckt, in Firefox hinter media.track.enabled. Prüfe die Unterstützung immer vorher mit 'videoTracks' in HTMLMediaElement.prototype. Für Seiten im Produktivbetrieb eignen sich Media Source Extensions oder Player wie hls.js/dash.js besser.

Direkt nach dem Setzen von src ist die Liste meist leer. Warte auf loadedmetadata oder addtrack.
Es kann höchstens eine Spur gewählt sein. selectedIndex kann -1 sein, prüfe den Wert also, bevor du tracks[tracks.selectedIndex] ausliest.
Die Liste ist kein echtes Array. Methoden wie map brauchen vorher Array.from().
Die Event-Objekte von addtrack und removetrack sind vom Typ TrackEvent; die betroffene Spur steht in event.track.

Siehe auch

AudioTrackList VideoTrack ImageTrackList TextTrackList DOMRectList