Signatur
Beschreibung
Der Konstruktor VideoFrame() gehört zur WebCodecs API und erzeugt einen einzelnen, unkomprimierten Videoframe. Solche Frames sind die Eingabe für einen VideoEncoder. Du kannst sie außerdem mit drawImage() auf ein Canvas zeichnen, als WebGL- oder WebGPU-Textur hochladen oder über MediaStreamTrackGenerator bzw. Insertable Streams in einen MediaStream einspeisen.
Es gibt zwei Varianten:
- Aus einer Bildquelle:
new VideoFrame(image, options). AlsimagegehenHTMLCanvasElement,OffscreenCanvas,HTMLImageElement,SVGImageElement,HTMLVideoElement,ImageBitmapoder ein andererVideoFrame. Der Konstruktor übernimmt den Pixelinhalt, der beim Aufruf vorliegt. Spätere Änderungen an der Quelle wirken sich nicht auf den Frame aus. - Aus rohen Pixeldaten:
new VideoFrame(data, options). AlsdatagehenArrayBuffer, ein TypedArray oder eineDataView. In diesem Fall sindformat,codedWidth,codedHeightundtimestampPflicht.
Den timestamp und die optionale duration gibst du in Mikrosekunden an. Sie legen fest, in welcher Reihenfolge und zu welchem Zeitpunkt der Frame im späteren Video erscheint. Wenn du einen bestehenden VideoFrame übergibst, entsteht ein neuer Frame, der dieselben Pixel nutzt. Mit visibleRect, displayWidth/displayHeight und ähnlichen Optionen kannst du den Frame dabei zuschneiden oder anders skalieren, ohne Pixel zu kopieren.
Ein VideoFrame belegt oft viel Speicher, teils auf der GPU oder im Decoder-Pool. Rufe deshalb immer frame.close() auf, sobald du den Frame nicht mehr brauchst. Andernfalls kann die Wiedergabe oder Kodierung stocken.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | HTMLCanvasElement | OffscreenCanvas | HTMLImageElement | SVGImageElement | HTMLVideoElement | ImageBitmap | VideoFrame | Variante 1: Bildquelle, deren aktueller Inhalt in den Frame übernommen wird. Bilder müssen vollständig dekodiert sein. Ein geschlossener VideoFrame löst einen InvalidStateError aus. |
|
| $data Pflicht | ArrayBuffer | TypedArray | DataView | Variante 2: Rohe Pixeldaten im angegebenen format. Der Puffer muss groß genug für alle Ebenen (Planes) laut layout bzw. Standard-Layout sein. |
|
| $options.timestamp | number | Zeitstempel in Mikrosekunden. Pflicht bei Rohdaten und bei allen Bildquellen außer einem VideoFrame, von dem sonst der Zeitstempel übernommen wird. |
|
| $options.duration | number | Dauer des Frames in Mikrosekunden. | |
| $options.alpha | "keep" | "discard" | "keep" | Nur bei Bildquellen: Legt fest, ob der Alphakanal erhalten bleibt oder verworfen wird. |
| $options.visibleRect | {x: number, y: number, width: number, height: number} | gesamte codierte Fläche | Sichtbarer Ausschnitt innerhalb der codierten Fläche. Damit schneidest du den Frame ohne Kopieren zu. Bei YUV-Formaten müssen die Werte zur Unterabtastung passen, meist also gerade Zahlen sein. |
| $options.displayWidth | number | visibleRect.width | Breite, mit der der Frame angezeigt werden soll (z. B. für nicht-quadratische Pixel). |
| $options.displayHeight | number | visibleRect.height | Höhe, mit der der Frame angezeigt werden soll. |
| $options.format | "I420" | "I420A" | "I422" | "I444" | "NV12" | "RGBA" | "RGBX" | "BGRA" | "BGRX" | … | Nur bei Rohdaten und dort Pflicht: das Pixelformat. Je nach Browser gibt es auch 10- und 12-Bit-Varianten wie I420P10. |
|
| $options.codedWidth | number | Nur bei Rohdaten und dort Pflicht: Breite der Pixeldaten in Pixeln. | |
| $options.codedHeight | number | Nur bei Rohdaten und dort Pflicht: Höhe der Pixeldaten in Pixeln. | |
| $options.layout | Array<{offset: number, stride: number}> | dicht gepacktes Standard-Layout | Nur bei Rohdaten: Byte-Offset und Zeilenlänge (stride) für jede Ebene. |
| $options.colorSpace | {primaries?: string, transfer?: string, matrix?: string, fullRange?: boolean} | formatabhängig (RGB: sRGB, YUV: BT.709) | Nur bei Rohdaten: Farbraum-Angaben für die korrekte Darstellung. |
| $options.transfer | ArrayBuffer[] | [] | Nur bei Rohdaten: Puffer, die ohne Kopie an den Frame übergeben werden. Danach sind sie im Aufrufer detached, also nicht mehr nutzbar. |
| $options.rotation / options.flip | 0 | 90 | 180 | 270 / boolean | 0 / false | Neuere Optionen für Drehung und Spiegelung. Noch nicht in allen Browsern verfügbar. |
Rückgabewert
VideoFrame-Objekt mit Eigenschaften wie format, codedWidth, displayWidth, timestamp und duration.