VideoFrame.codedRect — Eigenschaft · JavaScript-Referenz

Signatur

get VideoFrame.codedRect

Beschreibung

Die schreibgeschützte Eigenschaft codedRect gehört zur VideoFrame-Schnittstelle der WebCodecs-API. Sie liefert ein DOMRectReadOnly, dessen x und y immer 0 sind und dessen width und height den Werten von VideoFrame.codedWidth und VideoFrame.codedHeight entsprechen. Damit beschreibt es den kompletten Pixelpuffer des Frames, so wie er im Speicher liegt, und nicht nur den sichtbaren Ausschnitt.

Diesen Unterschied muss man kennen: Videocodecs arbeiten oft mit Blockgrößen von 16 × 16 Pixeln. Ein Full-HD-Video wird deshalb häufig mit 1920 × 1088 Pixeln kodiert, sichtbar sind aber nur 1920 × 1080. Den sichtbaren Bereich gibt visibleRect an, den gesamten Speicherbereich codedRect. Mit displayWidth/displayHeight kommt noch die Darstellungsgröße dazu, die bei nicht quadratischen Pixeln abweichen kann.

In der Praxis braucht man codedRect vor allem, wenn man mit VideoFrame.copyTo() oder allocationSize() die vollständigen Rohdaten eines Frames kopieren will (einschließlich Padding), wenn man eigene Puffer-Layouts berechnet oder wenn man beim Debuggen von Decodern prüfen will, ob kodierte und sichtbare Größe übereinstimmen.

Rückgabewert

Typ

DOMRectReadOnly | null

Beschreibung

Ein DOMRectReadOnly mit x = 0, y = 0, width = codedWidth und height = codedHeight. Wurde der Frame mit close() geschlossen, ist der Wert null.

Beispiele

codedRect eines Frames aus einem Canvas auslesen

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

const frame = new VideoFrame(canvas, { timestamp: 0 });
const { x, y, width, height } = frame.codedRect;
console.log(`codedRect: ${x},${y} ${width}x${height}`);

frame.close();

codedRect: 0,0 640x480

Kodierte und sichtbare Größe vergleichen (Padding erkennen)

// Rohes I420-Bild mit 1920x1088 Pixeln, sichtbar sind nur 1920x1080
const codedWidth = 1920;
const codedHeight = 1088;
const data = new Uint8Array(codedWidth * codedHeight * 1.5);

const frame = new VideoFrame(data, {
  format: 'I420',
  codedWidth,
  codedHeight,
  timestamp: 0,
  visibleRect: { x: 0, y: 0, width: 1920, height: 1080 }
});

const coded = frame.codedRect;
const visible = frame.visibleRect;
console.log('coded:', coded.width, 'x', coded.height);
console.log('visible:', visible.width, 'x', visible.height);
console.log('Padding-Zeilen:', coded.height - visible.height);

frame.close();

coded: 1920 x 1088 visible: 1920 x 1080 Padding-Zeilen: 8

Vollständigen Pixelpuffer mit copyTo() kopieren

const copyFullFrame = async (frame) => {
  // rect: codedRect = gesamter Speicherbereich statt nur visibleRect
  const options = { rect: frame.codedRect };
  const size = frame.allocationSize(options);
  const buffer = new Uint8Array(size);
  const layout = await frame.copyTo(buffer, options);
  return { buffer, layout };
};

const canvas = new OffscreenCanvas(320, 240);
canvas.getContext('2d').fillRect(0, 0, 320, 240);
const frame = new VideoFrame(canvas, { timestamp: 0 });

const { buffer, layout } = await copyFullFrame(frame);
console.log(frame.format, buffer.byteLength, layout.length);
frame.close();

RGBA 307200 1 (Format kann je nach Browser z. B. auch BGRA sein)

Nach close() ist codedRect null

const canvas = new OffscreenCanvas(100, 100);
canvas.getContext('2d').fillRect(0, 0, 100, 100);
const frame = new VideoFrame(canvas, { timestamp: 0 });

console.log(frame.codedRect?.width);
frame.close();
console.log(frame.codedRect);

100 null

// Wichtig · Fallstricke

Nicht mit visibleRect verwechseln: Wer ein Bild anzeigen oder weiterverarbeiten will, braucht meist visibleRect bzw. displayWidth/displayHeight. codedRect kann Padding-Pixel mit undefiniertem Inhalt enthalten, die z. B. als grüne oder schwarze Ränder auftauchen.
Geschlossene Frames: Nach frame.close() gibt codedRect null zurück. Beim Zugriff auf .width fliegt dann ein TypeError, also Optional Chaining (?.) verwenden oder vorher prüfen.
Immer neu: Jeder Zugriff liefert ein neues DOMRectReadOnly. Deshalb gilt frame.codedRect === frame.codedRect als false. Zum Vergleichen die einzelnen Werte heranziehen.
Unterabtastung (Subsampling): Bei Formaten wie I420 oder NV12 sind die Farbebenen (Chroma) nur halb so groß. codedRect beschreibt die Helligkeitsebene (Luma). Die tatsächlichen Ebenen-Layouts liefert der Rückgabewert von copyTo().
Kompatibilität: Teil der WebCodecs-API und nur in sicheren Kontexten (HTTPS) verfügbar, im Fenster und in Dedicated Workers. Chromium ab Version 94, Safari ab 16.4, Firefox ab 130. Vorher mit 'VideoFrame' in globalThis prüfen, ob die API vorhanden ist.

Siehe auch

VideoFrame VideoFrame.codedWidth VideoFrame.codedHeight VideoFrame.visibleRect VideoFrame.copyTo() VideoFrame.allocationSize() DOMRectReadOnly