VTTRegion — Schnittstelle · JavaScript-Referenz

Signatur

interface VTTRegion

Beschreibung

VTTRegion gehört zur WebVTT API und legt einen festen Bereich innerhalb des Videobilds fest, in dem Untertitel (VTTCue) angezeigt werden. Ein Cue wird einer Region zugeordnet, indem man sie seiner Eigenschaft cue.region zuweist. Mehrere Cues können dieselbe Region nutzen, zum Beispiel für Dialoge verschiedener Sprecher links und rechts oder für Live-Untertitel, die zeilenweise nach oben rollen („Roll-up“-Untertitel).

Die Größe der Region wird über width (in Prozent der Videobreite) und lines (Höhe in Textzeilen) festgelegt. Die Position ergibt sich aus zwei Ankerpunkten: regionAnchorX/regionAnchorY bestimmen einen Punkt innerhalb der Region (in Prozent), viewportAnchorX/viewportAnchorY den Punkt im Video, auf den dieser Anker gelegt wird. Mit scroll = "up" werden neue Zeilen unten angefügt und ältere nach oben herausgeschoben.

Wichtige Eigenschaften:

id (string): Kennung der Region, Standard "".
width (number): Breite in Prozent (0–100), Standard 100.
lines (number): Höhe in Zeilen, Standard 3.
regionAnchorX, regionAnchorY (number): Anker innerhalb der Region in Prozent, Standard 0 bzw. 100.
viewportAnchorX, viewportAnchorY (number): Anker im Video in Prozent, Standard 0 bzw. 100.
scroll ("" | "up"): Rollverhalten, Standard "" (kein Rollen).

Regionen lassen sich per JavaScript erzeugen oder direkt in einer .vtt-Datei mit einem REGION-Block definieren; Cues verweisen dort dann mit der Einstellung region:ID darauf.

Parameter

Name	Typ	Default	Beschreibung
$(keine)	—		Der Konstruktor `new VTTRegion()` hat keine Parameter. Alle Eigenschaften werden nach dem Erzeugen gesetzt.

Rückgabewert

Typ

VTTRegion

Beschreibung

Eine neue Region mit Standardwerten (volle Breite, 3 Zeilen, unten links verankert, kein Rollen).

Beispiele

Region erzeugen und einem Cue zuweisen

const video = document.querySelector('video');
const track = video.addTextTrack('subtitles', 'Deutsch', 'de');
track.mode = 'showing';

// Region: 40 % breit, 3 Zeilen, oben rechts im Video
const region = new VTTRegion();
region.id = 'sprecher-rechts';
region.width = 40;
region.lines = 3;
region.regionAnchorX = 100; // rechter Rand der Region ...
region.regionAnchorY = 0;   // ... oben
region.viewportAnchorX = 95; // liegt bei 95 % Videobreite
region.viewportAnchorY = 5;  // und 5 % Videohöhe

const cue = new VTTCue(1, 4, 'Hallo, wer ist da?');
cue.region = region;
track.addCue(cue);

console.log(cue.region.id);

sprecher-rechts

Roll-up-Untertitel für Live-Transkription

const video = document.querySelector('video');
const track = video.addTextTrack('captions', 'Live', 'de');
track.mode = 'showing';

const rollup = new VTTRegion();
rollup.width = 80;
rollup.lines = 2;
rollup.regionAnchorX = 50;
rollup.regionAnchorY = 100;
rollup.viewportAnchorX = 50;
rollup.viewportAnchorY = 90;
rollup.scroll = 'up'; // neue Zeilen schieben alte nach oben

const zeilen = ['Willkommen zur Konferenz.', 'Heute geht es um WebVTT.', 'Beginnen wir mit Regionen.'];
zeilen.forEach((text, i) => {
  const cue = new VTTCue(i * 2, i * 2 + 5, text);
  cue.region = rollup;
  track.addCue(cue);
});

console.log(rollup.scroll, rollup.lines);

up 2

Regionen aus einer .vtt-Datei auslesen

// untertitel.vtt:
// WEBVTT
//
// REGION
// id:links width:40% lines:3 regionanchor:0%,100% viewportanchor:5%,90% scroll:up
//
// 00:00:01.000 --> 00:00:04.000 region:links
// Guten Tag!

const trackEl = document.querySelector('track');
trackEl.addEventListener('load', () => {
  for (const cue of trackEl.track.cues) {
    if (cue.region) {
      const { id, width, lines, scroll } = cue.region;
      console.log(id, width, lines, scroll);
    }
  }
});

links 40 3 up

Funktionserkennung mit Fallback

const cue = new VTTCue(0, 3, 'Untertitel');

if ('VTTRegion' in window) {
  const region = new VTTRegion();
  region.width = 50;
  cue.region = region;
} else {
  // Fallback: Position direkt am Cue setzen
  cue.line = -2;
  cue.size = 50;
}
console.log('region' in cue ? 'Regionen unterstützt' : 'Fallback aktiv');

Regionen unterstützt

// Wichtig · Fallstricke

Browser-Kompatibilität: VTTRegion wird von Firefox und Safari unterstützt, in Chromium-Browsern (Chrome, Edge) aber nicht oder nur experimentell. Immer per 'VTTRegion' in window prüfen und einen Fallback über VTTCue.line, position und size vorsehen.
Wertebereiche: Wird width, einer der Anker-Werte außerhalb von 0–100 oder für lines ein negativer Wert gesetzt, wirft der Browser eine IndexSizeError-DOMException.
scroll akzeptiert nur "" und "up"; andere Werte werden ignoriert.
Einige Cue-Einstellungen wie vertical oder eine explizite line-Position stehen im Konflikt mit Regionen – laut Spezifikation wird der Cue dann ohne Region dargestellt.
Änderungen an einer Region wirken auf alle Cues, die sie verwenden. Wer Cues unabhängig voneinander platzieren will, braucht getrennte Region-Objekte.
Wie Untertitel dargestellt werden, hängt auch von den Einstellungen der Nutzer und dem CSS-Pseudoelement ::cue ab; Regionen legen nur die Position fest, nicht die Gestaltung.

Siehe auch

VTTCue TextTrack TextTrackCue HTMLTrackElement HTMLMediaElement.addTextTrack() TextTrack.addCue()