Return AVRational instead of fractions.Fraction

Delete `avrational_to_fraction()`, the last thing in PyAV producing a
Fraction, and route its call sites through from_avrational. Rational
attributes now hand back an AVRational, never None. An unset value is
the falsy `AVRational(0, 1)`

Settable attributes are stubbed as property/setter pairs so a
`fractions.Fraction` is still accepted on assignment, as documented,
while reads are typed AVRational. The reflected arithmetic dunders gain
overloads, without which `ctx.framerate = 1 / ctx.time_base` fails to
type check on the float arm of their return union.

Author: WyattBlue

CHANGELOG.rst

@@ -35,9 +35,18 @@ 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 :class:`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``.
+- Remove ``Capabilities.hwaccel``, ``Capabilities.hwaccel_vdpau``, and ``Capabilities.neg_linesizes``, none of which FFmpeg defines any more.
+
+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.
+- 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``, and the ``LCEVC``, ``VIEW_ID``, ``THREE_D_REFERENCE_DISPLAYS``, and ``EXIF`` members of ``sidedata.Type``.
 
 Fixes:
 
+- ``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.
 - 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.
 

av/codec/codec.py

@@ -5,7 +5,6 @@
 from cython.cimports.av.audio.format import get_audio_format
 from cython.cimports.av.codec.hwaccel import HWConfig, wrap_hwconfig
 from cython.cimports.av.rational import from_avrational
-from cython.cimports.av.utils import avrational_to_fraction
 from cython.cimports.av.video.format import VideoFormat, get_pix_fmt, get_video_format
 from cython.cimports.libc.stdlib import free, malloc
 

av/codec/context.py

@@ -8,7 +8,8 @@
 from cython.cimports.av.dictionary import Dictionary
 from cython.cimports.av.error import err_check
 from cython.cimports.av.packet import Packet
-from cython.cimports.av.utils import avrational_to_fraction, to_avrational
+from cython.cimports.av.rational import from_avrational
+from cython.cimports.av.utils import to_avrational
 from cython.cimports.libc.errno import EAGAIN
 from cython.cimports.libc.stdint import uint8_t
 from cython.cimports.libc.string import memcpy, strcmp
@@ -857,7 +858,7 @@ def level(self, value: cython.int):
     def time_base(self):
         if self.is_decoder:
             raise RuntimeError("Cannot access 'time_base' as a decoder")
-        return avrational_to_fraction(cython.address(self.ptr.time_base))
+        return from_avrational(self.ptr.time_base)
 
     @time_base.setter
     def time_base(self, value):

av/codec/context.pyi

@@ -6,6 +6,7 @@ from typing import ClassVar, Literal, cast, overload
 from av.audio import _AudioCodecName
 from av.audio.codeccontext import AudioCodecContext
 from av.packet import Packet
+from av.rational import AVRational
 from av.subtitles import _SubtitleCodecName
 from av.subtitles.codeccontext import SubtitleCodecContext
 from av.video import _VideoCodecName
@@ -125,7 +126,10 @@ class CodecContext:
     @property
     def profiles(self) -> list[str]: ...
     extradata: bytes | None
-    time_base: Fraction
+    @property
+    def time_base(self) -> AVRational: ...
+    @time_base.setter
+    def time_base(self, value: AVRational | Fraction | int) -> None: ...
     codec_tag: str
     global_quality: int
     bit_rate: int | None

av/container/core.py

@@ -11,9 +11,9 @@
 from cython.cimports.av.container.pyio import pyio_close_custom_gil, pyio_close_gil
 from cython.cimports.av.error import err_check, stash_exception
 from cython.cimports.av.format import build_container_format
+from cython.cimports.av.rational import from_avrational
 from cython.cimports.av.utils import (
     avdict_to_dict,
-    avrational_to_fraction,
     dict_to_avdict,
     to_avrational,
 )
@@ -433,7 +433,7 @@ def chapters(self):
                     "id": ch.id,
                     "start": ch.start,
                     "end": ch.end,
-                    "time_base": avrational_to_fraction(cython.address(ch.time_base)),
+                    "time_base": from_avrational(ch.time_base),
                     "metadata": avdict_to_dict(
                         ch.metadata, self.metadata_encoding, self.metadata_errors
                     ),

av/container/core.pyi

@@ -7,12 +7,13 @@ from typing import Any, ClassVar, Literal, Self, TypedDict, cast, overload
 
 from av.codec.hwaccel import HWAccel
 from av.format import ContainerFormat
+from av.rational import AVRational
 
 from .input import InputContainer
 from .output import OutputContainer
 from .streams import StreamContainer
 
-Real = int | float | Fraction
+Real = int | float | Fraction | AVRational
 
 class Flags(Flag):
     gen_pts = cast(ClassVar[Flags], ...)
@@ -72,7 +73,7 @@ class Chapter(TypedDict):
     id: int
     start: int
     end: int
-    time_base: Fraction | None
+    time_base: AVRational
     metadata: dict[str, str]
 
 class Container:

av/container/output.pyi

@@ -6,6 +6,7 @@ from av.audio import _AudioCodecName
 from av.audio.stream import AudioStream
 from av.codec.hwaccel import HWAccel
 from av.packet import Packet
+from av.rational import AVRational
 from av.stream import AttachmentStream, DataStream, Stream
 from av.subtitles import _SubtitleCodecName
 from av.subtitles.stream import SubtitleStream
@@ -29,7 +30,7 @@ class OutputContainer(Container):
     def add_stream(
         self,
         codec_name: _VideoCodecName,
-        rate: Fraction | int | None = None,
+        rate: AVRational | Fraction | int | None = None,
         options: dict[str, str] | None = None,
         hwaccel: HWAccel | None = None,
         **kwargs,
@@ -38,23 +39,23 @@ class OutputContainer(Container):
     def add_stream(
         self,
         codec_name: _SubtitleCodecName,
-        rate: Fraction | int | None = None,
+        rate: AVRational | Fraction | int | None = None,
         options: dict[str, str] | None = None,
         **kwargs,
     ) -> SubtitleStream: ...
     @overload
     def add_stream(
         self,
         codec_name: str,
-        rate: Fraction | int | None = None,
+        rate: AVRational | Fraction | int | None = None,
         options: dict[str, str] | None = None,
         hwaccel: HWAccel | None = None,
         **kwargs,
     ) -> VideoStream | AudioStream | SubtitleStream: ...
     def add_mux_stream(
         self,
         codec_name: str,
-        rate: Fraction | int | None = None,
+        rate: AVRational | Fraction | int | None = None,
         **kwargs,
     ) -> Stream: ...
     def add_stream_from_template(

av/filter/context.py

@@ -5,7 +5,7 @@
 from cython.cimports.av.error import err_check
 from cython.cimports.av.filter.link import alloc_filter_pads
 from cython.cimports.av.frame import Frame
-from cython.cimports.av.utils import avrational_to_fraction
+from cython.cimports.av.rational import from_avrational
 from cython.cimports.av.video.frame import alloc_video_frame
 
 _cinit_sentinel = cython.declare(object, object())
@@ -162,9 +162,7 @@ def pull(self):
         err_check(res)
 
         frame._init_user_attributes()
-        frame.time_base = avrational_to_fraction(
-            cython.address(self.ptr.inputs[0].time_base)
-        )
+        frame.time_base = from_avrational(self.ptr.inputs[0].time_base)
         return frame
 
     def process_command(

av/filter/graph.py

@@ -1,5 +1,4 @@
 import warnings
-from fractions import Fraction
 
 import cython
 from cython.cimports.av.audio.format import AudioFormat
@@ -8,6 +7,7 @@
 from cython.cimports.av.error import err_check
 from cython.cimports.av.filter.context import FilterContext, wrap_filter_context
 from cython.cimports.av.filter.filter import Filter, wrap_filter
+from cython.cimports.av.rational import AVRational
 from cython.cimports.av.video.format import VideoFormat
 from cython.cimports.av.video.frame import VideoFrame
 
@@ -160,7 +160,7 @@ def add_buffer(
                 "This is deprecated and may be removed in future releases.",
                 DeprecationWarning,
             )
-            time_base = Fraction(1, 1000)
+            time_base = AVRational(1, 1000)
 
         return self.add(
             "buffer",
@@ -204,7 +204,7 @@ def add_abuffer(
         if layout is None and channels is None:
             raise ValueError("missing layout or channels")
         if time_base is None:
-            time_base = Fraction(1, sample_rate)
+            time_base = AVRational(1, sample_rate)
 
         kwargs = {
             "sample_rate": f"{sample_rate}",

av/filter/graph.pyi

@@ -5,6 +5,7 @@ from av.audio.format import AudioFormat
 from av.audio.frame import AudioFrame
 from av.audio.layout import AudioLayout
 from av.audio.stream import AudioStream
+from av.rational import AVRational
 from av.video.format import VideoFormat
 from av.video.frame import VideoFrame
 from av.video.stream import VideoStream
@@ -29,7 +30,7 @@ class Graph:
         height: int | None = None,
         format: VideoFormat | None = None,
         name: str | None = None,
-        time_base: Fraction | None = None,
+        time_base: AVRational | Fraction | None = None,
     ) -> FilterContext: ...
     def add_abuffer(
         self,
@@ -39,7 +40,7 @@ class Graph:
         layout: AudioLayout | str | None = None,
         channels: int | None = None,
         name: str | None = None,
-        time_base: Fraction | None = None,
+        time_base: AVRational | Fraction | None = None,
     ) -> FilterContext: ...
     def set_audio_frame_size(self, frame_size: int) -> None: ...
     def push(self, frame: None | AudioFrame | VideoFrame, at: int = -1) -> None: ...