VideoFrame

Parameters:: other (DOMRectInit or DOMRectReadOnly, optional) – The rectangle to copy. When left out, the result is an empty rectangle at the origin.
Returns:: DOMRectReadOnly – The new rectangle.
Return type:: DOMRectReadOnly

to_json()

Serializes the rectangle, including its edges.

See MDN: DOMRectReadOnly/toJSON.

Returns:: dict – The x, y, width, height, top, right, bottom and left values.
Return type:: dict[str, 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 is accepted too.

See MDN: DOMRectReadOnly/fromRect_static.

Parameters:

x (float, optional) – The horizontal origin, 0 by default.
y (float, optional) – The vertical origin, 0 by default.
width (float, optional) – The width, 0 by default.
height (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.

Parameters:

offset (int) – The index of the plane’s first byte in the buffer.
stride (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. A member is 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.

Parameters:

primaries (webrtc.VideoColorPrimaries, optional) – The color primaries.
transfer (webrtc.VideoTransferCharacteristics, optional) – The transfer characteristics.
matrix (webrtc.VideoMatrixCoefficients, optional) – The matrix that converts between RGB and YUV.
full_range (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.

Returns:: dict – The primaries, transfer, matrix and fullRange values.
Return type:: dict[str, str | 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 is accepted too.

See MDN: VideoColorSpace/VideoColorSpace.

Parameters:

primaries (webrtc.VideoColorPrimaries, optional) – The color primaries.
transfer (webrtc.VideoTransferCharacteristics, optional) – The transfer characteristics.
matrix (webrtc.VideoMatrixCoefficients, optional) – The matrix that converts between RGB and YUV.
full_range (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().

See MDN: VideoFrame/metadata.

Parameters:: rtp_timestamp (int, optional) – The RTP timestamp of a frame received from a remote peer, or 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 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.

Parameters:

format (webrtc.VideoPixelFormat) – The pixel format of the buffer.
coded_width (int) – The width of the pixels in the buffer, which must be positive.
coded_height (int) – The height of the pixels in the buffer, which must be positive.
timestamp (int) – The presentation time in microseconds.
duration (int, optional) – The duration in microseconds.
layout (list of 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, 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, optional) – The clockwise rotation to apply when showing the frame, rounded to the nearest multiple of 90.
flip (bool, optional) – Whether to mirror the frame horizontally when showing it, before rotating.
display_width (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, optional) – The height to show the frame at, given together with display_width.
color_space (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, optional) – Extra facts about the frame, deep-copied.
transfer (list of bytes-like buffers, optional) – Buffers to give up to the frame. The pixels are copied regardless. Transferred 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 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.

Parameters:

timestamp (int, optional) – The presentation time in microseconds.
duration (int, optional) – The duration in microseconds.
alpha (webrtc.AlphaOption, optional) – Whether to keep the alpha channel. With discard, the frame switches to the matching format without alpha.
visible_rect (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, optional) – A clockwise rotation added to the source’s, rounded to the nearest multiple of 90.
flip (bool, optional) – Whether to mirror the frame horizontally. It toggles the source’s flip.
display_width (int, optional) – The width to show the frame at, given together with display_height.
display_height (int, optional) – The height to show the frame at, given together with display_width.
metadata (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() and VideoFrame.allocation_size().

See MDN: VideoFrame/copyTo.

Parameters:

rect (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 of PlaneLayout, optional) – Where to write each plane in the destination. By default, the planes are tightly packed one after another.
format (webrtc.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, 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, /, init: VideoFrameInit | None = None)

class webrtc.models.video_frame.VideoFrame(data: Buffer, /, init: VideoFrameBufferInit)

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

A frame holds its pixels until 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.

See MDN: VideoFrame.

Parameters:

source (Buffer | VideoFrame) – A bytes-like buffer of pixels, which is copied into the frame. It can also be another VideoFrame, whose pixels are shared without copying.
init (VideoFrameBufferInit or VideoFrameInit, optional) – The options. A buffer requires a VideoFrameBufferInit, and a frame takes an optional VideoFrameInit.

Raises:

TypeError – If the source or the options are invalid, or the buffer is too small for them.
webrtc.InvalidStateError – If the source frame is closed.

Example:

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

property format: VideoPixelFormat | None

The pixel format, or None once closed.

See MDN: VideoFrame/format.

Type:: webrtc.VideoPixelFormat, optional

property coded_width: int

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

See MDN: VideoFrame/codedWidth.

Type:: int

property coded_height: int

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

See MDN: VideoFrame/codedHeight.

Type:: int

property coded_rect: DOMRectReadOnly | None

A rectangle covering all the stored pixels, or None once closed.

See MDN: VideoFrame/codedRect.

Type:: DOMRectReadOnly, optional

property visible_rect: DOMRectReadOnly | None

The part of the stored pixels to show, or None once closed.

See MDN: VideoFrame/visibleRect.

Type:: DOMRectReadOnly, optional

property rotation: 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.

Type:: int

property flip: bool

Whether to mirror the frame horizontally when showing it, before rotation.

See MDN: VideoFrame/flip.

Type:: bool

property display_width: int

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

See MDN: VideoFrame/displayWidth.

Type:: int

property display_height: int

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

See MDN: VideoFrame/displayHeight.

Type:: int

property timestamp: int

The presentation time in microseconds, kept after closing.

See MDN: VideoFrame/timestamp.

Type:: int

property duration: int | None

The duration in microseconds, or None if unknown, as for frames from a track.

See MDN: VideoFrame/duration.

Type:: int, optional

property color_space: VideoColorSpace

The color space of the pixels, kept after closing.

See MDN: VideoFrame/colorSpace.

Type:: 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.

Returns:: VideoFrameMetadata – A deep copy, so changing it leaves the frame untouched.
Raises:: webrtc.InvalidStateError – If the frame is closed.
Return type:: VideoFrameMetadata

allocation_size(options=None)

Computes the minimum destination size for copy_to() with the same options.

See MDN: VideoFrame/allocationSize.

Parameters:

options (VideoFrameCopyToOptions, optional) – What to copy and how.

Returns:

int – The number of bytes.

Raises:

webrtc.InvalidStateError – If the frame is closed.
TypeError – If the options are invalid, like a rectangle outside the frame or overlapping planes.
webrtc.NotSupportedError – If the format or color space can’t be converted to.

Return type:

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.

Parameters:

destination (bytearray or writable memoryview) – The buffer to write to, at least allocation_size() bytes long.
options (VideoFrameCopyToOptions, optional) – What to copy and how.

Returns:

asyncio.Future – Resolves to a list of PlaneLayout that says where each plane was written. It fails with the errors of allocation_size(), or TypeError if the buffer is too small.

Return type:

Future[list[PlaneLayout]]

clone()

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

See MDN: VideoFrame/clone.

Returns:: VideoFrame – The new frame.
Raises:: webrtc.InvalidStateError – If the frame is closed.
Return type:: 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.

See MDN: VideoFrame/close.