VideoTrack.language — Eigenschaft · JavaScript-Referenz

Signatur

VideoTrack.language

Beschreibung

Die Eigenschaft language eines VideoTrack-Objekts gibt an, welcher Sprache der Inhalt einer Videospur zugeordnet ist. Der Wert ist ein Sprach-Tag nach BCP 47, etwa "de", "en-GB" oder "ja". Die Angabe stammt aus den Metadaten der Mediendatei bzw. des Streams (z. B. MP4-Container oder HLS-Manifest). Fehlt sie, ist der Wert ein leerer String "".

Bei Videospuren klingt das zunächst ungewöhnlich, ist aber sinnvoll: Manche Medien enthalten mehrere Videospuren mit sprachabhängigem Inhalt, zum Beispiel eingeblendeten Text, Gebärdensprache oder alternative Kamerafahrten mit landesspezifischen Grafiken. Über language kann man die passende Spur für die bevorzugte Sprache des Nutzers auswählen.

Die Liste aller Videospuren eines Medienelements erhält man über HTMLMediaElement.videoTracks (eine VideoTrackList). Eine Spur wird ausgewählt, indem man ihre Eigenschaft selected auf true setzt. Im Gegensatz dazu können mehrere Audiospuren gleichzeitig aktiv sein, aber immer nur eine Videospur.

Rückgabewert

Typ

string

Beschreibung

Ein BCP-47-Sprach-Tag wie "en" oder "de-AT". Ist keine Sprache bekannt, wird ein leerer String "" zurückgegeben.

Beispiele

Sprachen aller Videospuren auflisten

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

video.addEventListener('loadedmetadata', () => {
  // videoTracks wird nicht überall unterstützt
  if (!video.videoTracks) {
    console.log('VideoTrackList wird nicht unterstützt');
    return;
  }

  for (const track of video.videoTracks) {
    console.log(`Spur ${track.id}: ${track.language || '(unbekannt)'}`);
  }
});

Spur 1: de Spur 2: en Spur 3: (unbekannt)

Videospur passend zur Browsersprache auswählen

const selectVideoTrackByLanguage = (video, preferred = navigator.language) => {
  const tracks = video.videoTracks;
  if (!tracks) return null;

  // Erst exakte Übereinstimmung ("de-DE"), dann nur Primärsprache ("de")
  const primary = preferred.split('-')[0].toLowerCase();
  const list = Array.from(tracks);
  const match =
    list.find((t) => t.language.toLowerCase() === preferred.toLowerCase()) ??
    list.find((t) => t.language.toLowerCase().split('-')[0] === primary);

  if (match) match.selected = true; // wählt die übrigen Spuren automatisch ab
  return match ?? null;
};

const video = document.querySelector('video');
video.addEventListener('loadedmetadata', () => {
  const track = selectVideoTrackByLanguage(video, 'de-DE');
  console.log(track ? `Gewählt: ${track.language}` : 'Keine passende Spur');
});

Gewählt: de

Menü zur Spurauswahl erzeugen

const video = document.querySelector('video');
const select = document.querySelector('#video-track-select');
const names = new Intl.DisplayNames(['de'], { type: 'language' });

const buildMenu = () => {
  select.replaceChildren();
  Array.from(video.videoTracks ?? []).forEach((track, index) => {
    const label = track.language ? names.of(track.language) : 'Unbekannt';
    select.append(new Option(label, String(index), false, track.selected));
  });
};

select.addEventListener('change', () => {
  video.videoTracks[Number(select.value)].selected = true;
});

video.videoTracks?.addEventListener('addtrack', buildMenu);

// Wichtig · Fallstricke

Browser-Kompatibilität: VideoTrack und HTMLMediaElement.videoTracks werden standardmäßig nur von Safari unterstützt. In Chrome ist die API hinter einem Flag (Experimental Web Platform Features) versteckt, in Firefox hinter der Einstellung media.track.enabled. Prüfe daher immer vorher, ob video.videoTracks existiert.
Der Wert ist schreibgeschützt. Eine Zuweisung wird still ignoriert, im Strict Mode gibt es keinen Fehler, weil nur ein Getter existiert.
Ein leerer String bedeutet nicht „keine Sprache“, sondern „unbekannt“. Plane eine Rückfalllösung ein.
Die Schreibweise der Sprach-Tags kann je nach Quelle unterschiedlich sein ("en-us" oder "en-US"). Vergleiche deshalb ohne Beachtung von Groß- und Kleinschreibung oder normalisiere mit Intl.getCanonicalLocales(). Manche Container liefern auch dreibuchstabige ISO-639-2-Codes wie "deu".
Die Spuren sind erst nach dem Laden der Metadaten verfügbar. Lies die Werte daher in loadedmetadata oder im addtrack-Event der VideoTrackList aus.

Siehe auch

VideoTrack VideoTrack.label VideoTrack.kind VideoTrack.selected VideoTrackList HTMLMediaElement.videoTracks AudioTrack.language