apng duration returns float instead of int

[CTimmerman]

What did you do?

Get the duration of an apng file.

What did you expect to happen?

Get the ms as int. As documented, setting requires an int.

What actually happened?

Got ms as float.

What are your OS, Python and Pillow versions?

• OS: Windows 11 Home 24H2
• Python: Python 3.13.9 (tags/v3.13.9:8183fa5, Oct 14 2025, 14:09:13) [MSC v.1944 64 bit (AMD64)] on win32
• Pillow: 12.0.0

--------------------------------------------------------------------
Pillow 12.0.0
Python 3.13.9 (tags/v3.13.9:8183fa5, Oct 14 2025, 14:09:13) [MSC v.1944 64 bit (AMD64)]
--------------------------------------------------------------------
Python executable is D:\code\image viewer\tk_image_viewer\venv\Scripts\python.exe
Environment Python files loaded from D:\code\image viewer\tk_image_viewer\venv
System Python files loaded from C:\Users\C\AppData\Local\Python\pythoncore-3.13-64
--------------------------------------------------------------------
Python Pillow modules loaded from D:\code\image viewer\tk_image_viewer\venv\Lib\site-packages\PIL
Binary Pillow modules loaded from D:\code\image viewer\tk_image_viewer\venv\Lib\site-packages\PIL
--------------------------------------------------------------------
--- PIL CORE support ok, compiled for 12.0.0
--- TKINTER support ok, loaded 8.6
--- FREETYPE2 support ok, loaded 2.14.1
--- LITTLECMS2 support ok, loaded 2.17
--- WEBP support ok, loaded 1.6.0
--- AVIF support ok, loaded 1.3.0
--- JPEG support ok, compiled for libjpeg-turbo 3.1.2
--- OPENJPEG (JPEG2000) support ok, loaded 2.5.4
--- ZLIB (PNG/ZIP) support ok, loaded 1.3.1.zlib-ng, compiled for zlib-ng 2.2.5
--- LIBTIFF support ok, loaded 4.7.1
--- RAQM (Bidirectional Text) support ok, loaded 0.10.3, fribidi 1.0.13, harfbuzz 12.1.0
*** LIBIMAGEQUANT (Quantization method) support not installed
*** XCB (X protocol) support not installed
--------------------------------------------------------------------

from PIL import GifImagePlugin, Image, ImageGrab, ImageTk

im = Image.open(path)
im.load()  # Else im.info = {} for AVIF.
if hasattr(im, "n_frames"):
    n = im.n_frames
    if n > 1:
        APP.info["Frames"] = n
        duration: int = 0
        # for frame in range(n - 1, -1, -1):  # 116 GIF frames in 15.45s vs 0.21s!
        for frame in range(n):
            im.seek(frame)
            duration += im.info.get("duration", 100) or 100
        im.seek(0)
        print(duration)  # should be an int as Tk's `after()` expects

anim-icos.zip

[radarhere]

As documented, setting requires an int.

I don't think it says that for opening.

The documentation states that an integer should be used when saving.

You are actually free to pass a float when saving if you would like, it will simply be rounded to an integer.

Pillow/src/PIL/PngImagePlugin.py

Line 1277 in 2ebb3e9

frame_duration = int(round(encoderinfo.get("duration", 0)))

I don't think our documentation directly says anything about an integer being supplied when opening an image, and I don't think there's any restriction from the PNG documentation itself about the value.

If you want the documentation to say that a float will be given when opening, ok.

If you think that the documentation should be clarified to say that a float can be provided when saving, it will just be rounded, that sounds feasible.

[CTimmerman]

Silently rounding a float to an int is wrong as it bypasses the point of using a float. And ms should be enough detail for duration else you might just mandate the APNG fraction values. Also GIF at least only returns an int.

[radarhere]

Silently rounding a float to an int is wrong as it bypasses the point of using a float.

From this sentence, it sounds like you want Pillow to save using more precision than rounding to the nearest millisecond,

And ms should be enough detail for duration else you might just mandate the APNG fraction values.

but this sentence sounds like you think the nearest millisecond when saving is fine?

Also GIF at least only returns an int.

The GIF format does not allow for specifying fractions of a millisecond, so GIF duration can always be expressed as a whole integer.

https://www.w3.org/Graphics/GIF/spec-gif89a.txt

Delay Time - If not 0, this field specifies the number of hundredths (1/100) of a second to wait before continuing with the processing of the Data Stream.

As i said, I see nothing in the PNG fcTL chunk specification that means that it can't express the duration in fractions of a millisecond.

[CTimmerman]

The APNG standard has infinite precision, unlike the GIF one (0.01s minimum), but i thought Pillow settled on using 1ms as minimum delay, as also indicated by the APNG save code. I just want consistency or at least parity with open and save in APNG; https://gist.github.com/CTimmerman/63a52128b8aa3a94a9be661985687088 might help.

[radarhere]

I've created #9365 to accept floats as durations when saving PNG images.

[CTimmerman]

Thank you. "in milliseconds as float" in the open doc would suffice to close this issue then.

[radarhere]

I've created #9368

[radarhere]

Pillow 12.1.0 has now been released with these changes.