Signatur
Beschreibung
Die schreibgeschützte Eigenschaft length einer TextTrackList gibt an, wie viele Textspuren einem Medienelement (<video> oder <audio>) gerade zugeordnet sind. Eine solche Liste bekommt man über HTMLMediaElement.textTracks. Jeder Eintrag ist ein TextTrack, also z. B. Untertitel, Bildunterschriften, Beschreibungen, Kapitel oder Metadaten.
Gezählt werden alle Spuren, die über <track>-Elemente im Markup eingebunden sind, die per HTMLMediaElement.addTextTrack() im Skript angelegt wurden und die in der Mediendatei selbst stecken (In-Band-Spuren, sofern der Browser sie unterstützt). Wenn keine Spur vorhanden ist, liefert length den Wert 0.
Meist braucht man length, um mit einer klassischen for-Schleife über die Spuren zu laufen (Zugriff per Index wie textTracks[i]) oder um zu prüfen, ob sich überhaupt eine Untertitel-Auswahl lohnt. Der Wert ist live: Er ändert sich, sobald Spuren hinzukommen oder wegfallen. Das signalisieren die Events addtrack und removetrack.
Rückgabewert
TextTrack-Einträge in der Liste. Ist keine Spur vorhanden, ist der Wert 0.Beispiele
Anzahl der Textspuren eines Videos ermitteln
// 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');
console.log(`Textspuren: ${video.textTracks.length}`);Untertitel-Menü nur bei vorhandenen Spuren aufbauen
const video = document.querySelector('video');
const menu = document.querySelector('#untertitel-menue');
const tracks = video.textTracks;
if (tracks.length === 0) {
menu.hidden = true;
} else {
for (let i = 0; i < tracks.length; i++) {
const track = tracks[i];
if (track.kind !== 'subtitles' && track.kind !== 'captions') continue;
const button = document.createElement('button');
button.textContent = track.label || track.language;
button.addEventListener('click', () => {
for (let j = 0; j < tracks.length; j++) {
tracks[j].mode = j === i ? 'showing' : 'disabled';
}
});
menu.append(button);
}
}Live-Änderung von length beobachten
const video = document.querySelector('video');
const tracks = video.textTracks;
tracks.addEventListener('addtrack', () => {
console.log(`Neue Spur – jetzt ${tracks.length} Spur(en)`);
});
console.log('Vorher:', tracks.length);
const meta = video.addTextTrack('metadata', 'Kapitelmarken', 'de');
console.log('Direkt danach:', tracks.length);// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
textTracks.length = 0wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einenTypeErroraus. Spuren lassen sich damit also nicht entfernen. Dafür muss man das zugehörige<track>-Element aus dem DOM nehmen. - Kein echtes Array:
TextTrackListhat keine Methoden wiemap()oderfilter(). Um diese zu nutzen, wandelt man die Liste vorher mitArray.from(video.textTracks)oder[...video.textTracks]in ein Array um. - Live-Wert: Wenn während einer Schleife Spuren hinzukommen oder entfernt werden, ändert sich
lengthmitten im Durchlauf. Wer eine feste Momentaufnahme braucht, speichert den Wert vorher in einer Variablen oder kopiert die Liste in ein Array. - Zeitpunkt:
<track>-Elemente aus dem Markup sind in der Regel sofort in der Liste. In-Band-Spuren aus dem Mediencontainer erscheinen dagegen oft erst nach dem Laden der Metadaten (loadedmetadata). Ob solche Spuren überhaupt unterstützt werden, ist von Browser zu Browser verschieden. - Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Im Internet Explorer gibt es die Eigenschaft ab Version 10.