Codecs¶

Descriptors¶

class av.codec.Codec(name, mode='r')¶

Bases: object

Parameters:

name (str) – The codec name.
mode (str) – 'r' for decoding or 'w' for encoding.

This object exposes information about an available codec, and an avenue to create a CodecContext to encode/decode directly.

>>> codec = Codec('mpeg4', 'r')
>>> codec.name
'mpeg4'
>>> codec.type
'video'
>>> codec.is_encoder
False

Codec.create(kind=None)¶

Create a CodecContext for this codec.

Parameters:: kind (str) – Gives a hint to static type checkers for what exact CodecContext is used.

Codec.is_decoder¶

Codec.is_encoder¶

Codec.name¶

Codec.long_name¶

Codec.type¶

The media type of this codec.

E.g: 'audio', 'video', 'subtitle'.

Codec.id¶

Codec.frame_rates¶: A list of supported frame rates (fractions.Fraction), or None.

Codec.audio_rates¶: A list of supported audio sample rates (int), or None.

Codec.video_formats¶: A list of supported VideoFormat, or None.

Codec.audio_formats¶: A list of supported AudioFormat, or None.

Flags¶

Codec.properties¶

class av.codec.Properties(*values)¶

Bases: Flag

Wraps AVCodecDescriptor.props (AV_CODEC_PROP_*).

Codec.capabilities¶

Get the capabilities bitmask of the codec.

This method returns an integer representing the codec capabilities bitmask, which can be used to check specific codec features by performing bitwise operations with the Capabilities enum values.

Example:

from av.codec import Codec, Capabilities

codec = Codec("h264", "w")

# Check if the codec can be fed a final frame with a smaller size.
# This can be used to prevent truncation of the last audio samples.
small_last_frame = bool(codec.capabilities & Capabilities.small_last_frame)

Return type:: int

class av.codec.Capabilities(*values)¶

Bases: IntEnum

Wraps AVCodec.capabilities (AV_CODEC_CAP_*).

Note that ffmpeg -codecs prefers the properties versions of INTRA_ONLY and LOSSLESS.

Pixel Format Selection¶

av.codec.find_best_pix_fmt_of_list(pix_fmts, src_pix_fmt, has_alpha=False)¶

Find the best pixel format to convert to given a source format.

Wraps avcodec_find_best_pix_fmt_of_list.

Parameters:

pix_fmts – Iterable of pixel formats to choose from (str or VideoFormat).
src_pix_fmt – Source pixel format (str or VideoFormat).
has_alpha (bool) – Whether the source alpha channel is used.

Returns:

(best_format, loss)

Return type:

(VideoFormat | None, PixFmtLoss)

class av.codec.PixFmtLoss(*values)¶

Bases: IntFlag

Flags describing what is lost when converting between pixel formats.

Returned by find_best_pix_fmt_of_list(). Mirrors FFmpeg’s FF_LOSS_* flags.

Wraps FFmpeg’s FF_LOSS_* flags. Returned by find_best_pix_fmt_of_list() to describe what is lost when converting from the source pixel format to the chosen one. Being an enum.IntFlag, members can be combined and tested with bitwise operators.

Contexts¶

class av.codec.context.CodecContext¶: Bases: object

CodecContext.codec¶

CodecContext.options¶: options: dict

static CodecContext.create(codec, mode=None, hwaccel=None)¶

CodecContext.open(bool strict: cython.bint = True)¶

Attributes¶

CodecContext.is_open¶

CodecContext.is_encoder¶

CodecContext.is_decoder¶

CodecContext.name¶

CodecContext.type¶

CodecContext.profile¶

CodecContext.time_base¶

CodecContext.bit_rate¶

CodecContext.bit_rate_tolerance¶

CodecContext.max_bit_rate¶

CodecContext.thread_count¶

How many threads to use; 0 means auto.

Wraps AVCodecContext.thread_count.

CodecContext.thread_type¶

One of ThreadType.

Wraps AVCodecContext.thread_type.

CodecContext.skip_frame¶

Returns one of the following str literals:

“NONE” Discard nothing “DEFAULT” Discard useless packets like 0 size packets in AVI “NONREF” Discard all non reference “BIDIR” Discard all bidirectional frames “NONINTRA” Discard all non intra frames “NONKEY Discard all frames except keyframes “ALL” Discard all

Wraps AVCodecContext.skip_frame.

CodecContext.extradata¶

CodecContext.extradata_size¶

Transcoding¶

CodecContext.parse(raw_input=None)¶

Split up a byte stream into list of Packet.

This is only effectively splitting up a byte stream, and does no actual interpretation of the data.

It will return all packets that are fully contained within the given input, and will buffer partial packets until they are complete.

Any timing information the parser is able to infer (pts, dts, duration, pos and the keyframe flag) is assigned onto the returned packets. Fields the parser cannot determine are left unset.

Parameters:: raw_input (ByteSource) – A chunk of a byte-stream to process. Anything that can be turned into a ByteSource is fine. None or empty inputs will flush the parser’s buffers.
Returns:: list of Packet newly available.

CodecContext.encode(Frame frame: Frame | None = None)¶: Encode a list of Packet from the given Frame.

CodecContext.decode(Packet packet: Packet | None = None)¶

Decode a list of Frame from the given Packet.

If the packet is None, the buffers will be flushed. This is useful if you do not want the library to automatically re-order frames for you (if they are encoded with a codec that has B-frames).

Warning

This method is not thread-safe. Calling decode() concurrently from multiple threads on the same CodecContext will corrupt internal FFmpeg state and likely cause a crash (segfault). FFmpeg 8.1 enforces this more strictly than earlier releases. If you need to decode from multiple threads, give each thread its own CodecContext.

CodecContext.flush_buffers()¶

Reset the internal codec state and discard all internal buffers.

Should be called before you start decoding from a new position e.g. when seeking or when switching to a different stream.

Enums and Flags¶

CodecContext.flags¶

Get and set the flags bitmask of CodecContext.

Return type:: int

class av.codec.context.Flags(*values)¶

Bases: IntEnum

CodecContext Attribute	Flags Name	Flag Value	Meaning in FFmpeg

CodecContext.flags2¶

Get and set the flags2 bitmask of CodecContext.

Return type:: int

class av.codec.context.Flags2(*values)¶

Bases: IntEnum

CodecContext Attribute	Flags2 Name	Flag Value	Meaning in FFmpeg

class av.codec.context.ThreadType(*values)¶

Bases: Flag

Which multithreading methods to use. Use of FF_THREAD_FRAME will increase decoding delay by one frame per thread, so clients which cannot provide future frames should not use it.

ThreadType Name	Flag Value	Meaning in FFmpeg
NONE	0x0	-
FRAME	0x1	Decode more than one frame at once
SLICE	0x2	Decode more than one part of a single frame at once
AUTO	0x3	Decode using both FRAME and SLICE methods.

Hardware Acceleration¶

class av.codec.hwaccel.HWAccel(device_type, device=None, allow_software_fallback=True, options=None, flags=None, is_hw_owned=False)¶

Bases: object

Settings for hardware-accelerated decoding and encoding. Pass an instance to av.open() to decode on the device, or to OutputContainer.add_stream to encode on it.

Parameters:

device_type (str or HWDeviceType) – The kind of device, e.g. "cuda", "vaapi", "videotoolbox". See hwdevices_available() for the types supported by the loaded FFmpeg.
device (str) – An optional device identifier, e.g. a DRI render node path ("/dev/dri/renderD128") for VAAPI or a device index ("1") for CUDA. Uses the default device if None.
allow_software_fallback (bool) – Whether decoding falls back to a software decoder when the hardware decoder cannot handle the stream.
options (dict) – Options passed to av_hwdevice_ctx_create.
flags (int) – Flags passed to av_hwdevice_ctx_create.
is_hw_owned (bool) – If True, decoded frames stay on the device (for consumption via DLPack, for example) instead of being downloaded to system memory.

av.codec.hwaccel.hwdevices_available()¶: Return the names of the hardware device types FFmpeg was built with, e.g. ["cuda", "videotoolbox"].

To decode on a hardware device, pass an HWAccel to av.open():

import av
from av.codec.hwaccel import HWAccel

hwaccel = HWAccel(device_type="videotoolbox")
with av.open("input.mp4", hwaccel=hwaccel) as container:
    for frame in container.decode(video=0):
        ...  # Frames are downloaded to system memory by default.

To encode on a hardware device, pass one to OutputContainer.add_stream with a hardware encoder. Software frames passed to encode are uploaded to the device automatically:

with av.open("output.mp4", "w") as container:
    stream = container.add_stream(
        "h264_videotoolbox", rate=30, hwaccel=HWAccel(device_type="videotoolbox")
    )
    ...

See examples/basics/hw_decode.py for a complete example, including recommended device types per platform.

Codecs¶

Descriptors¶

Flags¶

Pixel Format Selection¶

Contexts¶

Attributes¶

Transcoding¶

Enums and Flags¶

Hardware Acceleration¶

Table of Contents

Previous topic

Next topic

This Page