# VideoFrame

The WebCodecs [`VideoFrame`](#webrtc.models.video_frame.VideoFrame), its rectangles, color space and the dictionaries that create and copy it.

### *class* webrtc.models.video_frame.DOMRectReadOnly(x=0, y=0, width=0, height=0)

An immutable rectangle, like the coded or visible part of a frame.

The width and height may be negative. The edges are then measured from `x` and `y` backwards.

See [MDN: DOMRectReadOnly](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly).

* **Parameters:**
  * **x** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The horizontal origin, 0 by default.
  * **y** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The vertical origin, 0 by default.
  * **width** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The width, 0 by default.
  * **height** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The height, 0 by default.

#### *property* top *: [float](https://docs.python.org/3/builtins/functions.html#float)*

The smaller of `y` and `y` plus `height`.

See [MDN: DOMRectReadOnly/top](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/top).

* **Type:**
  [`float`](https://docs.python.org/3/builtins/functions.html#float)

#### *property* right *: [float](https://docs.python.org/3/builtins/functions.html#float)*

The larger of `x` and `x` plus `width`.

See [MDN: DOMRectReadOnly/right](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/right).

* **Type:**
  [`float`](https://docs.python.org/3/builtins/functions.html#float)

#### *property* bottom *: [float](https://docs.python.org/3/builtins/functions.html#float)*

The larger of `y` and `y` plus `height`.

See [MDN: DOMRectReadOnly/bottom](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/bottom).

* **Type:**
  [`float`](https://docs.python.org/3/builtins/functions.html#float)

#### *property* left *: [float](https://docs.python.org/3/builtins/functions.html#float)*

The smaller of `x` and `x` plus `width`.

See [MDN: DOMRectReadOnly/left](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/left).

* **Type:**
  [`float`](https://docs.python.org/3/builtins/functions.html#float)

#### *classmethod* from_rect(other=None)

Creates a rectangle with the origin and size of another one.

See [MDN: DOMRectReadOnly/fromRect_static](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/fromRect_static).

* **Parameters:**
  **other** ([`DOMRectInit`](#webrtc.models.video_frame.DOMRectInit) or [`DOMRectReadOnly`](#webrtc.models.video_frame.DOMRectReadOnly), optional) – The rectangle to copy. When left
  out, the result is an empty rectangle at the origin.
* **Returns:**
  [`DOMRectReadOnly`](#webrtc.models.video_frame.DOMRectReadOnly) – The new rectangle.
* **Return type:**
  [*DOMRectReadOnly*](#webrtc.models.video_frame.DOMRectReadOnly)

#### to_json()

Serializes the rectangle, including its edges.

See [MDN: DOMRectReadOnly/toJSON](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/toJSON).

* **Returns:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) – The `x`, `y`, `width`, `height`, `top`, `right`, `bottom` and `left` values.
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]

### *class* webrtc.models.video_frame.DOMRectInit(x=0, y=0, width=0, height=0)

A rectangle passed as an option, like the visible part of a new frame.

Wherever one is accepted, a [`DOMRectReadOnly`](#webrtc.models.video_frame.DOMRectReadOnly) is accepted too.

See [MDN: DOMRectReadOnly/fromRect_static](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly/fromRect_static).

* **Parameters:**
  * **x** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The horizontal origin, 0 by default.
  * **y** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The vertical origin, 0 by default.
  * **width** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The width, 0 by default.
  * **height** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The height, 0 by default.

### *class* webrtc.models.video_frame.PlaneLayout(offset, stride)

The position of one plane of pixels in a buffer.

See [MDN: VideoFrame/copyTo](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/copyTo).

* **Parameters:**
  * **offset** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The index of the plane’s first byte in the buffer.
  * **stride** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The number of bytes from the start of one row to the start of the next, padding included.

### *class* webrtc.models.video_frame.VideoColorSpace(primaries=None, transfer=None, matrix=None, full_range=None)

The color space of a frame, read from [`VideoFrame.color_space`](#webrtc.models.video_frame.VideoFrame.color_space). A member is [`None`](https://docs.python.org/3/builtins/constants.html#None) when unknown.

Frames received from a track carry no color space of their own and report BT.601 (`smpte170m`) with a
limited range. That’s the default of the software decoders.

See [MDN: VideoColorSpace](https://developer.mozilla.org/en-US/docs/Web/API/VideoColorSpace).

* **Parameters:**
  * **primaries** ([`webrtc.VideoColorPrimaries`](../enums.md#webrtc.enums.VideoColorPrimaries), optional) – The color primaries.
  * **transfer** ([`webrtc.VideoTransferCharacteristics`](../enums.md#webrtc.enums.VideoTransferCharacteristics), optional) – The transfer characteristics.
  * **matrix** ([`webrtc.VideoMatrixCoefficients`](../enums.md#webrtc.enums.VideoMatrixCoefficients), optional) – The matrix that converts between RGB and YUV.
  * **full_range** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether samples span the full range of their bits. If not, they
    use the limited (studio) range.

#### to_json()

Serializes the color space.

See [MDN: VideoColorSpace/toJSON](https://developer.mozilla.org/en-US/docs/Web/API/VideoColorSpace/toJSON).

* **Returns:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) – The `primaries`, `transfer`, `matrix` and `fullRange` values.
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [bool](https://docs.python.org/3/builtins/functions.html#bool) | None]

### *class* webrtc.models.video_frame.VideoColorSpaceInit(primaries=None, transfer=None, matrix=None, full_range=None)

A color space passed to a new frame. A [`VideoColorSpace`](#webrtc.models.video_frame.VideoColorSpace) is accepted too.

See [MDN: VideoColorSpace/VideoColorSpace](https://developer.mozilla.org/en-US/docs/Web/API/VideoColorSpace/VideoColorSpace).

* **Parameters:**
  * **primaries** ([`webrtc.VideoColorPrimaries`](../enums.md#webrtc.enums.VideoColorPrimaries), optional) – The color primaries.
  * **transfer** ([`webrtc.VideoTransferCharacteristics`](../enums.md#webrtc.enums.VideoTransferCharacteristics), optional) – The transfer characteristics.
  * **matrix** ([`webrtc.VideoMatrixCoefficients`](../enums.md#webrtc.enums.VideoMatrixCoefficients), optional) – The matrix that converts between RGB and YUV.
  * **full_range** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether samples span the full range of their bits. If not, they
    use the limited (studio) range.

### *class* webrtc.models.video_frame.VideoFrameMetadata(rtp_timestamp=None)

Extra facts about a frame, returned by [`VideoFrame.metadata()`](#webrtc.models.video_frame.VideoFrame.metadata).

See [MDN: VideoFrame/metadata](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/metadata).

* **Parameters:**
  **rtp_timestamp** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The RTP timestamp of a frame received from a remote peer, or
  [`None`](https://docs.python.org/3/builtins/constants.html#None) for local frames.

### *class* webrtc.models.video_frame.VideoFrameBufferInit(format, coded_width, coded_height, timestamp, duration=None, layout=None, visible_rect=None, rotation=0, flip=False, display_width=None, display_height=None, color_space=None, metadata=None, transfer=<factory>)

Options to create a [`VideoFrame`](#webrtc.models.video_frame.VideoFrame) from a buffer of pixels.

Only the pixels of the visible rectangle are kept. They become the whole frame, so its coded size is the size
of `visible_rect`.

See [MDN: VideoFrame/VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/VideoFrame).

* **Parameters:**
  * **format** ([`webrtc.VideoPixelFormat`](../enums.md#webrtc.enums.VideoPixelFormat)) – The pixel format of the buffer.
  * **coded_width** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The width of the pixels in the buffer, which must be positive.
  * **coded_height** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The height of the pixels in the buffer, which must be positive.
  * **timestamp** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The presentation time in microseconds.
  * **duration** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The duration in microseconds.
  * **layout** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`PlaneLayout`](#webrtc.models.video_frame.PlaneLayout), optional) – The offset and stride of each plane in the buffer.
    By default, the planes are tightly packed one after another.
  * **visible_rect** ([`DOMRectInit`](#webrtc.models.video_frame.DOMRectInit), optional) – The part of the pixels to keep. Its coordinates are integers
    aligned to the chroma subsampling. All the pixels are kept by default.
  * **rotation** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – The clockwise rotation to apply when showing the frame, rounded to the
    nearest multiple of 90.
  * **flip** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether to mirror the frame horizontally when showing it, before rotating.
  * **display_width** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The width to show the frame at, given together with
    `display_height`. By default, the display size is the visible size after rotation.
  * **display_height** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The height to show the frame at, given together with
    `display_width`.
  * **color_space** ([`VideoColorSpaceInit`](#webrtc.models.video_frame.VideoColorSpaceInit), optional) – The color space. By default, it’s sRGB for RGB formats
    and BT.709 with a limited range for the others.
  * **metadata** ([`VideoFrameMetadata`](#webrtc.models.video_frame.VideoFrameMetadata), optional) – Extra facts about the frame, deep-copied.
  * **transfer** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of bytes-like buffers, optional) – Buffers to give up to the frame. The pixels are
    copied regardless. Transferred [`memoryview`](https://docs.python.org/3/builtins/stdtypes.html#memoryview) objects are released, but other buffers stay usable.

### *class* webrtc.models.video_frame.VideoFrameInit(timestamp=None, duration=None, alpha=AlphaOption.keep, visible_rect=None, rotation=0, flip=False, display_width=None, display_height=None, metadata=None)

Options to create a [`VideoFrame`](#webrtc.models.video_frame.VideoFrame) from another one. Anything left out is taken from the source frame.

The new frame shares the pixels of the source and always keeps its color space.

See [MDN: VideoFrame/VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/VideoFrame).

* **Parameters:**
  * **timestamp** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The presentation time in microseconds.
  * **duration** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The duration in microseconds.
  * **alpha** ([`webrtc.AlphaOption`](../enums.md#webrtc.enums.AlphaOption), optional) – Whether to keep the alpha channel. With `discard`, the frame
    switches to the matching format without alpha.
  * **visible_rect** ([`DOMRectInit`](#webrtc.models.video_frame.DOMRectInit), optional) – The part of the source’s coded pixels to show. Its coordinates
    are integers aligned to the chroma subsampling. Unless the display size is given, it’s scaled to match.
  * **rotation** ([`float`](https://docs.python.org/3/builtins/functions.html#float), optional) – A clockwise rotation added to the source’s, rounded to the nearest
    multiple of 90.
  * **flip** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool), optional) – Whether to mirror the frame horizontally. It toggles the source’s flip.
  * **display_width** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The width to show the frame at, given together with
    `display_height`.
  * **display_height** ([`int`](https://docs.python.org/3/builtins/functions.html#int), optional) – The height to show the frame at, given together with
    `display_width`.
  * **metadata** ([`VideoFrameMetadata`](#webrtc.models.video_frame.VideoFrameMetadata), optional) – Extra facts that replace the source’s, deep-copied.

### *class* webrtc.models.video_frame.VideoFrameCopyToOptions(rect=None, layout=None, format=None, color_space=None)

Options for [`VideoFrame.copy_to()`](#webrtc.models.video_frame.VideoFrame.copy_to) and [`VideoFrame.allocation_size()`](#webrtc.models.video_frame.VideoFrame.allocation_size).

See [MDN: VideoFrame/copyTo](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/copyTo).

* **Parameters:**
  * **rect** ([`DOMRectInit`](#webrtc.models.video_frame.DOMRectInit), optional) – The part of the coded pixels to copy. Its coordinates are integers
    aligned to the chroma subsampling. By default, the visible rectangle is copied.
  * **layout** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`PlaneLayout`](#webrtc.models.video_frame.PlaneLayout), optional) – Where to write each plane in the destination.
    By default, the planes are tightly packed one after another.
  * **format** ([`webrtc.VideoPixelFormat`](../enums.md#webrtc.enums.VideoPixelFormat), optional) – The format to write. It’s either the frame’s own
    format, or one of `RGBA`, `RGBX`, `BGRA` and `BGRX` to convert to RGB.
  * **color_space** ([`webrtc.PredefinedColorSpace`](../enums.md#webrtc.enums.PredefinedColorSpace), optional) – The color space of an RGB conversion. Only
    `srgb` is supported, and it’s the default.

### *class* webrtc.models.video_frame.VideoFrame(image: [VideoFrame](#webrtc.models.video_frame.VideoFrame), /, init: [VideoFrameInit](#webrtc.models.video_frame.VideoFrameInit) | [None](https://docs.python.org/3/builtins/constants.html#None) = None)

### *class* webrtc.models.video_frame.VideoFrame(data: Buffer, /, init: [VideoFrameBufferInit](#webrtc.models.video_frame.VideoFrameBufferInit))

One frame of video. It holds the pixels along with how and when to show them.

A frame holds its pixels until [`close()`](#webrtc.models.video_frame.VideoFrame.close) is called or a `with` block around it ends. Close every frame
once done with it, including frames read from a track. A frame that is garbage collected while open emits a
[`ResourceWarning`](https://docs.python.org/3/builtins/exceptions.html#ResourceWarning).

See [MDN: VideoFrame](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame).

* **Parameters:**
  * **source** (*Buffer* *|* [*VideoFrame*](#webrtc.models.video_frame.VideoFrame)) – A bytes-like buffer of pixels, which is copied into the frame. It can also be another
    [`VideoFrame`](#webrtc.models.video_frame.VideoFrame), whose pixels are shared without copying.
  * **init** ([`VideoFrameBufferInit`](#webrtc.models.video_frame.VideoFrameBufferInit) or [`VideoFrameInit`](#webrtc.models.video_frame.VideoFrameInit), optional) – The options. A
    buffer requires a [`VideoFrameBufferInit`](#webrtc.models.video_frame.VideoFrameBufferInit), and a frame takes an optional [`VideoFrameInit`](#webrtc.models.video_frame.VideoFrameInit).
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the source or the options are invalid, or the buffer is too small for them.
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the source frame is closed.

Example:

```default
frame = webrtc.VideoFrame(
    i420, webrtc.VideoFrameBufferInit(format='I420', coded_width=640, coded_height=480, timestamp=0)
)
```

#### *property* format *: [VideoPixelFormat](../enums.md#webrtc.enums.VideoPixelFormat) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The pixel format, or [`None`](https://docs.python.org/3/builtins/constants.html#None) once closed.

See [MDN: VideoFrame/format](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/format).

* **Type:**
  [`webrtc.VideoPixelFormat`](../enums.md#webrtc.enums.VideoPixelFormat), optional

#### *property* coded_width *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The width of the stored pixels, or 0 once closed.

See [MDN: VideoFrame/codedWidth](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/codedWidth).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* coded_height *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The height of the stored pixels, or 0 once closed.

See [MDN: VideoFrame/codedHeight](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/codedHeight).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* coded_rect *: [DOMRectReadOnly](#webrtc.models.video_frame.DOMRectReadOnly) | [None](https://docs.python.org/3/builtins/constants.html#None)*

A rectangle covering all the stored pixels, or [`None`](https://docs.python.org/3/builtins/constants.html#None) once closed.

See [MDN: VideoFrame/codedRect](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/codedRect).

* **Type:**
  [`DOMRectReadOnly`](#webrtc.models.video_frame.DOMRectReadOnly), optional

#### *property* visible_rect *: [DOMRectReadOnly](#webrtc.models.video_frame.DOMRectReadOnly) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The part of the stored pixels to show, or [`None`](https://docs.python.org/3/builtins/constants.html#None) once closed.

See [MDN: VideoFrame/visibleRect](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/visibleRect).

* **Type:**
  [`DOMRectReadOnly`](#webrtc.models.video_frame.DOMRectReadOnly), optional

#### *property* rotation *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The clockwise rotation to apply when showing the frame, which is 0, 90, 180 or 270.

Frames from a track carry the rotation that the sender signalled. The pixels themselves are not rotated.

See [MDN: VideoFrame/rotation](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/rotation).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* flip *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Whether to mirror the frame horizontally when showing it, before [`rotation`](#webrtc.models.video_frame.VideoFrame.rotation).

See [MDN: VideoFrame/flip](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/flip).

* **Type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *property* display_width *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The width to show the frame at after rotation, or 0 once closed.

See [MDN: VideoFrame/displayWidth](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/displayWidth).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* display_height *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The height to show the frame at after rotation, or 0 once closed.

See [MDN: VideoFrame/displayHeight](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/displayHeight).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* timestamp *: [int](https://docs.python.org/3/builtins/functions.html#int)*

The presentation time in microseconds, kept after closing.

See [MDN: VideoFrame/timestamp](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/timestamp).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

#### *property* duration *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)*

The duration in microseconds, or [`None`](https://docs.python.org/3/builtins/constants.html#None) if unknown, as for frames from a track.

See [MDN: VideoFrame/duration](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/duration).

* **Type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int), optional

#### *property* color_space *: [VideoColorSpace](#webrtc.models.video_frame.VideoColorSpace)*

The color space of the pixels, kept after closing.

See [MDN: VideoFrame/colorSpace](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/colorSpace).

* **Type:**
  [`VideoColorSpace`](#webrtc.models.video_frame.VideoColorSpace)

#### metadata()

Returns a copy of the frame’s extra facts, like the RTP timestamp of a frame received from a peer.

See [MDN: VideoFrame/metadata](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/metadata).

* **Returns:**
  [`VideoFrameMetadata`](#webrtc.models.video_frame.VideoFrameMetadata) – A deep copy, so changing it leaves the frame untouched.
* **Raises:**
  [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the frame is closed.
* **Return type:**
  [*VideoFrameMetadata*](#webrtc.models.video_frame.VideoFrameMetadata)

#### allocation_size(options=None)

Computes the minimum destination size for [`copy_to()`](#webrtc.models.video_frame.VideoFrame.copy_to) with the same options.

See [MDN: VideoFrame/allocationSize](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/allocationSize).

* **Parameters:**
  **options** ([`VideoFrameCopyToOptions`](#webrtc.models.video_frame.VideoFrameCopyToOptions), optional) – What to copy and how.
* **Returns:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int) – The number of bytes.
* **Raises:**
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the frame is closed.
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options are invalid, like a rectangle outside the frame or overlapping planes.
  * [**webrtc.NotSupportedError**](../exceptions.md#webrtc.exceptions.NotSupportedError) – If the format or color space can’t be converted to.
* **Return type:**
  [int](https://docs.python.org/3/builtins/functions.html#int)

#### copy_to(destination, options=None)

Copies the pixels into a buffer, converting them to RGB if asked.

The copy happens before this returns, so the future is already done. Call it from a running event loop.
Errors are set on the future and not raised. RGB conversion uses the frame’s matrix and range.

See [MDN: VideoFrame/copyTo](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/copyTo).

* **Parameters:**
  * **destination** ([`bytearray`](https://docs.python.org/3/builtins/stdtypes.html#bytearray) or writable [`memoryview`](https://docs.python.org/3/builtins/stdtypes.html#memoryview)) – The buffer to write to, at least
    [`allocation_size()`](#webrtc.models.video_frame.VideoFrame.allocation_size) bytes long.
  * **options** ([`VideoFrameCopyToOptions`](#webrtc.models.video_frame.VideoFrameCopyToOptions), optional) – What to copy and how.
* **Returns:**
  [`asyncio.Future`](https://docs.python.org/3/library/asyncio-future.html#asyncio.Future) – Resolves to a [`list`](https://docs.python.org/3/builtins/stdtypes.html#list) of [`PlaneLayout`](#webrtc.models.video_frame.PlaneLayout) that says where each plane was
  written. It fails with the errors of [`allocation_size()`](#webrtc.models.video_frame.VideoFrame.allocation_size), or [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError) if the buffer is too
  small.
* **Return type:**
  *Future*[[list](https://docs.python.org/3/builtins/stdtypes.html#list)[[*PlaneLayout*](#webrtc.models.video_frame.PlaneLayout)]]

#### clone()

Creates another frame that shares these pixels without copying them. Each frame must be closed separately.

See [MDN: VideoFrame/clone](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/clone).

* **Returns:**
  [`VideoFrame`](#webrtc.models.video_frame.VideoFrame) – The new frame.
* **Raises:**
  [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the frame is closed.
* **Return type:**
  [*VideoFrame*](#webrtc.models.video_frame.VideoFrame)

#### close()

Releases this frame’s hold on the pixels. Closing a closed frame does nothing.

After that, the size and rectangle attributes read as empty, and most methods raise
[`webrtc.InvalidStateError`](../exceptions.md#webrtc.exceptions.InvalidStateError).

See [MDN: VideoFrame/close](https://developer.mozilla.org/en-US/docs/Web/API/VideoFrame/close).