VideoFrame.displayHeight — Eigenschaft · JavaScript-Referenz

Signatur

get VideoFrame.prototype.displayHeight

Beschreibung

Die schreibgeschützte Eigenschaft displayHeight gibt an, wie hoch ein VideoFrame bei der Anzeige dargestellt werden soll. Sie kann von der tatsächlichen Pixelhöhe (codedHeight) bzw. der Höhe des sichtbaren Bereichs (visibleRect.height) abweichen, etwa bei anamorphem Material mit nicht-quadratischen Pixeln.

Zusammen mit displayWidth beschreibt sie das Zielformat für das Rendering. Beim Zeichnen auf ein <canvas> mit drawImage() werden standardmäßig genau diese Anzeigeabmessungen verwendet. Deshalb solltest du die Canvas-Größe an displayWidth und displayHeight anpassen, damit das Bild nicht verzerrt wird.

Den Wert legst du beim Erzeugen über die Option displayHeight des Konstruktors new VideoFrame() fest. Wenn du ihn weglässt, übernimmt der Browser die Höhe von visibleRect. Bei dekodierten Frames aus einem VideoDecoder kommt der Wert aus der Decoder-Konfiguration (displayAspectHeight) bzw. aus dem Datenstrom.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl: die Anzeigehöhe in Pixeln. Bei einem geschlossenen Frame (nach close()) ist der Wert 0.

Beispiele

Anzeige- und Pixelhöhe vergleichen

const canvas = new OffscreenCanvas(640, 480);
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'teal';
ctx.fillRect(0, 0, 640, 480);

// Anamorphes Frame: 640x480 Pixel, angezeigt als 640x360
const frame = new VideoFrame(canvas, {
  timestamp: 0,
  displayWidth: 640,
  displayHeight: 360
});

console.log(frame.codedHeight);   // echte Pixelhöhe
console.log(frame.displayHeight); // Anzeigehöhe
frame.close();

480 360

Canvas passend zur Anzeigegröße zeichnen

const renderFrame = (frame, canvas) => {
  // Canvas an die Anzeigegröße anpassen, damit nichts verzerrt wird
  canvas.width = frame.displayWidth;
  canvas.height = frame.displayHeight;
  const ctx = canvas.getContext('2d');
  ctx.drawImage(frame, 0, 0, frame.displayWidth, frame.displayHeight);
  frame.close();
};

const decoder = new VideoDecoder({
  output: (frame) => renderFrame(frame, document.querySelector('canvas')),
  error: (e) => console.error('Decoder-Fehler:', e)
});

Frames einer Kamera auswerten

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const processor = new MediaStreamTrackProcessor({ track });
const reader = processor.readable.getReader();

const { value: frame } = await reader.read();
console.log(`Anzeige: ${frame.displayWidth}x${frame.displayHeight}`);
frame.close();
track.stop();

Anzeige: 1280x720

// Wichtig · Fallstricke

Nicht mit codedHeight verwechseln: codedHeight enthält auch Füllpixel des Codecs (z. B. 1088 statt 1080). Wenn du Pixeldaten mit copyTo() ausliest, gelten visibleRect bzw. codedHeight, nicht displayHeight.
Nach frame.close() gibt die Eigenschaft 0 zurück. Lies die Werte also aus, bevor du den Frame schließt.
Gibst du im Konstruktor nur displayWidth oder nur displayHeight an, wirft er einen TypeError. Beide Werte müssen zusammen angegeben werden.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert, im Strict Mode gibt es einen TypeError.
Kompatibilität: Die WebCodecs-API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, in Fenstern und Workern. Chromium-Browser unterstützen sie vollständig, Firefox erst ab neueren Versionen, Safari nur teilweise. Prüfe vorab mit 'VideoFrame' in globalThis, ob sie vorhanden ist.

Siehe auch

VideoFrame VideoFrame.displayWidth VideoFrame.codedHeight VideoFrame.visibleRect VideoFrame.close() VideoDecoder VideoFrame.flip