TextTrack.label — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.label

Beschreibung

Die Eigenschaft label des TextTrack-Interfaces gibt die für Menschen lesbare Bezeichnung einer Textspur zurück, etwa „Deutsch“, „English (SDH)“ oder „Kapitel“. Bei Spuren, die über ein <track>-Element eingebunden sind, stammt der Wert aus dessen label-Attribut. Bei Spuren, die per Skript mit HTMLMediaElement.prototype.addTextTrack() erzeugt werden, wird er aus dem zweiten Argument übernommen.

Typischerweise nutzt man label, um eigene Untertitel-Menüs für selbst gebaute Videoplayer zu erstellen. Die Browser-eigenen Bedienelemente zeigen diesen Text ebenfalls in ihrer Untertitel-Auswahl an. Zusammen mit kind und language lässt sich eine Spur eindeutig beschreiben und auswählen.

Die Eigenschaft ist schreibgeschützt. Wer die Bezeichnung einer <track>-Spur ändern will, muss das label-Attribut des Elements setzen, also HTMLTrackElement.label. Ist kein Label angegeben, liefert die Eigenschaft einen leeren String, nicht null.

Rückgabewert

Typ

string

Beschreibung

Die Bezeichnung der Textspur oder "" (leerer String), wenn keine angegeben wurde.

Beispiele

Labels aller Textspuren eines Videos auflisten

// HTML: <video id="film" src="film.mp4">
//   <track kind="subtitles" src="de.vtt" srclang="de" label="Deutsch">
//   <track kind="subtitles" src="en.vtt" srclang="en" label="English">
// </video>
const video = document.getElementById('film');

for (const track of video.textTracks) {
  console.log(`${track.label || '(ohne Label)'} – ${track.language} – ${track.kind}`);
}

Deutsch – de – subtitles English – en – subtitles

Eigenes Untertitel-Menü aus den Labels bauen

const video = document.querySelector('video');
const select = document.createElement('select');
select.append(new Option('Aus', ''));

[...video.textTracks].forEach((track, index) => {
  if (track.kind === 'subtitles' || track.kind === 'captions') {
    select.append(new Option(track.label || `Spur ${index + 1}`, String(index)));
  }
});

select.addEventListener('change', () => {
  [...video.textTracks].forEach((track, index) => {
    track.mode = String(index) === select.value ? 'showing' : 'disabled';
  });
});

video.after(select);

Label bei per Skript erzeugter Spur

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Hörgeschädigte (DE)', 'de');
track.addCue(new VTTCue(0, 3, '[Musik]'));
track.mode = 'showing';

console.log(track.label);

// Schreibversuch wird ignoriert (im Strict Mode: TypeError)
try {
  'use strict';
  track.label = 'Neu';
} catch (e) {
  console.log(e.name);
}
console.log(track.label);

Hörgeschädigte (DE) Hörgeschädigte (DE)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an track.label wird im Sloppy Mode ohne Meldung ignoriert und wirft im Strict Mode (z. B. in ES-Modulen oder Klassen) einen TypeError. Für <track>-Spuren ändert man stattdessen trackElement.label. Der Wert von TextTrack.label passt sich dann an.
Leerer String statt null: Fehlt das Label, sollte man einen Ersatztext anzeigen, z. B. aus language oder dem Index der Spur.
Nicht eindeutig: Mehrere Spuren dürfen dasselbe Label haben. Zur Unterscheidung eignen sich id, language oder kind.
Sicherheit: Labels können aus fremden Quellen stammen. Beim Einfügen ins DOM sollte man textContent oder new Option() verwenden, nicht innerHTML, damit kein XSS möglich ist.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Bei in das Video eingebetteten Spuren (z. B. aus HLS- oder MP4-Containern) hängt das Label davon ab, welche Metadaten der Browser ausliest, und kann leer sein.

Siehe auch

TextTrack TextTrack.kind TextTrack.language TextTrack.mode HTMLTrackElement.label HTMLMediaElement.addTextTrack() HTMLMediaElement.textTracks