TrackEvent.track — Eigenschaft · JavaScript-Referenz

Signatur

TrackEvent.track

Beschreibung

Die Eigenschaft track des TrackEvent-Interfaces verweist auf das Track-Objekt, das ein Ereignis ausgelöst hat. TrackEvent-Ereignisse werden an den Track-Listen eines Medienelements ausgelöst (audioTracks, videoTracks, textTracks), und zwar bei den Ereignissen addtrack und removetrack.

Je nachdem, an welcher Liste das Ereignis auftritt, ist track ein AudioTrack, ein VideoTrack oder ein TextTrack. Wurde das Ereignis selbst per Konstruktor ohne Angabe eines Tracks erzeugt, ist der Wert null.

Typische Anwendungsfälle sind dynamische Untertitel- oder Sprachauswahlmenüs: Sobald das Medium neue Tracks meldet (z. B. bei HLS/DASH-Streams oder nach dem Einfügen eines <track>-Elements), kann man über event.track auf kind, label, language und id zugreifen und die Oberfläche aktualisieren.

Rückgabewert

Typ

AudioTrack | VideoTrack | TextTrack | null

Beschreibung

Das Track-Objekt, auf das sich das Ereignis bezieht, oder null, wenn beim Erzeugen des Ereignisses kein Track angegeben wurde.

Beispiele

Neue Untertitelspuren erkennen (addEventListener)

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

const onAddTrack = (event) => {
  const { kind, label, language } = event.track;
  console.log(`Neuer Track: ${kind} – ${label} (${language})`);
};

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

// Track dynamisch hinzufügen – löst addtrack aus
const trackEl = document.createElement('track');
trackEl.kind = 'subtitles';
trackEl.label = 'Deutsch';
trackEl.srclang = 'de';
trackEl.src = 'untertitel-de.vtt';
video.append(trackEl);

// Später wieder abmelden
// video.textTracks.removeEventListener('addtrack', onAddTrack);

Neuer Track: subtitles – Deutsch (de)

Sprachauswahl-Menü mit onaddtrack / onremovetrack pflegen

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

video.textTracks.onaddtrack = (event) => {
  const track = event.track;
  if (track.kind !== 'subtitles' && track.kind !== 'captions') return;
  track.mode = 'disabled';
  const option = new Option(track.label || track.language, track.language);
  select.append(option);
};

video.textTracks.onremovetrack = (event) => {
  const option = select.querySelector(`option[value="${event.track.language}"]`);
  option?.remove();
};

select.addEventListener('change', () => {
  for (const t of video.textTracks) {
    t.mode = t.language === select.value ? 'showing' : 'disabled';
  }
});

Track-Typ unterscheiden und synthetisches Ereignis

const describe = (event) => {
  const t = event.track;
  if (t === null) return 'kein Track';
  if (t instanceof TextTrack) return `TextTrack: ${t.kind}`;
  if ('AudioTrack' in window && t instanceof AudioTrack) return `AudioTrack: ${t.label}`;
  if ('VideoTrack' in window && t instanceof VideoTrack) return `VideoTrack: ${t.label}`;
  return 'unbekannt';
};

const leer = new TrackEvent('addtrack');
console.log(describe(leer));

const video = document.createElement('video');
const tt = video.addTextTrack('captions', 'Englisch', 'en');
const evt = new TrackEvent('addtrack', { track: tt });
console.log(describe(evt));

kein Track TextTrack: captions

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.track hat keine Wirkung (im Strict Mode TypeError). Den Track legt man beim Erzeugen über new TrackEvent(type, { track }) fest.
Browser-Kompatibilität: Mit textTracks funktioniert das überall. audioTracks und videoTracks unterstützt nur Safari standardmäßig; in Chrome und Firefox sind sie nur über Flags verfügbar. Deshalb vor Verwendung prüfen, ob 'audioTracks' in HTMLMediaElement.prototype gilt.
Die Ereignisse werden an der Track-Liste ausgelöst (video.textTracks), nicht am Medienelement selbst. Ein Listener an video reagiert also nicht auf addtrack.
Tracks, die bereits im HTML-Markup stehen, können schon vor der Registrierung des Listeners gemeldet worden sein. Deshalb zusätzlich einmal über die vorhandene Liste iterieren.
Ein neu hinzugefügter TextTrack hat oft mode = 'disabled', dann sind seine cues noch nicht geladen.

Siehe auch

HTMLTrackElement.src RTCTrackEvent.track HTMLTrackElement.track RTCTrackEvent.streams SyncEvent.tag