TextTrack.id — Eigenschaft · JavaScript-Referenz

Signatur

TextTrack.id

Beschreibung

Die Eigenschaft id der Schnittstelle TextTrack liefert eine Kennung für einen Text-Track, zum Beispiel für Untertitel, Kapitelmarken oder Metadaten. Mit dieser ID können Sie einen bestimmten Track in der TextTrackList eines Medienelements gezielt finden, etwa über video.textTracks.getTrackById().

Woher der Wert stammt, hängt von der Quelle des Tracks ab:

Track aus einem <track>-Element: Der Wert entspricht dem id-Attribut des Elements. Fehlt das Attribut, ist er ein leerer String.
In die Mediendatei eingebettete Tracks (z. B. in MP4 oder WebM): Der Browser vergibt die ID aus den Container-Daten, sofern das Format eine solche Kennung vorsieht.
Track aus HTMLMediaElement.addTextTrack(): Die ID ist immer ein leerer String und lässt sich nicht nachträglich setzen.

Die Eigenschaft ist schreibgeschützt. Nützlich ist sie vor allem für eigene Player-Oberflächen, zum Beispiel für Sprachauswahl-Menüs, die jeden Track über eine feste Kennung ansprechen, statt über seine Position in der Liste. Die Position kann sich nämlich ändern, wenn Tracks hinzukommen oder entfernt werden.

Rückgabewert

Typ

string

Beschreibung

Die ID des Tracks: das id-Attribut des <track>-Elements oder eine vom Browser vergebene Kennung. Gibt es keine ID, ist der Wert ein leerer String "".

Beispiele

IDs aller Tracks eines Videos auslesen

// HTML:
// <video id="player" src="film.mp4">
//   <track id="sub-de" kind="subtitles" srclang="de" label="Deutsch" src="de.vtt">
//   <track id="sub-en" kind="subtitles" srclang="en" label="English" src="en.vtt">
// </video>

const video = document.getElementById('player');

for (const track of video.textTracks) {
  console.log(`${track.id} → ${track.label} (${track.language})`);
}

sub-de → Deutsch (de) sub-en → English (en)

Untertitel per ID gezielt einschalten

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

const showSubtitles = (trackId) => {
  for (const track of video.textTracks) {
    // Nur der gewünschte Track wird angezeigt, alle anderen deaktiviert
    track.mode = track.id === trackId ? 'showing' : 'disabled';
  }
};

// Alternativ direkt über die TextTrackList
const de = video.textTracks.getTrackById('sub-de');
console.log(de?.id);

showSubtitles('sub-de');

sub-de

Per Skript erzeugter Track hat keine ID

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

const track = video.addTextTrack('captions', 'Live-Untertitel', 'de');
console.log(JSON.stringify(track.id)); // leerer String

// Schreiben wird ignoriert (im strict mode: TypeError)
try {
  track.id = 'live';
} catch (err) {
  console.log(err.name);
}
console.log(JSON.stringify(track.id));

"" TypeError ""

Menü zur Sprachauswahl aus Track-IDs aufbauen

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

const buildMenu = () => {
  select.replaceChildren(new Option('Aus', ''));
  for (const track of video.textTracks) {
    if (track.kind !== 'subtitles' || !track.id) continue; // Tracks ohne ID überspringen
    select.add(new Option(track.label || track.id, track.id));
  }
};

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

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

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an track.id wird ignoriert, im strict mode (z. B. in ES-Modulen) wirft sie einen TypeError. Um die ID eines <track>-Elements zu ändern, setzen Sie stattdessen trackElement.id.
Leerer String statt null: Fehlt eine ID, ist der Wert "". Prüfen Sie deshalb auf Leerstring, nicht auf null oder undefined.
addTextTrack(): Auf diesem Weg erzeugte Tracks haben immer eine leere ID. Wenn Sie die Tracks unterscheiden müssen, speichern Sie eine eigene Referenz auf das Objekt oder verwenden Sie label.
Eindeutigkeit ist nicht garantiert: Bei eingebetteten Tracks kommen die IDs aus dem Container-Format. Gibt es mehrere Tracks mit derselben ID, liefert getTrackById() nur den ersten Treffer.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Ob und wie IDs für eingebettete Tracks vergeben werden, kann je nach Browser und Medienformat unterschiedlich sein.

Siehe auch

TextTrack.kind TextTrack.mode TextTrack.cues TextTrack.label TextTrack.language