========
``avif``
========
|PyPI| |Pythons| |CI|
.. |PyPI| image:: https://img.shields.io/pypi/v/avif.svg
:alt: PyPI version
:target: https://pypi.org/project/avif/
.. |Pythons| image:: https://img.shields.io/pypi/pyversions/avif.svg
:alt: Supported Python versions
:target: https://pypi.org/project/avif/
.. |CI| image:: https://github.com/Julian/avif/workflows/CI/badge.svg
:alt: Build status
:target: https://github.com/Julian/avif/actions?query=workflow%3ACI
Python bindings for `libavif <https://github.com/AOMediaCodec/libavif>`_ (via
`CFFI <https://cffi.readthedocs.io/en/latest/>`_)
Installation from PyPI
----------------------
``avif`` is available `via PyPI <https://pypi.org/project/avif/>`_, with
wheels built for many common platforms. It can be installed via your
favorite Python package manager, e.g.:
.. code-block:: sh
$ pip install avif
Or if you want to use `Pillow <https://github.com/python-pillow/Pillow>`_ integration:
.. code-block:: sh
$ pip install avif[pillow]
Installation from source
------------------------
To install this module from source you will need to compile ``libavif`` yourself.
If you want to make use of the decoder you will also need to compile one
(decoders/encoders can be compiled from ``libavif``).
**List of available AV1 decoders:**
- `aom <https://aomedia.googlesource.com/aom>`_ (recommended)
- `dav1d <https://code.videolan.org/videolan/dav1d>`_
- `libgav1 <https://chromium.googlesource.com/codecs/libgav1>`_
- `rav1e <https://github.com/xiph/rav1e>`_
- `svt <https://github.com/AOMediaCodec/SVT-AV1>`_
If you compile ``avif`` without an AV1 decoder you will get
``AVIFError: No codec available`` raised when you try to get a result,
but you will still be able to import python module.
The installation steps below show how to compile ``libavif`` with the ``aom``
decoder.
Platform-Specific Steps
^^^^^^^^^^^^^^^^^^^^^^^
- `Linux <INSTALL.linux.rst>`_
- `Windows <INSTALL.win.rst>`_
Examples
--------
Examples can be found under `examples
<https://github.com/Julian/avif/tree/main/examples>`_ directory.
You can use ``sample.avif`` if you don't have any avif encoded image
for testing. Sample is 128x128 pixels in size and it's all white
*(RGBA: 255, 255, 255, 255)*.
**To test if library works properly you can run:**
.. code-block:: bash
$ python examples/avif_example_decode_file.py examples/sample.avif
Correct output:
.. code-block:: bash
Parsed AVIF: 128x128 (8bpc)
* First pixel: RGBA(255, 255, 255, 255)
**Or to test Pillow plugin:**
.. code-block:: bash
$ python examples/avif_example_pillow_decode_file.py examples/sample.avif
Correct output:
.. code-block:: bash
Parsed AVIF: 128x128 (Mode: RGBA)
* First pixel: RGBA(255, 255, 255, 255)
