AVIF Conversion in jekcms: How the Pipeline Actually Works

When you upload an image to jekcms, the file is not stored as it is. During the upload request the image is converted to AVIF and WebP, four sized copies are created and the original file is deleted. This post walks through the steps of that pipeline, what it needs from the server and where its limits are.

Why AVIF

AVIF produces noticeably smaller files than JPEG at the same visual quality; WebP is also smaller than JPEG, though usually not by as much. All current browsers can display AVIF, and WebP is there as a fallback for older ones that cannot. How much smaller a file gets depends on the photo: a detailed photograph and a flat-colour graphic behave very differently. If you want numbers for your own site, compare a few of your real images before and after conversion.

Step by Step

1. File received, checked that it really is an image
2. Size limit checked (50 MB by default)
3. Image scaled down if its long edge exceeds the cap (2560 px by default)
4. Saved as AVIF (quality 60 by default)
5. Saved as WebP (quality 82 by default)
6. Four sizes created: thumbnail, medium, large, pinterest
7. Original JPEG/PNG/GIF deleted once conversion succeeds
8. Record written to the media table

The long-edge cap can be set anywhere from 800 to 4096 pixels in the settings. The quality values are not fixed either: AVIF can be set between 40 and 80 and WebP between 55 and 95. The defaults come from widely used ranges for the web.

Because the image is re-encoded, EXIF data from phone photos (location, device, capture time) is not carried into the new files.

Sizes

• thumbnail: 400x400, cropped from the centre
• medium: up to 800 pixels, aspect ratio kept
• large: up to 1600 pixels, aspect ratio kept
• pinterest: 1000x1500, cropped from the centre

The thumbnail, medium and large dimensions can be changed in the settings. Cropping always happens from the centre of the image; there is no face or subject detection. For a photo whose main subject sits near the edge, it is worth checking the cropped sizes.

What the Server Needs

Conversion is done with PHP's GD extension. AVIF requires GD built with AVIF support (the imageavif function, PHP 8.1 and later). If the server has no AVIF support, WebP becomes the primary format. If GD is missing altogether, the image is stored in its original format and the site keeps working.

How the Browser Picks the Format

Themes print the image with a <picture> tag. The AVIF source comes first, then WebP, and the browser picks the first format it supports:

<picture>
  <source srcset="/uploads/images/2026/03/photo.avif" type="image/avif">
  <source srcset="/uploads/images/2026/03/photo.webp" type="image/webp">
  <img src="/uploads/images/2026/03/photo.webp" alt="Description"
       width="800" height="500" loading="lazy">
</picture>

The decision is made entirely in the browser; the server does not look at the Accept header and send a different file. That is why CDNs that do not forward the Accept header cause no trouble. In your own theme, get_featured_picture() produces this tag with its srcsets ready; if you only need the address, use get_featured_image($post, 'medium').

Transparent and Animated Images

Transparent PNGs keep their transparency through conversion; logos and icons stay transparent in AVIF and WebP.

GIF files are converted to AVIF and WebP too. Because GD reads only the first frame, an animated GIF becomes a still image after conversion. If you want moving content on a page, a short video works better: the animation is kept and the file is much smaller.

Converting Older Images

The batchConvert() function in the Media class converts images that do not have AVIF and WebP versions yet, in groups of 50. You can use it to update a library uploaded before AVIF support was available. There is no separate panel screen for this; the function has to be called from a script.