Signatur
Beschreibung
Die Eigenschaft id des Interfaces VTTRegion ist ein String, der eine Region für Untertitel eindeutig benennt. Eine Region ist ein Teilbereich des Videobilds, in dem Cues angezeigt werden – zum Beispiel ein Bereich unten links, in dem die Zeilen nach oben weiterlaufen (Roll-up-Untertitel).
In einer WebVTT-Datei legt ein REGION-Block die Region an, etwa mit der Zeile id:sprecher1. Einzelne Cues verweisen dann mit der Cue-Einstellung region:sprecher1 auf diese Region. Die Eigenschaft id enthält genau diesen Bezeichner. Nach dem Parsen können Sie damit Regionen im Skript wiedererkennen und zuordnen.
Wenn Sie eine Region mit new VTTRegion() selbst erzeugen, ist id zunächst ein leerer String. Sie können einen beliebigen String zuweisen. Für die Zuordnung per Skript braucht es die id nicht, denn dort weisen Sie das Region-Objekt direkt über VTTCue.region zu. Die id hilft aber beim Debuggen, beim Serialisieren und beim Wiederfinden von Regionen.
Rückgabewert
"". Die Eigenschaft ist les- und schreibbar.Beispiele
Region per Skript anlegen und benennen
const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';
if ('VTTRegion' in window) {
const region = new VTTRegion();
console.log(JSON.stringify(region.id)); // Standardwert
region.id = 'sprecher-links';
region.width = 40; // Prozent der Videobreite
region.lines = 3;
region.scroll = 'up';
const cue = new VTTCue(0, 5, 'Hallo, willkommen!');
cue.region = region;
track.addCue(cue);
console.log(cue.region.id);
} else {
console.warn('VTTRegion wird in diesem Browser nicht unterstützt.');
}Regionen aus einer WebVTT-Datei auslesen
// untertitel.vtt:
// WEBVTT
//
// REGION
// id:fred
// width:40%
// lines:3
// regionanchor:0%,100%
// viewportanchor:10%,90%
// scroll:up
//
// 00:00:00.000 --> 00:00:04.000 region:fred align:left
// Hallo, ich bin Fred.
const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
for (const cue of trackEl.track.cues) {
const regionId = cue.region?.id ?? '(keine Region)';
console.log(`${cue.startTime}s: "${cue.text}" → ${regionId}`);
}
});Cues nach Region gruppieren
const groupByRegion = (textTrack) => {
const groups = new Map();
for (const cue of textTrack.cues ?? []) {
const key = cue.region?.id || 'standard';
if (!groups.has(key)) groups.set(key, []);
groups.get(key).push(cue.text);
}
return groups;
};
const video = document.querySelector('video');
const textTrack = video.textTracks[0];
textTrack.mode = 'hidden'; // Cues laden, ohne sie anzuzeigen
console.log(groupByRegion(textTrack));// Wichtig · Fallstricke
- Browser-Unterstützung:
VTTRegiongibt es in Firefox und Safari. Chromium-Browser (Chrome, Edge) unterstützen es standardmäßig nicht oder nur teilweise. Prüfen Sie die Unterstützung vorher mit'VTTRegion' in window. - Keine Eindeutigkeitsprüfung: Der Browser prüft nicht, ob eine per Skript gesetzte
ideindeutig ist. Wer mehrere Regionen gleich benennt, verwechselt sie beim späteren Auslesen leicht. - Verknüpfung per Objekt, nicht per String: Wenn Sie
idnachträglich ändern, bleibt ein Cue trotzdem mit seiner Region verbunden.VTTCue.regionverweist auf das Objekt selbst, nicht auf den Namen. - In WebVTT-Dateien darf die
idkeine Leerzeichen und keine Zeichenfolge-->enthalten. Sonst wird die Einstellung ignoriert. - Cues sind erst verfügbar, wenn der Track geladen ist, also nach dem
load-Event des<track>-Elements. Außerdem mussmodeauf'hidden'oder'showing'stehen. Vorher istcue.regionnicht zugänglich.