VTTCue.line — Eigenschaft · JavaScript-Referenz

Signatur

VTTCue.line

Beschreibung

Die Eigenschaft line des VTTCue-Interfaces legt fest, wo ein Untertitel- oder Caption-Cue im Video angezeigt wird. Bei horizontalem Text (Standard) bestimmt sie die vertikale Position, bei vertikalem Text (vertical = "rl" oder "lr") die horizontale Position. Sie entspricht der Cue-Einstellung line: in einer WebVTT-Datei, z. B. line:0, line:-1 oder line:90%.

Wie der Wert gedeutet wird, hängt von snapToLines ab:

snapToLines === true (Standard): line ist eine Zeilennummer. 0 ist die erste Zeile oben, 1 die zweite usw.; negative Werte zählen von unten, -1 ist also die letzte Zeile.
snapToLines === false: line ist ein Prozentwert zwischen 0 und 100, gemessen von der oberen (bzw. je nach Schreibrichtung linken/rechten) Kante des Videobereichs.
"auto" (Standardwert): Der Browser wählt die Position selbst, üblicherweise unten im Video, und stapelt mehrere gleichzeitig sichtbare Cues so, dass sie sich nicht überlappen.

Welcher Teil der Cue-Box an der berechneten Position ausgerichtet wird, steuert lineAlign ("start", "center", "end"). Mit line setzt man Untertitel zum Beispiel nach oben, wenn unten im Bild eingeblendeter Text (Bauchbinden, Anzeigen) nicht verdeckt werden soll, oder um Sprecher räumlich zu trennen.

Parameter

Name	Typ	Default	Beschreibung
$value	number \| "auto"	"auto"	Neuer Wert beim Setzen: eine Zahl (Zeilennummer oder Prozentwert, abhängig von `snapToLines`) oder der String `"auto"`.

Rückgabewert

Typ

number | "auto"

Beschreibung

Die aktuelle Zeilenposition als Zahl oder "auto", wenn der Browser die Position automatisch bestimmt.

Beispiele

Untertitel am oberen Rand anzeigen (Zeilennummer)

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

const cue = new VTTCue(1, 5, 'Hinweis: Dieser Text steht oben.');
cue.snapToLines = true; // Standard – line ist eine Zeilennummer
cue.line = 0;           // erste Zeile oben
track.addCue(cue);

console.log(cue.line);

Letzte Zeile von unten mit negativem Wert

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

const cue = new VTTCue(0, 4, '[Musik]');
cue.line = -1; // letzte Zeile, von unten gezählt
track.addCue(cue);

console.log(cue.line, cue.snapToLines);

-1 true

Prozentuale Position mit lineAlign

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

const cue = new VTTCue(2, 6, 'Sprecher B (Mitte des Bildes)');
cue.snapToLines = false; // line wird als Prozent gedeutet
cue.line = 50;           // 50 % von oben
cue.lineAlign = 'center';// Mitte der Cue-Box auf 50 % ausrichten
track.addCue(cue);

console.log(`${cue.line}% / ${cue.lineAlign}`);

50% / center

Position zur Laufzeit ändern und zurücksetzen

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

// Alle Cues nach oben verschieben, solange eine Einblendung unten läuft
const moveCues = (top) => {
  for (const cue of track.cues ?? []) {
    if (cue instanceof VTTCue) {
      cue.line = top ? 0 : 'auto';
    }
  }
};

moveCues(true);
setTimeout(() => moveCues(false), 10000);
console.log(track.cues?.[0]?.line);

// Wichtig · Fallstricke

Abhängigkeit von snapToLines: Derselbe Wert bedeutet je nach Flag etwas ganz anderes: line = 90 ist bei snapToLines = true die 91. Zeile, also meist außerhalb des Bildes, bei false dagegen 90 % von oben. Setzen Sie snapToLines deshalb immer ausdrücklich zusammen mit line.
Negative Werte sind nur im Zeilenmodus sinnvoll. Im Prozentmodus sollten Werte zwischen 0 und 100 liegen, sonst kann der Cue außerhalb des sichtbaren Bereichs landen.
Werte aus WebVTT-Dateien: line:90% setzt beim Einlesen automatisch snapToLines = false, line:-1 dagegen snapToLines = true.
Der Browser kann Cues trotzdem verschieben, um Überlappungen zu vermeiden, vor allem im Zeilenmodus. Eine pixelgenaue Position ist deshalb nicht garantiert.
Änderungen an einem Cue, der gerade angezeigt wird, übernehmen Browser in der Regel sofort. Bei älteren Browsern kann ein erneutes Zeichnen erst beim nächsten Cue-Wechsel erfolgen.
Kompatibilität: VTTCue und line werden von Chrome, Edge, Firefox und Safari unterstützt. Eigene Player mit CSS-Untertiteln (::cue) werten line nicht automatisch aus.

Siehe auch

VTTCue VTTCue.snapToLines VTTCue.lineAlign VTTCue.position VTTCue.vertical TextTrack.addCue() HTMLMediaElement.addTextTrack()