av

Major

• Drop support for Python 3.11. Binary wheels are now built for Python 3.12 and later.
• Remove the undocumented CodecContext.hwaccel attribute. It held the HWAccel settings object passed in, not the live device context; use CodecContext.is_hwaccel to check whether hardware acceleration is in use.
• Rational attributes (time_base, average_rate, base_rate, guessed_rate, framerate, rate, sample_aspect_ratio, and display_aspect_ratio) now return av.AVRational rather than fractions.Fraction, and are never None: an unset value is the falsy AVRational(0, 1). Test them with if not stream.time_base: instead of is None. Setters still accept a fractions.Fraction.
• Closing an OutputContainer now frees its context, so using one afterwards raises Container is not open instead of continuing against a finished file. Muxing has no avformat_close_input() to do this for it, so add_stream(), mux(), start_encoding() and the rest kept working after close(), and streams held from it stayed readable.
• Remove Capabilities.hwaccel, Capabilities.hwaccel_vdpau, and Capabilities.neg_linesizes, none of which FFmpeg defines any more.
• Remove the metadata_encoding and metadata_errors arguments to av.open, and the matching attributes. Metadata is now always read and written as UTF-8 with surrogateescape, which is byte exact: a tag in another encoding survives as surrogates and is recovered per key with value.encode("utf-8", "surrogateescape").decode("cp1251"). Previously one encoding had to be chosen for a whole container, so a file mixing encodings across tags could not be represented at all.
• Remove the stream_options argument to av.open and the matching attribute. They only ever reached avformat_find_stream_info(), and only for formats that expose their streams before it runs, so they raised for MPEG and friends; output containers rejected them outright. Pass options for every stream, set stream.codec_context.options for one, and Container.add_stream(..., options={}) when writing.

Features

• av.dump_codecs() now lists every codec FFmpeg knows of rather than only those with an encoder or a decoder, so data and attachment codecs appear, matching ffmpeg -codecs. Its legend gains the ..D... and ..T... media types.
• ContainerFormat.fixed_framesize reports whether a format wants fixed size audio frames.
• CodecContext exposes more of AVCodecContext: pkt_timebase, frame_num, active_thread_type, bits_per_raw_sample, compression_level, rc_buffer_size, min_bit_rate, a setter for max_bit_rate, the audio initial_padding, trailing_padding, and seek_preroll, and stats_in/stats_out for two-pass encoding. VideoCodecContext gains chroma_sample_location, refs, and mb_decision; AudioCodecContext gains block_align.
• CodecContext.coded_side_data and CodecContext.decoded_side_data expose the context's global side data as dicts of bytes, keyed by packet side data name and Type respectively. Stream wide HDR metadata, such as mastering display and content light level, arrives in decoded_side_data once a frame has been decoded.
• VideoFrame.chroma_location exposes AVFrame.chroma_location, the position of the chroma samples relative to the luma samples, and the new ChromaLocation enum names its values. Only the codec context side of the field was wrapped, as VideoCodecContext.chroma_sample_location, so the siting a decoder actually reported per frame could not be read at all. Each property mirrors its C field name, which FFmpeg spells differently on the two structs.
• Enums gained the members FFmpeg has since added: Properties.FIELDS, Properties.ENHANCEMENT, PixFmtLoss.EXCESS_RESOLUTION, PixFmtLoss.EXCESS_DEPTH, Flags2.icc_profiles, format.Flags.experimental, Interpolation.STRICT, Interpolation.UNSTABLE, ColorTrc.V_LOG, ColorPrimaries.V_GAMUT, the LCEVC, VIEW_ID, THREE_D_REFERENCE_DISPLAYS, and EXIF members of sidedata.Type, and the exif, dynamic_hdr_smpte_2094_app5, and hevc_conf packet side data names.

Fixes

• Frame.side_data and PacketSideData.data_type no longer raise on side data types FFmpeg has added since PyAV last listed them. The packet side data names were missing three, so reading, say, the AV_PKT_DATA_HEVC_CONF an HEVC stream in MP4 or Matroska carries raised IndexError. A frame side data type that no sidedata.Type member names, which is anything a newer FFmpeg than PyAV was built against added, now becomes an UNKNOWN_<value> member rather than raising ValueError.
• CodecContext.bit_rate_tolerance returns its value instead of always None; the getter was missing its return.
• A rejected add_stream() or add_mux_stream() no longer breaks the container.
• InputContainer.size returns None when the size cannot be determined rather than the negative AVERROR it was passing through, which read as a plausible byte count. A non-seekable input, such as a pipe, reported -78.
• av.dump_codecs() no longer drops the canonical names h264, hevc, av1, dirac, and ilbc, each of which was overwritten by the row of whichever encoder it resolved to.
• FilterLink.input and FilterLink.output now follow the filters the graph auto-inserts while configuring. They cached the pad they first resolved, so reading one before Graph.configure() reported the filter the link no longer pointed at.
• Fix a segfault when a FilterLink outlives its Graph. It held the graph by weak reference and dereferenced AVFilterLink before consulting it, so link.input and link.output read freed memory. It now holds the graph, as a FilterContext already did.
• Reading a Stream or its index_entries after the container is closed now raises instead of reading freed memory, since avformat_close_input() frees the underlying AVStream. Holding an index_entries also keeps its container alive, and an IndexEntry is a copy, so it stays readable after the close and is unaffected by the demuxer reallocating the index.
• Attaching one object to the opaque of more than one frame or packet no longer loses it. The objects were keyed by id(), so every holder shared an entry and whichever was freed first took it away from the rest.
• Frame.side_data now satisfies the Mapping protocol it advertises: iteration yields Type keys, so items(), keys(), and values() work instead of raising KeyError. Values remain reachable positionally by an integer or, for the first time, a slice. Its type stub was a TypedDict with a single literal key, and is now SideDataContainer.
• Fix crashes from indexes that were turned into C pointer arithmetic without being range checked. MotionVectors[i] only checked the upper bound, so a negative index read off the front of the buffer (mvs[-1] now returns the last vector, as with any sequence); VideoFormatComponent and AudioPlane accepted any index at all; and BitmapSubtitlePlane and VideoBlockParams were missing their lower bounds.
• Frames returned by flushing a codec context directly (CodecContext.decode() with no packet) now carry the stream's time_base instead of None.
• VideoFrame.reformat() (and so to_ndarray(format=...), to_rgb(), to_image()) now shares one SwsContext per thread instead of allocating one per frame. FFmpeg 8's swscale retains megabytes of graph state per context, which showed up as large RSS growth when many frames were alive at once.
• Writing to a network URL no longer blocks every other Python thread, and timeout now applies to opening an output container. avio_open(), avformat_write_header(), av_write_trailer(), and avio_closep() held the GIL, so an unreachable RTMP server froze the whole process, and the interrupt callback was only installed for demuxing, so nothing could end the wait. OutputContainer.close now raises rather than freeing a context another thread is still muxing or closing. By @adrianrfreedman in (#2412).
• timeout now applies to muxing and closing an output container, not just to opening it. Only opening armed the interrupt callback, so a peer that accepted the connection and then stopped reading left av_interleaved_write_frame() and av_write_trailer() blocked forever. Each mux gets the full timeout, and a close shares one across writing the trailer and flushing, so neither can outlast it. Only unseekable outputs are covered: writing a seekable file takes as long as the file is big, so a deadline meant for a peer would abandon it part-written. By @adrianrfreedman in (#2414).
• HWAccel.create now passes flags on to the context it creates. They were dropped, so av_hwdevice_ctx_create() always got 0 and CUDA's AV_CUDA_USE_PRIMARY_CONTEXT could not be requested through them.

New Contributors

• @threexc made their first contribution in #2398
• @dylanpulver made their first contribution in #2405
• @happyme531 made their first contribution in #2404
• @adrianrfreedman made their first contribution in #2412
• @Robolightning made their first contribution in #2415

Full Changelog: v18.1.0...v19.0.0

Features

• Infer the specific stream and codec context types for all FFmpeg encoder names in type-checked code by @WyattBlue.
• Add CodecContext.supported_options to discover generic and codec-specific options by @WyattBlue (#2032).
• Add Packet.rescale_ts() to rescale packet PTS, DTS, and duration to a new AVRational time base by @WyattBlue.
• Support reusing the thread's current CUDA context via a current_ctx flag on CudaContext and VideoFrame.from_dlpack, for interop with libraries like PyTorch that initialize CUDA first by @Yozer (#2339).
• VideoFrame.from_dlpack no longer requires restating primary_ctx/current_ctx when passing an explicit cuda_context; the flags are only validated when explicitly given by @WyattBlue.
• Support passing an explicit CUDA stream to FFmpeg CUDA operations, including NVENC input and output, via a cuda_stream parameter on CudaContext; currently limited to logical CUDA device 0 by @Yozer (#2360).
• Add av.AVRational, an exact rational number stored as two int32s that mirrors FFmpeg's AVRational. Codec.frame_rates now holds these rather than fractions.Fraction, and every setter that accepts a Fraction also accepts an AVRational. Unset rational attributes are falsy, so test them with if not stream.time_base: rather than is None by @WyattBlue.
• Add Frame.metadata, the metadata FFmpeg attaches to a frame, by @WyattBlue.
• Add CodecContext.level by @WyattBlue.
• Add VideoCodecContext.field_order by @WyattBlue.
• VideoFrame.save now forwards keyword arguments to the encoder, letting callers trade file size for speed (e.g. pred="none" or compression_level=1 for PNG, qscale=2 for JPG) by @WyattBlue.
• Add InputContainer.start_time_realtime, the stream's start time in microseconds since the Unix epoch, which RTSP derives from RTCP sender reports, by @WyattBlue (#2365).

Fixes

• Fix VideoFrame.save raising AttributeError when given a Path rather than a str by @WyattBlue.
• Fix a frame rate assigned to a VideoStream after add_stream being dropped from the output; the codec context's frame rate is now copied to the stream before the header is written by @WyattBlue (#2301).
• Prevent crashes and corrupted output when structural codec properties are changed after an output stream has been opened by @WyattBlue, reported by @oakaigh (#2232).
• Fix a crash when using a stream that has no CodecContext (a demuxed stream with no available decoder, such as one from a truncated file, or a stream created by add_mux_stream); decoding now raises DecoderNotFoundError, encoding now raises EncoderNotFoundError, and BitStreamFilterContext accepts such a stream as out_stream by @WyattBlue, reported by @justinrmiller (#2344).

Misc

• Support building from source against FFmpeg 9.0 by @WyattBlue. The binary wheels still ship FFmpeg 8.1.2.

New Contributors

• @Yozer made their first contribution in #2339

Full Changelog: v18.0.0...v18.1.0

Major

• Remove Support for Python 3.10
• Upgrade binary wheels to ffmpeg 8.1.2

Features

• Support HW encoding via a hwaccel parameter on OutputContainer.add_stream (e.g. h264_vaapi, h264_nvenc, h264_videotoolbox); software frames passed to encode are uploaded to the device automatically by @WyattBlue (#2156).
• Expose sw_format on VideoCodecContext, and allow configuring the software format of hardware encoders by @WyattBlue.
• Add options parameter to AudioResampler for passing libswresample options (e.g. resampler, filter_size, cutoff) by @WyattBlue (#2262).
• Support yuv420p10le in VideoFrame.to_ndarray and VideoFrame.from_ndarray by @WyattBlue (#1981).
• Add at parameter to Graph.push and Graph.vpush to push a frame to a single buffer source by index, for multi-input filters like overlay by @WyattBlue.
• find_best_pix_fmt_of_list now returns the loss as a PixFmtLoss enum.IntFlag instead of a plain int by @WyattBlue (#2300).
• Add Colorspace.BT2020 by @mark-oshea.
• BitStreamFilterContext now accepts a Codec or a codec-name str as in_stream to pin the input codec without a full Stream by @WyattBlue.

Fixes

• Fix VideoFrame.reformat (and to_ndarray/to_rgb/to_image) raising OSError Operation not supported on frames tagged with reserved or otherwise unsupported color_primaries/color_trc values (e.g. VP9 and NVDEC output); a transfer/primaries conversion is now only performed when explicitly requested by @WyattBlue (#2208).
• Fix add_mux_stream producing unwritable Matroska files by extracting codec extradata from the bitstream before the header is written by @WyattBlue (#2198).
• Encode GPU frames (e.g. CUDA frames from DLPack) directly with pix_fmt="cuda" by adopting the frame's hw_frames_ctx before opening the encoder by @WyattBlue (#2199).
• Fix a crash when reading VideoCodecContext.pix_fmt before it is set; it now returns None by @CarlosRDomin.
• Preserve frame attributes (pts, time_base, colorspace, etc.) when downloading hardware frames to system memory by @CarlosRDomin.

New Contributors

• @mark-oshea made their first contribution in #2325

Full Changelog: v17.1.0...v18.0.0

Breaking

• Remove the undertested av.option and av.descriptor APIs, along with the related Codec and Filter descriptor accessors.

Features

• Use FFmpeg 8.1.1 in the binary wheels by @WyattBlue.
• Build Linux ARMv7 binary wheels by @WyattBlue.
• Expose AVCodecContext.global_quality by @WyattBlue in #2246.
• Expose Stream.discard so demuxing and seeking can skip unwanted streams by @WyattBlue (#2272).
• Add Stream.set_display_matrix() and Stream.set_display_rotation() to write the container display (rotation) matrix on output streams by @hmaarrfk in #2287.
• Add Container.video_codec_id to force a specific video codec on a container by @WyattBlue (#2243).

Fixes

• Add cython.final to leaf classes, ensuring that they are not subclassed by @WyattBlue.
• Warn that CodecContext.decode() is not memory safe in some cases.
• Fix memory leaks in FFmpegError, AudioLayout channel layouts, and Frame.opaque, and break a reference cycle between FilterLink and Graph by @lgeiger.
• Reduce excessive logging lock contention by @WyattBlue (#2276).
• Fix a crash when accessing Stream from multiple threads under FFmpeg 8.1 by @WyattBlue (#2247).
• Fix a crash during InputContainer initialization by @WyattBlue (#2010).
• Fix enumerate_input_devices and enumerate_output_devices raising AttributeError by @WyattBlue and @kazuki (#2264).
• Map HTTP 429 to HTTPTooManyRequestsError instead of UndefinedError by @WyattBlue (#2267).
• Fix crash in VideoFrame.to_ndarray() and to_image() on bottom-up frames with a negative line_size by @WyattBlue (#2213).
• Make Disposition an IntFlag so Stream.disposition can be assigned without raising TypeError by @HotariTobu.
• Assign parser-inferred pts, dts, and duration to packets from CodecContext.parse() by @WyattBlue (#1919).
• Copy time_base in add_stream_from_template() by @daveisfera in #2249.
• Fix the remux examples dropping keyframes that demux with no DTS, which produced audio-only output by @WyattBlue (#1917).
• Fix subtitle UTF-8 handling by @jbree in #2271.
• Fix several incorrect malloc size calculations by @WyattBlue.

New Contributors

• @HotariTobu made their first contribution in #2257
• @jbree made their first contribution in #2271
• @kazuki made their first contribution in #2288

Full Changelog: v17.0.1...v17.1.0

What's Changed

• Adjust tests so they work with ffmpeg 8.1 by @strophy in #2204 and #2205
• Make VideoFormat.components lazy by @WyattBlue in #2209
• Break reference cycle in StreamContainer.get() by @lgeiger in #2221
• Expose threads in filter graph by @lgeiger in #2211
• Fix crash with container closing with GC by @WyattBlue in #2225
• Fix #2223 "Writing packets to data stream broken in av>=17" regression by @WyattBlue
• Remove _send_packet_and_recv to simplify decode() by @lgeiger in #2233
• Reuse a AVPacket read buffer when demuxing by @lgeiger in #2234
• Use AVCodecContext.frame_num instead of counting ourselves by @WyattBlue in #2236
• Use layout_compare() for AudioLayout.__eq__() by @WyattBlue in #2236

New Contributors

• @strophy made their first contribution in #2204

Full Changelog: v17.0.0...v17.0.1

Major

• Limited API binary wheels are now built.
• 3.13t (free-threading) wheels are be dropped because of storage limitations. Use 3.14t or 3.13.
• When an FFmpeg C function indicates an error, raise av.ArgumentError instead of ValueError/av.ValueError. This helps disambiguate why an exception is being thrown.
• Save space by removing libaom (av1 encoder/decoder); dav1d, stvav1, and hardware, are available alternatives.

Features

• Add OutputContainer.add_mux_stream() for creating codec-context-free streams, enabling muxing of pre-encoded packets without an encoder, addressing #1970 by @WyattBlue.
• Use zero-copy for Packet init from buffer data by @WyattBlue in (#2199).
• Expose AVIndexEntry by @Queuecumber in (#2136).
• Preserving hardware memory during cuvid decoding, exporting/importing via dlpack by @WyattBlue in (#2155).
• Add enumerate_input_devices and enumerate_output_devices API by @WyattBlue in (#2174).
• Add ColorTrc and ColorPrimaries enums; add color_trc and color_primaries properties to VideoFrame; add dst_color_trc and dst_color_primaries parameters to VideoFrame.reformat(), addressing #1968 by @WyattBlue in (#2175).
• Add multithreaded reformatting and reduce Python overhead by replacing sws_scale with sws_scale_frame, skipping unnecessary reformats, and minimizing Python interactions by @lgeiger.
• Prevent data copy in VideoFrame.to_ndarray() for padded frames by @lgeiger in (#2190).

Fixes

• Fix #2149 by @WyattBlue in (#2155).
• Fix packet typing based on stream and specify InputContainer.demux based on incoming stream by @ntjohnson1 in (#2134).
• Fix memory growth when remuxing with add_stream_from_template by skipping avcodec_open2 for template-initialized codec contexts, addressing #2135 by @WyattBlue).
• Explicitly disable OpenSSL in source builds (scripts/build-deps) to prevent accidental OpenSSL linkage that breaks FIPS-enabled systems, addressing #1972.
• Add missing SWS_SPLINE interpolation by @lgeiger in (#2188).

New Contributors

• @wojiushixiaobai made their first contribution in #2076
• @ntjohnson1 made their first contribution in #2134
• @clayy24 made their first contribution in #2181

Full Changelog: v16.1.0...v17.0.0

Features:

• Add support for Intel QSV codecs by @ladaapp.
• Add AMD AMF hardware decoding by @ladaapp2.
• Add subtitle encoding support by @skeskinen in #2050.
• Add read/write access to PacketSideData by @skeskinen in #2051.
• Add yuv422p support for video frame to_ndarray and from_ndarray by @wader in #2054.
• Add binding for avcodec_find_best_pix_fmt_of_list() by @ndeybach in #2058.

Fixes:

• Fix #2036, #2053, #2057 by @WyattBlue.

New Contributors

• @ndeybach made their first contribution in #2052
• @benedikt-grl made their first contribution in #2070

Full Changelog: v16.0.1...v16.1.0

Build is failing because it can't find libcurl:
ValueError: Cannot repair wheel, because required library
"libssl.so.10" could not be located

Someone who cares about this can fix it