VideoTrackList: addtrack — Ereignis · JavaScript-Referenz

Signatur

videoTrackList.addEventListener("addtrack", handler)

Beschreibung

Das Ereignis addtrack wird an einer VideoTrackList ausgelöst, wenn eine neue Videospur in die Liste aufgenommen wird. Die Liste bekommt man über HTMLMediaElement.videoTracks, meist von einem <video>-Element. Das Ereignis ist vom Typ TrackEvent. Die neue Spur steht in der Eigenschaft event.track bereit. Das Ereignis steigt nicht auf (bubbelt nicht) und lässt sich nicht abbrechen.

Typische Auslöser sind das Laden der Metadaten einer Mediendatei mit mehreren Videospuren (zum Beispiel verschiedene Kamerawinkel oder eine Gebärdensprach-Spur) und Streams über Media Source Extensions (MSE), die im laufenden Betrieb weitere Spuren anmelden.

Einen Handler registriert man auf zwei Wegen:

mit videoTracks.addEventListener("addtrack", handler). Das ist der empfohlene Weg, weil mehrere Handler möglich sind und man sie gezielt wieder entfernen kann.
über die Eigenschaft videoTracks.onaddtrack = handler. Hier ist nur ein Handler möglich, und jede neue Zuweisung ersetzt den vorherigen.

Mit dem Ereignis kann man zum Beispiel eine Spurauswahl in der Oberfläche aktuell halten oder automatisch eine passende Spur über track.selected = true auswählen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"addtrack"`.
$handler Pflicht	(event: TrackEvent) => void		Callback, der ein `TrackEvent` erhält. `event.track` ist das neu hinzugefügte `VideoTrack`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `signal` (`AbortSignal`) oder `passive`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein TrackEvent mit den Eigenschaften track (VideoTrack), type ("addtrack") und target (die VideoTrackList).

Beispiele

Neue Videospuren mit addEventListener protokollieren

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

// Nur in Browsern mit VideoTrackList-Unterstützung
if ('videoTracks' in video) {
  video.videoTracks.addEventListener('addtrack', (event) => {
    const { id, kind, label, language } = event.track;
    console.log(`Neue Videospur: ${label || id} (${kind}, ${language || 'k. A.'})`);
    console.log(`Spuren insgesamt: ${video.videoTracks.length}`);
  });
} else {
  console.warn('VideoTrackList wird von diesem Browser nicht unterstützt.');
}

Neue Videospur: Kamera 2 (alternative, de) Spuren insgesamt: 2

Spurauswahl über die onaddtrack-Eigenschaft aktualisieren

const video = document.querySelector('#player');
const select = document.querySelector('#spurwahl');

video.videoTracks.onaddtrack = ({ track }) => {
  const option = new Option(track.label || `Spur ${track.id}`, track.id);
  option.selected = track.selected;
  select.append(option);
};

select.addEventListener('change', () => {
  const track = video.videoTracks.getTrackById(select.value);
  if (track) track.selected = true; // hebt die Auswahl der übrigen Spuren automatisch auf
});

Handler mit removeEventListener und AbortController entfernen

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

const onAddTrack = (event) => {
  console.log('Spur hinzugefügt:', event.track.id);
  // Gebärdensprach-Spur automatisch auswählen
  if (event.track.kind === 'sign') event.track.selected = true;
};

video.videoTracks.addEventListener('addtrack', onAddTrack);

// Später, z. B. beim Abbau des Players:
video.videoTracks.removeEventListener('addtrack', onAddTrack);

// Alternative: mehrere Handler auf einmal über ein Signal entfernen
const controller = new AbortController();
video.videoTracks.addEventListener('addtrack', onAddTrack, { signal: controller.signal });
controller.abort(); // entfernt den Handler

// Wichtig · Fallstricke

Browser-Unterstützung: VideoTrackList und damit addtrack funktionieren ohne weitere Einstellungen nur in Safari. In Chrome/Edge muss das Flag „Experimental Web Platform features“ aktiv sein, in Firefox die Einstellung media.track.enabled. Vor der Nutzung sollte man deshalb mit 'videoTracks' in HTMLMediaElement.prototype prüfen, ob die Schnittstelle vorhanden ist.

Spuren, die schon vor der Registrierung des Handlers bekannt waren, lösen kein weiteres Ereignis aus. Deshalb zusätzlich die vorhandenen Einträge in videoTracks durchlaufen (die Liste ist iterierbar bzw. über den Index erreichbar).
Das Ereignis wird an der VideoTrackList ausgelöst und nicht am <video>-Element. Ein Handler direkt am Video-Element empfängt es nicht.
Anders als bei Audiospuren kann in einer VideoTrackList immer nur eine Spur gleichzeitig selected sein. Wählt man eine Spur aus, wird die Auswahl der vorherigen aufgehoben, und das Ereignis change wird ausgelöst.
Eine neue Zuweisung an onaddtrack überschreibt den vorherigen Handler. Für mehrere Handler addEventListener verwenden.

Siehe auch

VideoTrackList VideoTrackList: removetrack VideoTrackList: change VideoTrack TrackEvent HTMLMediaElement.videoTracks AudioTrackList: addtrack