VideoTrackList: change — Ereignis · JavaScript-Referenz

Signatur

videoTrackList.addEventListener("change", handler)

Beschreibung

Das change-Ereignis tritt an einer VideoTrackList auf, die man über HTMLMediaElement.videoTracks erhält. Es wird ausgelöst, sobald sich die Auswahl der aktiven Videospur ändert – also wenn eine Spur über VideoTrack.selected = true ausgewählt wird oder der Browser selbst die Spur wechselt (z. B. über ein eingebautes Menü zur Spurauswahl).

Anders als bei Audiospuren kann in einer VideoTrackList immer höchstens eine Spur ausgewählt sein. Wählt man eine neue Spur aus, wird die bisherige automatisch abgewählt; beides zusammen erzeugt nur ein einziges change-Ereignis. Die aktuell gewählte Spur ermittelt man über videoTrackList.selectedIndex.

Typische Anwendungsfälle sind eigene Player-Oberflächen mit Kamerawinkel- oder Gebärdensprach-Spuren: Über das Ereignis hält man die Benutzeroberfläche (Dropdown, Buttons) synchron mit der tatsächlich aktiven Spur. Das Ereignis ist nicht abbrechbar und steigt nicht auf (kein Bubbling). Es kann per addEventListener("change", …) oder über die Eigenschaft onchange registriert werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"change"`.
$handler Pflicht	(event: Event) => void		Callback, der ein generisches `Event` erhält. `event.target` ist die betroffene `VideoTrackList`; die geänderte Spur selbst wird nicht mitgeliefert.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt (kein spezieller Ereignistyp).

Beispiele

Spurwechsel mit addEventListener überwachen

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

if (!tracks) {
  console.warn('VideoTrackList wird von diesem Browser nicht unterstützt.');
} else {
  tracks.addEventListener('change', (event) => {
    const list = event.target;
    const idx = list.selectedIndex;
    const track = idx >= 0 ? list[idx] : null;
    console.log('Aktive Videospur:', track ? `${track.label || track.id} (${track.kind})` : 'keine');
  });

  // Zweite Spur (z. B. anderer Kamerawinkel) auswählen
  if (tracks.length > 1) {
    tracks[1].selected = true;
  }
}

Aktive Videospur: Kamera 2 (alternative)

Auswahl-Dropdown mit onchange synchron halten

const video = document.querySelector('#player');
const select = document.querySelector('#angle-select');
const tracks = video.videoTracks;

const renderOptions = () => {
  select.replaceChildren(
    ...Array.from(tracks, (t, i) => new Option(t.label || `Spur ${i + 1}`, String(i), false, t.selected))
  );
};

// Benutzeroberfläche -> Spur
select.addEventListener('change', () => {
  tracks[Number(select.value)].selected = true;
});

// Spur -> Benutzeroberfläche (z. B. bei Wechsel über native Steuerelemente)
tracks.onchange = () => {
  select.value = String(tracks.selectedIndex);
};

video.addEventListener('loadedmetadata', renderOptions);

Listener mit AbortController wieder entfernen

const video = document.querySelector('video');
const controller = new AbortController();

const onTrackChange = () => {
  console.log('Neue Spur-Index:', video.videoTracks.selectedIndex);
};

video.videoTracks.addEventListener('change', onTrackChange, { signal: controller.signal });

// Später, z. B. beim Zerstören der Player-Komponente:
controller.abort();
// Alternativ klassisch:
// video.videoTracks.removeEventListener('change', onTrackChange);
// bzw. video.videoTracks.onchange = null;

Neue Spur-Index: 1

// Wichtig · Fallstricke

Browser-Unterstützung sehr eingeschränkt: HTMLMediaElement.videoTracks ist nur in Safari standardmäßig verfügbar. In Chrome/Edge nur hinter dem Flag „Experimental Web Platform features“, in Firefox hinter media.track.enabled. Immer per if (video.videoTracks) auf Unterstützung prüfen.
Das Ereignis liefert keine Information darüber, welche Spur sich geändert hat – über selectedIndex bzw. die selected-Eigenschaft der Spuren ermitteln.
Nicht verwechseln mit addtrack/removetrack: Diese Ereignisse melden Hinzufügen bzw. Entfernen von Spuren, nicht den Wechsel der Auswahl.
Einfache MP4-/WebM-Dateien enthalten meist nur eine Videospur; Spurwechsel sind vor allem bei HLS-Streams oder Dateien mit mehreren Videospuren relevant.
Das Setzen von selected = false auf der einzigen aktiven Spur führt zu selectedIndex === -1; es wird dann kein Bild mehr angezeigt.

Siehe auch

VideoTrackList VideoTrack VideoTrack.selected VideoTrackList.selectedIndex HTMLMediaElement.videoTracks