AudioTrackList.getTrackById() — Methode · JavaScript-Referenz

Signatur

AudioTrackList.prototype.getTrackById(id)

Beschreibung

Mit getTrackById() sucht man in einer AudioTrackList gezielt nach einer Tonspur anhand ihrer Kennung. Die Liste bekommt man über HTMLMediaElement.audioTracks eines <video>- oder <audio>-Elements. Die Methode liefert das erste AudioTrack-Objekt, dessen Eigenschaft id genau dem übergebenen String entspricht.

Die id einer Tonspur kommt aus der Mediendatei selbst, zum Beispiel aus dem Container (MP4-Track-ID, WebM-Tracknummer) oder bei adaptivem Streaming aus dem Manifest. Man verwendet die Methode vor allem dann, wenn die IDs bekannt sind, etwa aus einer Konfiguration oder einer Nutzereinstellung, und eine bestimmte Spur (Originalton, Synchronfassung, Audiodeskription) gezielt aktivieren oder deaktivieren soll, ohne die ganze Liste zu durchlaufen.

Wird keine passende Spur gefunden, gibt die Methode null zurück. Der Vergleich beachtet Groß- und Kleinschreibung und findet nur exakte Treffer. Eine Suche nach Teilstrings gibt es nicht.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die Kennung der gesuchten Tonspur. Sie wird mit `AudioTrack.id` auf exakte Gleichheit verglichen. Andere Werte werden in einen String umgewandelt.

Rückgabewert

Typ

AudioTrack | null

Beschreibung

Das erste AudioTrack-Objekt mit passender id oder null, wenn keine Spur diese Kennung hat.

Beispiele

Tonspur per ID suchen und aktivieren

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

video.addEventListener('loadedmetadata', () => {
  const tracks = video.audioTracks;
  if (!tracks) {
    console.warn('audioTracks wird nicht unterstützt');
    return;
  }

  const track = tracks.getTrackById('2');
  if (track) {
    track.enabled = true;
    console.log(`Aktiv: ${track.label} (${track.language})`);
  } else {
    console.log('Keine Spur mit ID 2 gefunden');
  }
});

Aktiv: Deutsch (de)

Nur eine Tonspur aktiv lassen (Sprachumschaltung)

const selectAudioTrack = (media, id) => {
  const list = media.audioTracks;
  const target = list?.getTrackById(id);
  if (!target) return false;

  // Alle anderen Spuren abschalten, damit nicht zwei Sprachen gleichzeitig laufen
  for (const track of list) {
    track.enabled = track === target;
  }
  return true;
};

const video = document.getElementById('film');
console.log(selectAudioTrack(video, 'audio-en'));

true

Gespeicherte Nutzereinstellung wiederherstellen

const video = document.querySelector('video');
const savedId = localStorage.getItem('preferredAudioTrack');

video.audioTracks?.addEventListener('addtrack', () => {
  const preferred = savedId && video.audioTracks.getTrackById(savedId);
  if (preferred && !preferred.enabled) {
    preferred.enabled = true;
    console.log('Bevorzugte Tonspur wiederhergestellt:', preferred.id);
  }
});

Bevorzugte Tonspur wiederhergestellt: audio-de

// Wichtig · Fallstricke

Browser-Unterstützung: audioTracks und damit getTrackById() funktioniert nur in Safari ohne Weiteres. In Chrome/Edge muss man „Experimental Web Platform features“ aktivieren, in Firefox die Einstellung media.track.enabled. Vorher also prüfen, ob die Funktion vorhanden ist, zum Beispiel mit if (video.audioTracks) oder video.audioTracks?.getTrackById(...).
Die Liste ist erst gefüllt, wenn die Metadaten geladen sind (loadedmetadata oder addtrack). Ein zu früher Aufruf liefert null.
IDs sind Strings: getTrackById(2) funktioniert zwar dank Umwandlung, trotzdem sollte man Strings übergeben. Die Kennung hängt vom Container bzw. Manifest ab und ist je nach Browser unterschiedlich aufgebaut. Man sollte sich also nicht auf ein bestimmtes Format verlassen.
Bei Streams mit Media Source Extensions oder in Playern wie hls.js/Shaka erscheinen die Tonspuren oft nicht in audioTracks. Dafür nutzt man die API des jeweiligen Players.
Tonspuren können gleichzeitig aktiv sein (enabled). Wer die Sprache umschalten will, muss die anderen Spuren selbst deaktivieren.

Siehe auch

VideoTrackList.getTrackById() TextTrackList.getTrackById() MediaStream.getTrackById() TextTrackCueList.getCueById() AudioContext.setSinkId()