TextTrackList.getTrackById() — Methode · JavaScript-Referenz

Signatur

TextTrackList.prototype.getTrackById(id)

Beschreibung

Mit getTrackById() suchen Sie gezielt eine einzelne Textspur (Untertitel, Bildunterschriften, Kapitel, Beschreibungen oder Metadaten) aus der TextTrackList eines <video>- oder <audio>-Elements heraus. Diese Liste erhalten Sie über HTMLMediaElement.textTracks.

Verglichen wird mit der Eigenschaft TextTrack.id. Bei Spuren aus einem <track>-Element entspricht sie dem id-Attribut dieses Elements. Bei Spuren, die per addTextTrack() im Skript erzeugt wurden, ist die id eine leere Zeichenkette. Solche Spuren findet diese Methode deshalb nicht zuverlässig.

Die Methode ist praktisch, wenn Sie eine bestimmte Spur per Knopf ein- oder ausschalten wollen, zum Beispiel beim Wechsel der Untertitelsprache. So müssen Sie nicht die ganze Liste durchlaufen. Gibt es mehrere Spuren mit derselben id, erhalten Sie die erste davon. Gibt es keine passende Spur, liefert die Methode null.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die gesuchte Kennung. Sie wird mit `TextTrack.id` verglichen, also mit dem `id`-Attribut des zugehörigen `<track>`-Elements. Groß- und Kleinschreibung werden unterschieden.

Rückgabewert

Typ

TextTrack | null

Beschreibung

Die erste TextTrack mit passender id oder null, wenn keine Spur passt.

Beispiele

Deutsche Untertitel gezielt einschalten

// HTML:
// <video id="player" src="film.mp4" controls>
//   <track id="sub-de" kind="subtitles" srclang="de" label="Deutsch" src="de.vtt">
//   <track id="sub-en" kind="subtitles" srclang="en" label="English" src="en.vtt">
// </video>

const video = document.querySelector('#player');
const track = video.textTracks.getTrackById('sub-de');

if (track) {
  track.mode = 'showing';
  console.log(`Aktiv: ${track.label} (${track.language})`);
}

Aktiv: Deutsch (de)

Untertitelsprache per Auswahlfeld wechseln

const video = document.querySelector('#player');
const select = document.querySelector('#subtitle-select'); // Werte: 'off', 'sub-de', 'sub-en'

select.addEventListener('change', () => {
  // Zuerst alle Untertitel ausblenden
  for (const t of video.textTracks) {
    if (t.kind === 'subtitles') t.mode = 'disabled';
  }
  if (select.value === 'off') return;

  const chosen = video.textTracks.getTrackById(select.value);
  if (chosen) {
    chosen.mode = 'showing';
  } else {
    console.warn(`Keine Spur mit id "${select.value}" gefunden`);
  }
});

Nicht vorhandene id liefert null

const video = document.querySelector('#player');
const missing = video.textTracks.getTrackById('sub-fr');
console.log(missing);

// Sichere Kurzform mit optionaler Verkettung
console.log(video.textTracks.getTrackById('sub-fr')?.label ?? 'nicht vorhanden');

null nicht vorhanden

// Wichtig · Fallstricke

Spuren aus dem Skript: Mit HTMLMediaElement.addTextTrack() erzeugte Spuren haben die leere Zeichenkette "" als id. Nutzen Sie für sie besser eine eigene Referenz oder suchen Sie über label bzw. language.
Später gesetzte ids: Wenn Sie das id-Attribut eines <track>-Elements nachträglich ändern, ändert sich TextTrack.id nicht in jedem Browser mit. Legen Sie die ids deshalb direkt im HTML fest.
Mehrfach vergebene ids: Es wird nur die erste passende Spur zurückgegeben. Doppelte ids sind im HTML ohnehin ungültig.
Status der Spur: Wird eine Spur gefunden, heißt das nicht, dass ihre Hinweise (Cues) schon geladen sind. track.cues kann bei mode = 'disabled' den Wert null haben. Warten Sie auf das load-Ereignis des <track>-Elements.
Kompatibilität: In allen modernen Browsern (Chrome, Edge, Firefox, Safari) verfügbar. Nicht verfügbar im Internet Explorer.

Siehe auch

AudioTrackList.getTrackById() VideoTrackList.getTrackById() TextTrackCueList.getCueById() MediaStream.getTrackById() TextTrack.removeCue()