HTMLMediaElement.videoTracks — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLMediaElement.videoTracks

Beschreibung

Die schreibgeschützte Eigenschaft videoTracks liefert ein VideoTrackList-Objekt, das alle Videospuren der aktuell geladenen Medienressource enthält. Jede Spur ist ein VideoTrack mit Eigenschaften wie id, kind, label, language und selected.

Sinnvoll ist das bei Medien mit mehreren Videospuren, etwa einem Hauptvideo und einer Gebärdensprach-Spur, alternativen Kameraperspektiven oder einer Spur mit Audiodeskription. Anders als bei Audiospuren kann immer nur eine Videospur gleichzeitig ausgewählt sein: Setzt man selected = true auf eine Spur, werden alle anderen automatisch abgewählt. Den Index der aktiven Spur liefert videoTracks.selectedIndex (bzw. -1, wenn keine ausgewählt ist).

Die Liste wird dynamisch gefüllt, sobald die Metadaten geladen sind. Deshalb sollte man sie frühestens im Event loadedmetadata auswerten oder auf die Events addtrack, removetrack und change der VideoTrackList reagieren. Die Eigenschaft selbst lässt sich nicht neu zuweisen, die zurückgegebene Liste bleibt aber „live“.

Rückgabewert

Typ

VideoTrackList

Beschreibung

Eine live aktualisierte, array-ähnliche VideoTrackList mit allen VideoTrack-Objekten des Elements. Bietet length, Indexzugriff, selectedIndex, getTrackById(id) sowie die Events addtrack, removetrack und change. Ohne Videospuren ist die Liste leer (length === 0).

Beispiele

Videospuren nach dem Laden der Metadaten auflisten

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

video.addEventListener('loadedmetadata', () => {
  // Funktion prüfen, da die Unterstützung eingeschränkt ist
  if (!('videoTracks' in video)) {
    console.log('videoTracks wird nicht unterstützt');
    return;
  }

  const tracks = video.videoTracks;
  console.log(`Anzahl Videospuren: ${tracks.length}`);

  for (const track of Array.from(tracks)) {
    console.log(track.id, track.kind, track.label || '(ohne Label)', track.selected);
  }
});

Anzahl Videospuren: 2 v1 main Hauptkamera true v2 sign Gebärdensprache false

Auswahlmenü zum Umschalten der Videospur

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

const fillMenu = () => {
  select.replaceChildren();
  Array.from(video.videoTracks).forEach((track, index) => {
    const option = new Option(track.label || `Spur ${index + 1}`, track.id);
    option.selected = track.selected;
    select.append(option);
  });
};

if ('videoTracks' in video) {
  video.videoTracks.addEventListener('addtrack', fillMenu);
  video.videoTracks.addEventListener('removetrack', fillMenu);

  select.addEventListener('change', () => {
    const track = video.videoTracks.getTrackById(select.value);
    // Nur eine Videospur kann aktiv sein – die übrigen werden automatisch abgewählt
    if (track) track.selected = true;
  });
}

Auf Spurwechsel reagieren

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

if ('videoTracks' in video) {
  video.videoTracks.onchange = () => {
    const { selectedIndex } = video.videoTracks;
    if (selectedIndex === -1) {
      console.log('Keine Videospur aktiv');
      return;
    }
    const active = video.videoTracks[selectedIndex];
    console.log(`Aktive Spur: ${active.label} (${active.language || 'ohne Sprache'})`);
  };
}

Aktive Spur: Gebärdensprache (de)

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Safari unterstützt videoTracks standardmäßig. In Chrome ist die Eigenschaft nur mit dem Flag „Experimental Web Platform features“ verfügbar, in Firefox nur über die Einstellung media.track.enabled. Prüfen Sie die Unterstützung daher immer mit 'videoTracks' in video, bevor Sie darauf zugreifen.
Die Liste ist vor loadedmetadata in der Regel leer. Ein direkter Zugriff gleich nach dem Setzen von src liefert also meist length === 0.
Viele gängige Container (z. B. einfache MP4-/WebM-Dateien) enthalten nur eine einzige Videospur. Mehrere Spuren kommen vor allem bei HLS-Streams (Safari) oder speziell erstellten Dateien vor.
Bei Media Source Extensions verweist VideoTrack.sourceBuffer auf den zugehörigen SourceBuffer. Die Spuren werden dann erst beim Anhängen der Initialisierungssegmente angelegt.
VideoTrackList ist array-ähnlich, aber kein echtes Array. Für map/filter vorher Array.from() verwenden.
Für Untertitel und Kapitel ist nicht videoTracks zuständig, sondern textTracks.

Siehe auch

HTMLTextAreaElement.required HTMLMediaElement.audioTracks HTMLMediaElement.textTracks HTMLMediaElement.controls HTMLMediaElement.autoplay