WebP AVIF Pro — Complete Guide

WebP AVIF Pro converts and compresses your media library images to WebP or AVIF, locally, with no subscription or quota. This guide covers installation, the two delivery modes, AI alt text generation, image SEO, bulk processing, WP-Cron background and WP-CLI, plus backup and troubleshooting.

Server requirements

The plugin works with either of PHP’s two image engines:

• Imagick compiled with libheif (AVIF) and WebP support — recommended;
• GD with the imagewebp() and imageavif() functions (PHP 8.1 or higher).

The plugin Settings page shows pills indicating the engines and formats actually available on your hosting (Imagick, GD, WebP, AVIF).

Installation

1. Upload the df-webp-avif-pro folder to /wp-content/plugins/ (or install the ZIP from Plugins then Add New).
2. Activate the plugin from the Plugins menu.
3. Go to WebP AVIF Pro then Settings to configure the format, delivery mode, renaming and AI.
4. Run a dry-run analysis, then the optimization from the Optimization page.

Output format and compression

Choose WebP (maximum compatibility) or AVIF (better compression). Main options:

• Automatic WebP fallback: if AVIF is requested but unavailable, the plugin produces WebP instead of failing.
• Quality: from 1 to 100, recommended between 78 and 85.
• Resizing: caps the longest edge to a pixel value (0 = off). Replace mode only.
• EXIF/ICC stripping: removes metadata to make files lighter.
• Skip animated GIFs: avoids breaking animations.

Delivery modes

WebP AVIF Pro offers two strategies, chosen to fit your context.

Replace

The original file is converted, optionally renamed, and all references (post content, metadata) are rewritten to the new file. Originals are backed up so they can be restored.

Keep original (non-destructive)

A next-gen file is generated next to the original (for example photo.jpg and photo.jpg.webp). On output, the plugin serves the next-gen version only to browsers that accept it, using the Accept header; others get the original. No htaccess rule is required.

SEO renaming

Four file renaming modes are available: none, product name (WooCommerce), custom template, or base64 (anonymization). The template mode accepts tokens:

• {product} {title} {sku} {cat} {alt} {id} {date} {n}

Example: {product}-{cat}-{n} produces a filename like custom-rug-entrance-a1b2c3.webp. Renaming does not apply in keep mode.

AI alt text

WebP AVIF Pro generates descriptive alt attributes with AI, in several languages, from the image and the product context.

1. Enable AI in Settings, choose a provider (Anthropic, OpenAI, Gemini, Mistral for vision, or DeepSeek for context only) and enter your API key.
2. Select the desired languages. The first checked language fills the main alt; the others are synced to the Polylang translations when they exist.
3. Generate alt text from the AI ALT page (in bulk), automatically on upload, or per image via the “Generate alt (AI)” media library action.

Front-end SEO

• Anti-CLS dimensions: adds width and height attributes to content images that lack them, to reduce layout shift (Core Web Vitals).
• ImageObject schema: emits a JSON-LD block on pages and product views (featured image and WooCommerce gallery).

Bulk optimization

From the Optimization page:

• Analyze (dry-run): estimates the savings on a sample, without modifying anything.
• Optimize the whole library: processes images in batches without blocking the server. You can leave the page and resume later; processing continues from the remaining images.

The stat cards show the number of converted images, the space saved and a monthly history.

Background (WP-Cron) and WP-CLI

For large libraries, enable background processing: the plugin optimizes one batch every 5 minutes via WP-Cron, without keeping a tab open. Agencies can also drive the plugin from the command line:

wp df-wap status
wp df-wap optimize --batch=20
wp df-wap optimize --dry-run
wp df-wap alt --batch=10
wp df-wap restore --yes

Backup, purge and restore

In replace mode, originals are copied to /wp-content/uploads/df-wap-backups/ (protected folder). You can:

• Restore a single image (media library action) or the whole library (“Restore all” button).
• Automatically purge backups after a set number of days, to reclaim disk space.

In keep mode, restoring simply deletes the next-gen files, since the originals were never modified.

Diagnostics

The Optimization page shows contextual warnings: presence of a media offload plugin (S3/CDN), detected page builders, AVIF requested but unavailable, or low disk space. Follow these recommendations before a large run.

Troubleshooting

• AVIF unavailable: enable the WebP fallback, or set the output format to WebP. The Settings page shows the available engines.
• Images not replaced inside a page builder: some URLs stored by builders escape the rewrite. Prefer keep mode.
• Alt text not generated: check that AI is enabled, the API key is valid and credit remains with the provider.
• Bulk processing seems slow: lower the images-per-batch value (AVIF is heavy), or use the background / WP-CLI.