Signatur
Beschreibung
Die Eigenschaft textTracks gehört zur Media Source Extensions API (MSE). Sie liefert eine TextTrackList mit allen Textspuren (z. B. Untertitel, Bildunterschriften, Kapitel oder Metadaten), die aus den an diesen SourceBuffer angehängten Mediensegmenten stammen. Die Spuren entstehen, wenn ein Initialisierungssegment mit Textspuren über appendBuffer() eingelesen wird.
Nützlich ist die Eigenschaft vor allem in eigenen Streaming-Playern (adaptives Streaming mit fragmentiertem MP4 oder WebM), wenn man wissen möchte, aus welchem Puffer eine bestimmte Textspur stammt. Die gleichen Spuren tauchen zusätzlich in HTMLMediaElement.textTracks des zugehörigen <video>- oder <audio>-Elements auf, dort allerdings gemischt mit Spuren aus <track>-Elementen und anderen Puffern.
Die Liste ist schreibgeschützt: Die Eigenschaft selbst kann nicht neu zugewiesen werden. Die enthaltenen TextTrack-Objekte lassen sich aber normal steuern, z. B. über track.mode = "showing". Über die Ereignisse addtrack und removetrack der TextTrackList erfährt man, wann Spuren hinzukommen oder entfernt werden.
Rückgabewert
TextTrackList mit den TextTrack-Objekten dieses Puffers. Ist die Liste leer, enthält der Puffer (noch) keine Textspuren.Beispiele
Textspuren eines SourceBuffers auflisten (mit Feature-Erkennung)
const video = document.querySelector('video');
const mediaSource = new MediaSource();
video.src = URL.createObjectURL(mediaSource);
mediaSource.addEventListener('sourceopen', async () => {
const mime = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';
const sourceBuffer = mediaSource.addSourceBuffer(mime);
// Initialisierungssegment laden und anhängen
const init = await fetch('/media/init.mp4').then((r) => r.arrayBuffer());
sourceBuffer.appendBuffer(init);
sourceBuffer.addEventListener('updateend', () => {
if (!('textTracks' in sourceBuffer)) {
console.log('SourceBuffer.textTracks wird nicht unterstützt');
return;
}
for (const track of sourceBuffer.textTracks) {
console.log(`${track.kind}: ${track.label} (${track.language})`);
}
}, { once: true });
});Deutsche Untertitel automatisch einblenden
const showGermanSubtitles = (sourceBuffer) => {
const tracks = sourceBuffer.textTracks;
if (!tracks) return false;
let found = false;
for (const track of tracks) {
const isGerman = track.language === 'de' && track.kind === 'subtitles';
track.mode = isGerman ? 'showing' : 'disabled';
if (isGerman) found = true;
}
return found;
};
// Aufruf z. B. nach dem ersten 'updateend'
console.log(showGermanSubtitles(sourceBuffer));Auf neu hinzukommende Spuren reagieren
if (sourceBuffer.textTracks) {
sourceBuffer.textTracks.addEventListener('addtrack', (event) => {
const { track } = event;
console.log('Neue Textspur:', track.label || track.id);
track.mode = 'hidden'; // Cues laden, aber nicht anzeigen
track.addEventListener('cuechange', () => {
const cue = track.activeCues?.[0];
if (cue) console.log('Aktueller Cue:', cue.text);
});
});
}// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Eigenschaft ist in der MSE-Spezifikation definiert, wird aber von Chrome, Edge und Firefox nicht implementiert (Wert
undefined). Unterstützung gibt es höchstens in WebKit/Safari. Immer per'textTracks' in sourceBufferprüfen und aufvideo.textTracksausweichen. - Die Liste ist erst gefüllt, nachdem ein Initialisierungssegment mit Textspuren verarbeitet wurde – also frühestens nach dem ersten
updateend-Ereignis. - Wird der Puffer mit
MediaSource.removeSourceBuffer()entfernt, verschwinden seine Spuren auch ausHTMLMediaElement.textTracks. - Viele Streaming-Bibliotheken (hls.js, dash.js, Shaka Player) verarbeiten Untertitel nicht über In-Band-Spuren im
SourceBuffer, sondern laden WebVTT separat und erzeugen Spuren peraddTextTrack(). In diesem Fall bleibtsourceBuffer.textTracksleer. - In der Spezifikation ist die Eigenschaft als experimentell gekennzeichnet und kann sich noch ändern.