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:

Fraction or 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:

Fraction or None

decode(Packet packet=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:

Fraction or None

encode(VideoFrame frame=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:

Fraction or 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:

Fraction or 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

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_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 compoment 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?

Wraps AVFrame.interlaced_frame.

VideoFrame.pict_type

One of PictureType.

Wraps AVFrame.pict_type.

class av.video.frame.PictureType

Bases: EnumItem

Wraps AVPictureType (AV_PICTURE_TYPE_*).

PictureType Name	Flag Value	Meaning in FFmpeg
NONE	0x0	Undefined
I	0x1	Intra
P	0x2	Predicted
B	0x3	Bi-directional predicted
S	0x4	S(GMC)-VOP MPEG-4
SI	0x5	Switching intra
SP	0x6	Switching predicted
BI	0x7	BI type

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(**kwargs)

Get a numpy array of this frame.

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

Note

Numpy must be installed.

Note

For formats which return an array of ``uint16`, 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).

static VideoFrame.from_image(img)

Construct a frame from a PIL.Image.

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

Construct a frame from a numpy array.

Note

For formats which expect an array of uint16, 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).

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

Bases: EnumItem

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	Lanczos
SPLINE	0x400	Bicubic spline

class av.video.reformatter.Colorspace

Bases: EnumItem

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

Colorspace Name	Flag Value	Meaning in FFmpeg
ITU709	0x1	-
FCC	0x4	-
ITU601	0x5	-
ITU624	0x5	-
SMPTE170M	0x5	-
SMPTE240M	0x7	-
DEFAULT	0x5	-
smpte240	0x7	-