VideoTrack.selected — Eigenschaft · JavaScript-Referenz

Signatur

VideoTrack.selected

Beschreibung

Die Eigenschaft selected eines VideoTrack-Objekts zeigt an, ob diese Videospur gerade wiedergegeben wird. Sie ist les- und schreibbar: Setzt man sie auf true, wird die Spur aktiv. Setzt man sie auf false, wird sie abgewählt.

Anders als bei Audiospuren (AudioTrack.enabled, dort können mehrere gleichzeitig aktiv sein) kann in einer VideoTrackList immer nur eine Videospur ausgewählt sein. Wählt man eine Spur aus, setzt der Browser selected bei allen anderen Spuren derselben Liste automatisch auf false. Den Index der aktiven Spur liefert VideoTrackList.selectedIndex (oder -1, wenn keine Spur ausgewählt ist).

Typische Anwendungsfälle sind Medien mit mehreren Videospuren, zum Beispiel verschiedene Kamerawinkel, eine Fassung mit Gebärdensprache oder Versionen mit unterschiedlichen Einblendungen. Der Zugriff läuft über HTMLMediaElement.videoTracks. Wenn sich die Auswahl ändert, löst die VideoTrackList das Ereignis change aus.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Spur gerade die aktive Videospur ist, sonst false. Beim Zuweisen von true werden alle anderen Spuren der Liste abgewählt.

Beispiele

Aktive Videospur ermitteln

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

video.addEventListener('loadedmetadata', () => {
  if (!video.videoTracks) {
    console.log('VideoTrack-API wird nicht unterstützt');
    return;
  }
  for (const track of video.videoTracks) {
    console.log(`${track.label || track.id}: ${track.selected ? 'aktiv' : 'inaktiv'}`);
  }
});

Hauptkamera: aktiv Tribüne: inaktiv

Kamerawinkel per Schaltfläche wechseln

const video = document.querySelector('video');
const buttons = document.querySelectorAll('[data-track]');

buttons.forEach((btn) => {
  btn.addEventListener('click', () => {
    const index = Number(btn.dataset.track);
    const track = video.videoTracks?.[index];
    if (track) {
      // Andere Spuren werden automatisch abgewählt
      track.selected = true;
    }
  });
});

video.videoTracks?.addEventListener('change', () => {
  console.log('Aktive Spur:', video.videoTracks.selectedIndex);
});

Aktive Spur: 1

Spur mit Gebärdensprache bevorzugen

const selectSignTrack = (video) => {
  const tracks = Array.from(video.videoTracks ?? []);
  const sign = tracks.find((t) => t.kind === 'sign');
  if (sign) {
    sign.selected = true;
    return sign.label;
  }
  return null;
};

const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
  console.log(selectSignTrack(video) ?? 'Keine Gebärdensprach-Spur vorhanden');
});

Gebärdensprache

// Wichtig · Fallstricke

Browser-Kompatibilität: Uneingeschränkt nutzbar ist die API nur in Safari. In Chrome und Edge ist sie nur über das Flag „Experimental Web Platform features“ verfügbar, in Firefox nur über media.track.enabled. Prüfe deshalb immer, ob video.videoTracks existiert.
Es kann immer nur eine Videospur ausgewählt sein. Wenn du selected = false auf die aktive Spur setzt, ist keine Spur mehr aktiv (selectedIndex === -1) und es wird kein Bild angezeigt.
Spuren stehen erst nach dem Laden der Metadaten bereit. Frage sie also frühestens bei loadedmetadata ab oder reagiere auf das Ereignis addtrack.
Bei adaptivem Streaming (HLS/DASH über Media Source Extensions) werden die Spuren oft vom Player-Framework verwaltet und tauchen nicht unbedingt in videoTracks auf.

Siehe auch

ElementInternals.ariaSelected VideoTrack.label VideoTrack.id VideoTrack.kind VideoTrack.language