Video

Video Streams

class av.video.stream.VideoStream

Bases: Stream

average_rate

The average frame rate of this video stream.

This is calculated when the file is opened by looking at the first few frames and averaging their rate.

Type:

fractions.Fraction | None

base_rate

The base frame rate of this stream.

This is calculated as the lowest framerate at which the timestamps of frames can be represented accurately. See AVStream.r_frame_rate for more.

Type:

fractions.Fraction | None

decode(Packet packet: Packet | None = None)

Decode a Packet and return a list of VideoFrame.

Return type:

list[VideoFrame]

See also

This is a passthrough to CodecContext.decode().

display_aspect_ratio

The guessed display aspect ratio (DAR) of this stream.

This is calculated from VideoStream.guessed_sample_aspect_ratio().

Type:

fractions.Fraction | None

encode(VideoFrame frame: VideoFrame | None = None)

Encode an VideoFrame and return a list of Packet.

Return type:

list[Packet]

See also

This is mostly a passthrough to CodecContext.encode().

guessed_rate

The guessed frame rate of this stream.

This is a wrapper around av_guess_frame_rate, and uses multiple heuristics to decide what is “the” frame rate.

Type:

fractions.Fraction | None

sample_aspect_ratio

The guessed sample aspect ratio (SAR) of this stream.

This is a wrapper around av_guess_sample_aspect_ratio, and uses multiple heuristics to decide what is “the” sample aspect ratio.

Type:

fractions.Fraction | None

Video Codecs

class av.video.codeccontext.VideoCodecContext

Bases: CodecContext

bits_per_coded_sample

The number of bits per sample in the codedwords. It’s mandatory for this to be set for some formats to decode properly.

Wraps AVCodecContext.bits_per_coded_sample.

Type:

int

coded_height
Type:

int

coded_width
Type:

int

color_primaries

Describes the RGB/XYZ matrix of the colorspace.

Wraps AVFrame.color_primaries.

Type:

int

color_range

Describes the signal range of the colorspace.

Wraps AVFrame.color_range.

Type:

int

color_trc

Describes the linearization function (a.k.a. transformation characteristics) of the colorspace.

Wraps AVFrame.color_trc.

Type:

int

colorspace

Describes the YUV/RGB transformation matrix of the colorspace.

Wraps AVFrame.colorspace.

Type:

int

display_aspect_ratio
encoded_frame_count
format
framerate

The frame rate, in frames per second.

Type:

fractions.Fraction

gop_size

Sets the number of frames between keyframes. Used only for encoding.

Type:

int

has_b_frames
Type:

bool

height
max_b_frames

The maximum run of consecutive B frames when encoding a video.

Type:

int

pix_fmt

The pixel format’s name.

Type:

str | None

qmax

The maximum quantiser value of an encoded stream.

Wraps AVCodecContext.qmax.

Type:

int

qmin

The minimum quantiser value of an encoded stream.

Wraps AVCodecContext.qmin.

Type:

int

rate

Another name for framerate.

reformatter
sample_aspect_ratio
width

Video Formats

class av.video.format.VideoFormat

Bases: object

>>> format = VideoFormat('rgb24')
>>> format.name
'rgb24'
bits_per_pixel
chroma_height(luma_height=0)

Height of a chroma plane relative to a luma plane.

Parameters:

luma_height (int) – Height of the luma plane; defaults to self.height.

chroma_width(luma_width=0)

Width of a chroma plane relative to a luma plane.

Parameters:

luma_width (int) – Width of the luma plane; defaults to self.width.

components
has_palette

Pixel format has a palette in data[1], values are indexes in this palette.

height
is_bayer

The pixel format contains Bayer data.

is_big_endian

Pixel format is big-endian.

is_bit_stream

All values of a component are bit-wise packed end to end.

is_planar

At least one pixel component is not in the first data plane.

is_rgb

The pixel format contains RGB-like data (as opposed to YUV/grayscale).

name

Canonical name of the pixel format.

padded_bits_per_pixel
width
class av.video.format.VideoFormatComponent

Bases: object

bits

Number of bits in the component.

height

The height of this component’s plane.

Requires the parent VideoFormat to have a height.

index
is_alpha

Is this component an alpha channel?

is_chroma

Is this component a chroma channel?

is_luma

Is this component a luma channel?

plane

The index of the plane which contains this component.

width

The width of this component’s plane.

Requires the parent VideoFormat to have a width.

Video Frames

class av.video.frame.VideoFrame

Bases: Frame

A single video frame.

Parameters:

  • width (int) – The width of the frame.

  • height (int) – The height of the frame.

  • format (VideoFormat or str.) – The format of the frame.

>>> frame = VideoFrame(1920, 1080, 'rgb24')

Structural

VideoFrame.width

Width of the image, in pixels.

VideoFrame.height

Height of the image, in pixels.

VideoFrame.format

The VideoFormat of the frame.

VideoFrame.planes

A tuple of VideoPlane objects.

Types

VideoFrame.key_frame

Is this frame a key frame?

Wraps AVFrame.key_frame.

VideoFrame.interlaced_frame

Is this frame an interlaced or progressive?

VideoFrame.pict_type

Returns an integer that corresponds to the PictureType enum.

Wraps AVFrame.pict_type

Type:

int

class av.video.frame.PictureType(*values)

Bases: IntEnum

Wraps AVPictureType (AV_PICTURE_TYPE_*).

PictureType Name

Flag Value

Meaning in FFmpeg

NONE

0x0

-

I

0x1

-

P

0x2

-

B

0x3

-

S

0x4

-

SI

0x5

-

SP

0x6

-

BI

0x7

-

Conversions

VideoFrame.reformat(width=None, height=None, format=None, src_colorspace=None, dst_colorspace=None, interpolation=None)

Create a new VideoFrame with the given width/height/format/colorspace.

See also

VideoReformatter.reformat() for arguments.

VideoFrame.to_rgb(**kwargs)

Get an RGB version of this frame.

Any **kwargs are passed to VideoReformatter.reformat().

>>> frame = VideoFrame(1920, 1080)
>>> frame.format.name
'yuv420p'
>>> frame.to_rgb().format.name
'rgb24'
VideoFrame.to_image(**kwargs)

Get an RGB PIL.Image of this frame.

Any **kwargs are passed to VideoReformatter.reformat().

Note

PIL or Pillow must be installed.

VideoFrame.to_ndarray(channel_last=False, **kwargs)

Get a numpy array of this frame.

Any **kwargs are passed to VideoReformatter.reformat().

The array returned is generally of dimension (height, width, channels).

Parameters:

channel_last (bool) – If True, the shape of array will be (height, width, channels) rather than (channels, height, width) for the “yuv444p” and “yuvj444p” formats.

Note

Numpy must be installed.

Note

For formats which return an array of uint16, float16 or float32, the samples will be in the system’s native byte order.

Note

For pal8, an (image, palette) tuple will be returned, with the palette being in ARGB (PyAV will swap bytes if needed).

Note

For gbrp formats, channels are flipped to RGB order.

static VideoFrame.from_image(img)

Construct a frame from a PIL.Image.

static VideoFrame.from_ndarray(array, format='rgb24', channel_last=False)

Construct a frame from a numpy array.

Parameters:

channel_last (bool) – If False (default), the shape for the yuv444p and yuvj444p is given by (channels, height, width) rather than (height, width, channels).

Note

For formats which expect an array of uint16, float16 or float32, the samples must be in the system’s native byte order.

Note

for pal8, an (image, palette) pair must be passed. palette must have shape (256, 4) and is given in ARGB format (PyAV will swap bytes if needed).

Note

for gbrp formats, channels are assumed to be given in RGB order.

Video Planes

class av.video.plane.VideoPlane

Bases: Plane

buffer_size
height
line_size

Bytes per horizontal line in this plane.

Type:

int

width

Video Reformatters

class av.video.reformatter.VideoReformatter

Bases: object

An object for reformatting size and pixel format of VideoFrame.

It is most efficient to have a reformatter object for each set of parameters you will use as calling reformat() will reconfigure the internal object.

reformat(VideoFrame frame, width=None, height=None, format=None, src_colorspace=None, dst_colorspace=None, interpolation=None, src_color_range=None, dst_color_range=None)

Create a new VideoFrame with the given width/height/format/colorspace.

Returns the same frame untouched if nothing needs to be done to it.

Parameters:

  • width (int) – New width, or None for the same width.

  • height (int) – New height, or None for the same height.

  • format (VideoFormat or str) – New format, or None for the same format.

  • src_colorspace (Colorspace or str) – Current colorspace, or None for the frame colorspace.

  • dst_colorspace (Colorspace or str) – Desired colorspace, or None for the frame colorspace.

  • interpolation (Interpolation or str) – The interpolation method to use, or None for BILINEAR.

  • src_color_range (color range or str) – Current color range, or None for the UNSPECIFIED.

  • dst_color_range (color range or str) – Desired color range, or None for the UNSPECIFIED.

Enums

class av.video.reformatter.Interpolation(*values)

Bases: IntEnum

Wraps the SWS_* flags.

Interpolation Name

Flag Value

Meaning in FFmpeg

FAST_BILINEAR

0x1

Fast bilinear

BILINEAR

0x2

Bilinear

BICUBIC

0x4

Bicubic

X

0x8

Experimental

POINT

0x10

Nearest neighbor / point

AREA

0x20

Area averaging

BICUBLIN

0x40

Luma bicubic / chroma bilinear

GAUSS

0x80

Gaussian

SINC

0x100

Sinc

LANCZOS

0x200

Bicubic spline
class av.video.reformatter.Colorspace(*values)

Bases: IntEnum

Wraps the SWS_CS_* flags. There is a bit of overlap in these names which comes from FFmpeg and backwards compatibility.

Colorspace Name

Flag Value

Meaning in FFmpeg

ITU709

0x1

-

FCC

0x4

-

ITU601

0x5

-

ITU624

0x5

-

SMPTE170M

0x5

-

SMPTE240M

0x7

-

DEFAULT

0x5

-
class av.video.reformatter.ColorRange(*values)

Bases: IntEnum

Wraps the AVCOL* flags.

ColorRange Name

Flag Value

Meaning in FFmpeg

UNSPECIFIED

0x0

Unspecified

MPEG

0x1

MPEG (limited) YUV range, 219*2^(n-8)

JPEG

0x2

JPEG (full) YUV range, 2^n-1

NB

0x3

Not part of ABI