WebP Python bindings

Installation

pip install webp

On Windows you may encounter the following error during installation:

conans.errors.ConanException: 'settings.compiler' value not defined

This means that you need to install a C compiler and configure Conan so that it knows which compiler to use. See https://github.com/anibali/pywebp/issues/20 for more details.

Requirements

• Python 3.8+

Usage

import webp

Simple API

# Save an image
webp.save_image(img, 'image.webp', quality=80)
Load an image
img = webp.load_image('image.webp', 'RGBA')
Save an animation
webp.save_images(imgs, 'anim.webp', fps=10, lossless=True)
Load an animation
imgs = webp.load_images('anim.webp', 'RGB', fps=10)

If you prefer working with numpy arrays, use the functions imwrite, imread, mimwrite, and mimread instead.

Advanced API

# Encode a PIL image to WebP in memory, with encoder hints
pic = webp.WebPPicture.from_pil(img)
config = WebPConfig.new(preset=webp.WebPPreset.PHOTO, quality=70)
buf = pic.encode(config).buffer()
Read a WebP file and decode to a BGR numpy array
with open('image.webp', 'rb') as f:
  webpdata = webp.WebPData.frombuffer(f.read())
  arr = webpdata.decode(colormode=WebPColorMode.BGR)
Save an animation
enc = webp.WebPAnimEncoder.new(width, height)
timestamp_ms = 0
for img in imgs:
  pic = webp.WebPPicture.from_pil(img)
  enc.encodeframe(pic, timestampms)
  timestamp_ms += 250
animdata = enc.assemble(timestampms)
with open('anim.webp', 'wb') as f:
  f.write(anim_data.buffer())
Load an animation
with open('anim.webp', 'rb') as f:
  webpdata = webp.WebPData.frombuffer(f.read())
  dec = webp.WebPAnimDecoder.new(webp_data)
  for arr, timestamp_ms in dec.frames():
    # arr contains decoded pixels for the frame
    # timestampms contains the end_ time of the frame
    pass

Features

• Picture encoding/decoding
• Animation encoding/decoding
• Automatic memory management
• Simple API for working with PIL.Image objects

Not implemented

• Encoding/decoding still images in YUV color mode
• Advanced muxing/demuxing (color profiles, etc.)
• Expose all useful fields

Developer notes

Setting up

• Install uv.
• Create a development environment with all dependency groups:

$ uv sync --all-groups

Running tests

$ uv run pytest

Cutting a new release

• Ensure that tests are passing and everything is ready for release.
• Create and push a Git tag:

$ git tag v0.1.6
   $ git push --tags

• Download the artifacts from GitHub Actions, which will include the source distribution tarball and binary wheels.
• Create a new release on GitHub from the tagged commit and upload the packages as attachments to the release.
• Also upload the packages to PyPI using Twine:

$ uv run twine upload webp-.tar.gz webp-.whl

• Bump the version number in pyproject.toml and create a commit, signalling the start of development on the next version.

These files should also be added to a GitHub release.

Known issues

• An animation where all frames are identical will "collapse" in on itself,

resulting in a single frame. Unfortunately, WebP seems to discard timestamp information in this case, which breaks webp.load_images when the FPS is specified.

• There are currently no 32-bit binaries of libwebp uploaded to Conan Center. If you are running

32-bit Python, libwebp will be built from source.