VideoTrackList.getTrackById() — Methode · JavaScript-Referenz

Signatur

VideoTrackList.prototype.getTrackById(id)

Beschreibung

Die Methode getTrackById() der Schnittstelle VideoTrackList sucht in den Videospuren eines Medienelements (über HTMLMediaElement.videoTracks) nach der Spur mit der passenden id. Zurückgegeben wird das erste VideoTrack-Objekt, dessen id-Eigenschaft genau mit dem übergebenen String übereinstimmt. Gibt es keinen Treffer, liefert sie null.

Brauchen kann man das, wenn man eine bestimmte Videospur gezielt ansprechen will, etwa einen anderen Kamerawinkel, eine Gebärdensprach-Einblendung oder eine Spur mit anderer Auflösung. Mit dem Ergebnis setzt man dann VideoTrack.selected auf true. Anders als bei Audiospuren kann in einer VideoTrackList immer nur eine Spur ausgewählt sein. Wählt man eine Spur aus, werden alle anderen automatisch abgewählt.

Welche Form die ID hat, legt das Containerformat fest. Bei MPEG-DASH, HLS oder fragmentiertem MP4 stammt sie meist aus den Metadaten, bei Ogg zum Beispiel aus der Track-Nummer. Deshalb sollte man IDs nicht fest im Code hinterlegen. Besser liest man sie zur Laufzeit aus der Liste aus, am besten nach dem Ereignis loadedmetadata oder addtrack.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die gesuchte ID. Sie wird mit `VideoTrack.id` verglichen, und zwar exakt, also mit Beachtung von Groß- und Kleinschreibung. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

VideoTrack | null

Beschreibung

Das erste VideoTrack-Objekt mit passender id oder null, wenn keine Spur passt.

Beispiele

Videospur per ID auswählen

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

video.addEventListener('loadedmetadata', () => {
  // Funktionsprüfung, da nicht alle Browser videoTracks unterstützen
  if (!video.videoTracks) {
    console.warn('VideoTrackList wird nicht unterstützt');
    return;
  }

  const track = video.videoTracks.getTrackById('2');
  if (track) {
    track.selected = true; // wählt alle anderen Videospuren automatisch ab
    console.log(`Aktive Spur: ${track.label || track.id}`);
  } else {
    console.log('Spur mit ID "2" nicht gefunden');
  }
});

Aktive Spur: Kamera 2

Kamerawinkel-Umschalter mit Buttons

const video = document.querySelector('#konzert');
const leiste = document.querySelector('#winkel');

const baueButtons = () => {
  leiste.replaceChildren();
  for (const track of video.videoTracks) {
    const btn = document.createElement('button');
    btn.textContent = track.label || `Spur ${track.id}`;
    btn.dataset.trackId = track.id;
    leiste.append(btn);
  }
};

leiste.addEventListener('click', (event) => {
  const id = event.target.dataset.trackId;
  if (!id) return;
  const track = video.videoTracks.getTrackById(id);
  if (track) track.selected = true;
});

if (video.videoTracks) {
  video.videoTracks.addEventListener('addtrack', baueButtons);
  video.videoTracks.addEventListener('removetrack', baueButtons);
}

Hilfsfunktion mit Rückfall auf die erste Spur

const waehleSpur = (video, gewuenschteId) => {
  const list = video.videoTracks;
  if (!list || list.length === 0) return null;

  const track = list.getTrackById(gewuenschteId) ?? list[0];
  track.selected = true;
  return track.id;
};

const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
  console.log('Gewählt:', waehleSpur(video, 'gebaerdensprache'));
});

Gewählt: 1

// Wichtig · Fallstricke

Browserunterstützung: HTMLMediaElement.videoTracks und damit getTrackById() gibt es von Haus aus nur in Safari. In Chrome/Edge muss man „Experimental Web Platform features“ aktivieren, in Firefox die Einstellung media.track.enabled. Prüfe deshalb vor dem Aufruf immer, ob video.videoTracks existiert.
Bevor die Metadaten geladen sind, ist die Liste leer, und getTrackById() gibt null zurück. Rufe die Methode deshalb erst nach loadedmetadata oder addtrack auf.
Die ID ist immer ein String. Zahlen werden zwar umgewandelt, ein Vergleich wie track.id === 2 schlägt aber fehl.
Bei Streams über Media Source Extensions (MSE) oder HLS-Bibliotheken wie hls.js tauchen die Spuren oft gar nicht in videoTracks auf. Die Auswahl läuft dort über die API der jeweiligen Bibliothek.
Kommt eine ID mehrfach vor, was eigentlich nicht erlaubt ist, liefert die Methode nur den ersten Treffer.

Siehe auch

VideoTrackList VideoTrack VideoTrack.selected VideoTrackList.selectedIndex HTMLMediaElement.videoTracks AudioTrackList.getTrackById() TextTrackList.getTrackById()