VideoFrame.codedWidth — Eigenschaft · JavaScript-Referenz

Signatur

VideoFrame.codedWidth

Beschreibung

Die schreibgeschützte Eigenschaft codedWidth gibt die Breite der Pixeldaten eines VideoFrame im Speicher an, und zwar so, wie der Decoder oder die Quelle sie erzeugt hat. Diese kodierte Breite kann größer sein als der tatsächlich sichtbare Bildbereich, weil Video-Codecs wie H.264 oder VP9 Bilder oft in Makroblöcken (z. B. 16×16 Pixel) verarbeiten und das Bild deshalb am Rand auffüllen.

Wichtig ist der Unterschied zu verwandten Eigenschaften:

codedWidth: volle Breite des Pixelpuffers mit Polsterung.
visibleRect.width: Breite des sichtbaren Ausschnitts innerhalb des kodierten Bildes.
displayWidth: Breite für die Anzeige, nachdem das Pixel-Seitenverhältnis berücksichtigt wurde.

codedWidth brauchen Sie vor allem, wenn Sie Rohdaten mit VideoFrame.copyTo() auslesen, Puffergrößen berechnen, einen VideoEncoder konfigurieren oder mit new VideoFrame(buffer, init) selbst Frames aus Pixeldaten erzeugen. In diesem Fall geben Sie codedWidth im Init-Objekt selbst an. Fürs Zeichnen auf ein Canvas nehmen Sie dagegen meist displayWidth.

Rückgabewert

Typ

number

Beschreibung

Eine positive ganze Zahl (unsigned long) mit der kodierten Breite in Pixeln. Ist der Frame geschlossen, wird 0 zurückgegeben.

Beispiele

Kodierte, sichtbare und Anzeige-Breite vergleichen

const decoder = new VideoDecoder({
  output: (frame) => {
    console.log('codedWidth:', frame.codedWidth);
    console.log('visibleRect.width:', frame.visibleRect.width);
    console.log('displayWidth:', frame.displayWidth);
    frame.close(); // Speicher sofort freigeben
  },
  error: (e) => console.error(e)
});

decoder.configure({ codec: 'avc1.42E01E', codedWidth: 1920, codedHeight: 1080 });
// ... decoder.decode(new EncodedVideoChunk({...}))

codedWidth: 1920 visibleRect.width: 1920 displayWidth: 1920 // Bei 1080p-H.264 ist oft codedHeight = 1088 statt 1080

Frame aus Rohdaten erzeugen

const width = 320;
const height = 240;
// RGBA: 4 Bytes pro Pixel
const pixels = new Uint8ClampedArray(width * height * 4).fill(255);

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

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

320 240 0

Frame aus einem Canvas und Encoder-Konfiguration

const canvas = document.querySelector('canvas');
const frame = new VideoFrame(canvas, { timestamp: performance.now() * 1000 });

const encoder = new VideoEncoder({
  output: (chunk) => console.log('Chunk:', chunk.byteLength, 'Bytes'),
  error: console.error
});

encoder.configure({
  codec: 'vp8',
  width: frame.codedWidth,
  height: frame.codedHeight
});

encoder.encode(frame);
frame.close();
await encoder.flush();

Chunk: 5123 Bytes

Puffergröße für copyTo() ermitteln

const readPixels = async (frame) => {
  // allocationSize() berücksichtigt Format und Polsterung
  const size = frame.allocationSize();
  const buffer = new Uint8Array(size);
  const layout = await frame.copyTo(buffer);
  console.log(`Breite ${frame.codedWidth}px, Stride Ebene 0: ${layout[0].stride}`);
  return buffer;
};

Breite 1920px, Stride Ebene 0: 1920

// Wichtig · Fallstricke

Nicht mit der Anzeigebreite verwechseln: codedWidth kann Polsterpixel enthalten. Wenn Sie damit zeichnen oder skalieren, können am Rand Streifen mit Datenmüll erscheinen. Für die Darstellung nehmen Sie displayWidth, für den Bildinhalt visibleRect.
Stride ist nicht gleich Breite: Die Zeilenlänge in Bytes hängt vom Pixelformat ab (z. B. I420, NV12, RGBA). Berechnen Sie Puffergrößen nicht von Hand aus codedWidth, sondern mit allocationSize(), und lesen Sie den Stride aus dem Layout, das copyTo() liefert.
Geschlossene Frames: Nach close() gibt die Eigenschaft 0 zurück. Schließen Sie Frames trotzdem immer, weil sie viel GPU- oder Hauptspeicher belegen können.
Kompatibilität: Die WebCodecs API gibt es nur in sicheren Kontexten (HTTPS). Sie läuft in Chromium-Browsern ab Version 94, in Safari ab 16.4 und in Firefox ab 130. Prüfen Sie die Unterstützung mit 'VideoFrame' in window. Die API ist auch in Workern verfügbar.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung und löst im Strict Mode einen TypeError aus.

Siehe auch

VideoFrame VideoFrame.codedHeight VideoFrame.codedRect VideoFrame.visibleRect VideoFrame.displayWidth VideoFrame.prototype.copyTo() VideoDecoder