VideoFrame.codedHeight — Eigenschaft · JavaScript-Referenz

Signatur

VideoFrame.codedHeight

Beschreibung

VideoFrame.codedHeight ist eine schreibgeschützte Eigenschaft der WebCodecs API. Sie gibt die Höhe des Frames in Pixeln an, so wie er im Speicher liegt. Dazu gehört auch nicht sichtbare Auffüllung (Padding), die Codecs oft einfügen, um auf Makroblock-Grenzen zu kommen. Ein 1080p-H.264-Video hat deshalb häufig eine codedHeight von 1088, weil 1088 durch 16 teilbar ist.

Die Eigenschaft brauchen Sie vor allem, wenn Sie direkt mit den Rohdaten eines Frames arbeiten, z. B. beim Anlegen von Puffern für VideoFrame.prototype.copyTo(), beim Berechnen von Plane-Größen oder beim Erzeugen eines neuen VideoFrame aus einem ArrayBuffer. Dort ist codedHeight zusammen mit codedWidth ein Pflichtwert im Init-Objekt.

Für die Anzeige ist codedHeight meist die falsche Größe. Der sichtbare Bereich steht in visibleRect. Die Höhe, mit der der Frame dargestellt werden soll (unter Berücksichtigung des Seitenverhältnisses), steht in displayHeight.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl ohne Vorzeichen: die kodierte Höhe des Frames in Pixeln. Wurde der Frame mit close() geschlossen, ist der Wert 0.

Beispiele

Kodierte und sichtbare Höhe vergleichen

// Frames aus einer Kamera lesen
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const reader = new MediaStreamTrackProcessor({ track }).readable.getReader();

const { value: frame } = await reader.read();
console.log('codedHeight:', frame.codedHeight);
console.log('visibleRect.height:', frame.visibleRect.height);
console.log('displayHeight:', frame.displayHeight);
frame.close();
track.stop();

codedHeight: 720 visibleRect.height: 720 displayHeight: 720

VideoFrame aus Rohdaten erzeugen (RGBA)

const width = 320;
const height = 240;
const pixels = new Uint8ClampedArray(width * height * 4).fill(255); // weißes Bild

const frame = new VideoFrame(pixels, {
  format: 'RGBA',
  codedWidth: width,
  codedHeight: height, // Pflichtangabe bei Rohdaten
  timestamp: 0
});

console.log(frame.codedWidth, frame.codedHeight);
frame.close();
console.log(frame.codedHeight); // nach close()

320 240 0

Padding eines dekodierten Frames erkennen

const decoder = new VideoDecoder({
  output: (frame) => {
    const padding = frame.codedHeight - frame.visibleRect.height;
    if (padding > 0) {
      console.log(`Frame hat ${padding} Zeilen Padding unten`);
    }
    frame.close();
  },
  error: (e) => console.error(e)
});

decoder.configure({ codec: 'avc1.42E01F', codedWidth: 1920, codedHeight: 1080 });
// decoder.decode(encodedChunk) …

Frame hat 8 Zeilen Padding unten

// Wichtig · Fallstricke

Kodierte ist nicht gleich sichtbare Höhe: Wegen des Paddings kann codedHeight größer sein als die sichtbare Höhe. Zum Zeichnen oder für Layoutberechnungen nehmen Sie visibleRect.height oder displayHeight, sonst erscheinen am Rand leere oder grüne Streifen.
Puffergrößen: Bei Formaten mit Farb-Unterabtastung (z. B. I420, NV12) haben die Chroma-Planes nur die halbe Höhe. Die benötigte Puffergröße berechnen Sie zuverlässiger mit frame.allocationSize() statt von Hand aus codedHeight.
Nach close(): Die Eigenschaft liefert dann 0. Lesen Sie den Wert also vor dem Schließen aus.
Kompatibilität: WebCodecs gibt es nur in sicheren Kontexten (HTTPS). Unterstützt wird die API in Chromium-Browsern ab Version 94, in Firefox ab 130 und in Safari ab 16.4 (anfangs mit Einschränkungen). MediaStreamTrackProcessor aus Beispiel 1 ist nicht in allen Browsern vorhanden. Prüfen Sie die Unterstützung mit 'VideoFrame' in window.

Siehe auch

VideoFrame.codedRect VideoFrame.codedWidth VideoFrame.displayHeight VideoFrame.colorSpace VideoFrame.duration