Signatur
Beschreibung
Die Eigenschaft text eines VTTCue-Objekts enthält den Inhalt eines Untertitels, einer Bildunterschrift oder eines Kapitels als unverarbeiteten String. Es ist genau der Text, der in einer WebVTT-Datei zwischen der Zeitangabe und der nächsten Leerzeile steht. Mehrzeilige Cues sind durch \n getrennt.
Die Eigenschaft lässt sich lesen und schreiben. Beim Lesen bekommen Sie den Text zum Beispiel für ein eigenes Untertitel-Overlay, ein durchsuchbares Transkript oder eine Protokollierung. Wenn Sie einen neuen Wert setzen, zeigt der Browser den geänderten Inhalt sofort an, auch wenn der Cue gerade aktiv ist. So lassen sich Untertitel zur Laufzeit übersetzen, korrigieren oder ergänzen.
Der Wert kann WebVTT-Auszeichnungen enthalten, zum Beispiel <b>, <i>, <u>, <c.klasse>, <v Sprecher>, <lang de> und Zeitstempel wie <00:00:05.000>. text liefert diese Tags unverändert als Zeichen zurück. Wenn Sie den Inhalt als sicheres, bereits geparstes DOM brauchen, verwenden Sie VTTCue.getCueAsHTML().
Rückgabewert
\n). Wenn Sie einen String zuweisen, wird der angezeigte Inhalt ersetzt.Beispiele
Cue per Skript anlegen und Text auslesen
const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';
const cue = new VTTCue(0, 4, 'Willkommen zum <b>Tutorial</b>!');
track.addCue(cue);
console.log(cue.text);Aktiven Untertitel in ein eigenes Overlay schreiben
const video = document.querySelector('video');
const overlay = document.querySelector('#untertitel');
const track = video.textTracks[0];
// 'hidden': Cues werden geladen, der Browser zeigt sie aber nicht selbst an
track.mode = 'hidden';
track.addEventListener('cuechange', () => {
overlay.replaceChildren();
for (const cue of track.activeCues) {
// Sicher: das geparste DOM statt innerHTML mit cue.text verwenden
overlay.append(cue.getCueAsHTML());
}
});Untertitel zur Laufzeit ersetzen
const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'showing';
const korrekturen = new Map([
['Hallo Welt', 'Hallo, Welt!'],
['Tschüs', 'Auf Wiedersehen']
]);
video.addEventListener('loadeddata', () => {
for (const cue of track.cues ?? []) {
if (korrekturen.has(cue.text)) {
cue.text = korrekturen.get(cue.text);
}
}
});Transkript ohne Markup erzeugen
const cue = new VTTCue(10, 14, '<v Anna>Das ist <i>wirklich</i> wichtig.\nMerkt euch das!');
// WebVTT-Tags entfernen, Zeilenumbrüche durch Leerzeichen ersetzen
const reinText = cue.text.replace(/<[^>]+>/g, '').replace(/\n/g, ' ');
console.log(reinText);// Wichtig · Fallstricke
- XSS-Gefahr: Setzen Sie
cue.textnie direkt ininnerHTMLein. Untertiteldateien stammen oft aus fremden Quellen und können manipuliert sein. Verwenden Sie stattdessengetCueAsHTML(), das nur die erlaubten WebVTT-Tags in sicheres DOM umwandelt, odertextContent. - Markup wird nicht entfernt:
textenthält alle Tags und Zeitstempel. Für einen reinen Text müssen Sie das Markup selbst herausfiltern. - Zugriff auf Cues: Cues aus einem
<track>-Element stehen erst zur Verfügung, wenn der Modus des Tracks"hidden"oder"showing"ist und die Datei geladen wurde. Im Modus"disabled"isttrack.cuesnull. - CORS: Liegt die VTT-Datei auf einer anderen Domain, braucht das Media-Element das Attribut
crossoriginund der Server passende CORS-Header. Sonst wird die Datei nicht geladen. - Kompatibilität:
VTTCueundtextwerden von allen modernen Browsern unterstützt. Ältere Versionen von Edge (vor Chromium) und Internet Explorer kannten nurTextTrackCuemit eingeschränkten Funktionen.