VTTCue.region — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.region

Beschreibung

Die Eigenschaft region der Schnittstelle VTTCue verweist auf ein VTTRegion-Objekt. Eine Region ist ein rechteckiger Teilbereich des Videos mit eigener Breite, Zeilenanzahl, Ankerpunkten und optionalem Scroll-Verhalten. Gehört eine Cue zu einer Region, rendert der Browser sie in diesem Bereich statt nach den normalen Positionsregeln (line, position, size).

Regionen braucht man vor allem für Roll-up-Untertitel, wie sie bei Live-Übertragungen üblich sind: Mit scroll = "up" rutschen neue Zeilen von unten nach und ältere Zeilen scrollen nach oben aus dem Bereich. Außerdem kann man so mehrere Sprecher in getrennten Bildbereichen darstellen, z. B. einen links oben und einen rechts unten.

In WebVTT-Dateien weist man die Region über die Cue-Einstellung region:ID zu. Per Skript setzt man cue.region direkt auf eine VTTRegion-Instanz. Mit null hebt man die Zuordnung wieder auf, dann gilt wieder die Standard-Positionierung.

Parameter

Name	Typ	Default	Beschreibung
$value	VTTRegion \| null	null	Beim Setzen: die `VTTRegion`, in der die Cue angezeigt werden soll, oder `null`, um die Zuordnung zu entfernen.

Rückgabewert

Typ

VTTRegion | null

Beschreibung

Die zugeordnete VTTRegion oder null, wenn die Cue keiner Region angehört.

Beispiele

Cue einer Region zuordnen

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

// Region im unteren linken Bildbereich
const region = new VTTRegion();
region.id = 'sprecher-links';
region.width = 40;            // 40 % der Videobreite
region.lines = 3;
region.regionAnchorX = 0;
region.regionAnchorY = 100;
region.viewportAnchorX = 5;
region.viewportAnchorY = 90;

const cue = new VTTCue(0, 5, 'Hallo zusammen!');
cue.region = region;
track.addCue(cue);

console.log(cue.region.id);

sprecher-links

Roll-up-Untertitel für einen Live-Stream

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

const rollUp = new VTTRegion();
rollUp.width = 80;
rollUp.lines = 3;
rollUp.scroll = 'up'; // neue Zeilen schieben ältere nach oben

const zeilen = ['Willkommen zur Übertragung.', 'Gleich geht es los.', 'Die Teams laufen ein.'];
zeilen.forEach((text, i) => {
  const cue = new VTTCue(i * 2, i * 2 + 6, text);
  cue.region = rollUp;
  track.addCue(cue);
});

console.log([...track.cues].every(c => c.region === rollUp));

true

Region prüfen und Zuordnung aufheben

const track = document.querySelector('video').textTracks[0];

for (const cue of track.cues) {
  if (cue instanceof VTTCue && cue.region) {
    console.log(`Cue ${cue.id || '(ohne ID)'} liegt in Region "${cue.region.id}"`);
    cue.region = null; // zurück zur normalen Positionierung
  }
}

// Wichtig · Fallstricke

Browser-Unterstützung: VTTCue gibt es in allen modernen Browsern. VTTRegion und damit auch die Darstellung von Regionen unterstützen Chromium und Safari. Firefox unterstützt sie nur eingeschränkt oder hinter der Einstellung media.webvtt.regions.enabled. Vor der Nutzung sollte man die Unterstützung mit typeof VTTRegion !== 'undefined' prüfen.
Ist eine Region gesetzt, ignorieren die Browser meist die Einstellungen line, position und size der Cue ganz oder teilweise. Außerdem funktionieren Regionen nur bei horizontalem Text. Bei vertical ungleich "" wird die Region ignoriert.
Nur Objekte vom Typ VTTRegion oder null sind erlaubt. Andere Werte lösen einen TypeError aus.
Mehrere Cues können sich dasselbe VTTRegion-Objekt teilen. Ändert man dessen Eigenschaften, wirkt sich das auf alle diese Cues aus.
Der Wert lines der Region begrenzt, wie viele Zeilen gleichzeitig zu sehen sind. Überzählige Zeilen werden je nach scroll weggescrollt oder abgeschnitten.

Siehe auch

VTTCue VTTRegion VTTRegion.scroll VTTCue.line VTTCue.position TextTrack.addCue() ContactAddress.region