AVIF Local Support

AVIF Local Support adds modern AVIF image support to WordPress while keeping compatibility with existing JPEG media. Built by a Boston photographer who needs it for their own portfolio website.

GitHub Repository: https://github.com/ddegner/avif-local-support

• Local-first: all processing happens on your own server — no external calls. Works well for me on a shared CPU with 2GB of RAM on Linode.
• Image quality first: uses Imagick PHP and CLI when available for high-quality resizing (LANCZOS), corrects EXIF orientation, and preserves ICC color profiles and EXIF/XMP/IPTC metadata when possible.
• Tunable quality and speed: set AVIF quality (0–100) and encoder speed (0–10) to balance fidelity and performance. You can even adjust choose chroma subsampling (4:2:0, 4:2:2, 4:4:4) and bit depth (8/10/12-bit). Defaults: 4:2:0 and 8-bit if your server supports it and you want higher quality images.
• Wraps existing tags in with an AVIF when an .avif version is present.
• Converts JPEG originals and generated sizes to AVIF on upload, or via a daily/background scan.
• Preserves EXIF/XMP/IPTC metadata and ICC color profiles by default (when using ImageMagick/Imagick).
• WordPress-aware resizing logic enabled by default to avoid double-resizing when generating AVIF sizes from originals.
  • Tools include: convert missing AVIFs, upload a test JPEG, and delete all AVIF files in uploads.

How it works

• Front end: Filters common image outputs to add an AVIF ahead of the original JPEG. Browsers that support AVIF will use it; others fall back to JPEG.
• Conversion: Uses Imagick when available (preferred) — with auto-orientation and LANCZOS resizing — or GD with an AVIF encoder. Quality, speed, chroma subsampling, and bit depth are configurable (subsampling/bit depth applied via Imagick when supported).
• Scheduling: Optional daily scan to backfill missing .avif files for existing JPEGs.

Requirements

• PHP 8.0 or later (8.1+ recommended)
• WordPress 6.5 or later
• Imagick PHP extension recommended for best quality and metadata/ICC preservation. GD fallback supported.

Ubuntu/Debian setup (summary)

For local JPEG→AVIF conversion you need either Imagick with AVIF-enabled ImageMagick, or GD with AVIF support:

• Imagick path (recommended)

  • PHP extension: imagick
  • System libraries: ImageMagick built with HEIF/AVIF support (via libheif)
  • Notes: This path enables higher-quality resizing and preserves metadata/ICC profiles

• GD path (fallback)

  • PHP extension: gd built with AVIF support (provides imageavif on PHP 8.1+)
  • Notes: Ensure your distro’s PHP GD is compiled with AVIF; some builds omit it

• Helpful extras

  • PHP exif extension (for orientation handling in the GD fallback)
  • Web server configured to serve .avif as image/avif (Apache/Nginx/LiteSpeed)

Official documentation:
– PHP Imagick installation: https://www.php.net/imagick
– PHP GD installation (AVIF details): https://www.php.net/manual/en/image.installation.php
– ImageMagick format support (AVIF/HEIF): https://imagemagick.org/script/formats.php
– Apache MIME configuration: https://httpd.apache.org/docs/current/mod/mod_mime.html
– Nginx MIME configuration: https://nginx.org/en/docs/http/ngx_http_types_module.html

1. Upload the plugin files to the /wp-content/plugins/avif-local-support directory, or install via the WordPress Plugins screen.
2. Activate the plugin through the ‘Plugins’ screen in WordPress.
3. Go to Settings → AVIF Local Support to configure options.

1. 

   Settings — configure AVIF conversion and output.

2. 

   Tools — convert missing AVIFs, test a conversion, and delete AVIFs.

3. 

   Status — server capability check and library coverage.

4. 

   About — in-admin readme for quick reference.

0.3.0

• Feature: Engine priority update: CLI > Imagick > GD.
• UI: Updated engine selection UI to reflect new priority and show CLI path.
• Fix: Resolved contradictory server support diagnosis.
• Fix: Improved pipeline robustness and error handling.

0.2.9

• Fix: Capture and display detailed CLI output and exit codes in logs when a CLI conversion fails silently.
• Fix: Ensure error messages are correctly populated in the log details even when empty.

0.2.8

• Change: Downgrade memory limit exhaustion error to a warning and continue conversion attempt.
• Logs: Added warning log type when memory limit is exceeded but conversion continues.

0.2.7

• Change: Prevent fallback to GD if Imagick is available but fails conversion in “Auto” mode. Ensures expected engine is used.

0.2.6

• Fix: Validate output size for Imagick PHP extension conversions (rejects invalid 0-byte/tiny files).
• Fix: “Copy logs” button now correctly captures the latest logs after a refresh.
• Fix: Ensure debug details for failed CLI conversions are always included in the log error message.

0.2.4

• Fix: Automatically clean up invalid/empty AVIF files if conversion fails (e.g., exit 0 but no output).
• Fix: Treat existing 0-byte or tiny AVIF files as “missing” so they are regenerated during scans.
• Fix: Restrict macOS-specific ImageMagick environment variables to Darwin systems to prevent interference on Linux.
• Logs: Added verbose debug logging for silent CLI failures (exit 0, no file) to help diagnose resource exhaustion.

0.2.3

• Support: Automatically rewrite parent anchor links to point to AVIFs (improves compatibility with lightboxes like SimpleLightbox).

0.2.2

• Reliability: Added pre-conversion memory check to prevent fatal errors on low-RAM servers.
• Settings: Added “Disable memory check” option for advanced users who want to bypass safety limits.
• Logs: Improved error reporting with actionable suggestions (highlighted) for memory limits, missing delegates, and configuration issues.
• Logs: Include memory check status in conversion log details.

0.2.1

• Admin: Add Logs panel to Tools with refresh/clear and detailed entries (status, engine, duration, sizes, settings, errors).
• Admin: Add “Run ImageMagick test” diagnostic action with inline CLI output and exit code.
• Tools: Show inline progress with a progress bar and faster polling during Convert now.
• Scheduling: Respect site timezone and selected time; reschedule daily task if time changes.
• Engine/CLI: Improve binary validation, set env paths for Homebrew modules, retry transient delegate/read errors, and add helpful AVIF support hint when no output.
• Uploads: Allow .avif uploads via WordPress mime filter.
• Output: Remove stray XML declaration from HTML output when using picture tag replacement.
• Docs: Add FAQ for LiteSpeed/CyberPanel open_basedir causing is_executable to return false.

0.2.0

• Engine: Add ImageMagick CLI support as alternative to Imagick extension with auto-detection of available binaries.
• Engine: New engine selection settings with automatic detection of ImageMagick CLI installations.
• Admin: Improved header styling to match WordPress metabox design patterns.
• Admin: Enhanced tab navigation with better CSS handling and removal of Status tab.
• Admin: Added reset defaults functionality for settings management.
• UI: Better spacing and visual consistency in admin interface.

0.1.8

• Performance: Optimize Imagick conversion by using single instance for both processing and metadata extraction, reducing memory usage and file I/O operations.

0.1.7

• Bugfix: Correct AdobeRGB desaturation by preserving ICC from a fresh read and only adding nclx when untagged; continue to prefer Imagick so ICC survives.

0.1.6

• Color: Preserve ICC profiles when present; add sRGB nclx only when no ICC.
• Color: Avoid transforming tagged images; transform untagged to sRGB to prevent desaturation.
• Color: Explicitly set AVIF nclx to sRGB/full range when applicable.
• Orientation: Normalize EXIF Orientation to 1 after auto-orienting to prevent double-rotate.
• UI: Status tab warns when GD is the preferred method about lack of color management.

0.1.5

• Tools: Add “Delete all AVIF files” action with security checks.
• Admin: Show “Running…” on convert start and poll progress more frequently.
• Admin: Increase spacing and add non-breaking spaces between radio options.
• Admin: Place “Convert now” under file input in Upload Test.
• Status: Deduplicate counts by real JPEG path to avoid double-counting.

0.1.4

• Defaults: Always preserve metadata (EXIF/XMP/IPTC) and ICC color profiles.
• Defaults: Always avoid double-resizing by using WordPress original/-scaled logic.
• Settings: Remove toggles for metadata/ICC/avoid double-resizing (now defaults).
• Settings: Add chroma subsampling radios (4:2:0, 4:2:2, 4:4:4) and bit depth radios (8/10/12-bit). Defaults: 4:2:0 and 8-bit.
• Security: Continue strict sanitization of new settings with whitelists.
• Docs: Update descriptions to reflect new defaults and controls.

0.1.3

• Cleanup: remove unused admin-post “Convert now” handler; AJAX is the single path.
• Cleanup: simplify deactivation routine to directly clear scheduled hooks.
• Cleanup: remove unused global polling object and helpers in assets/admin.js.
• Internal: no user-facing changes; reduces complexity and maintenance overhead.

0.1.2

• Security: ensure all settings use sanitize_callback and validate/escape inputs consistently
• Admin: sanitize GET/FILES handling for the Tools → Upload Test
• Prefix: standardize on aviflosu_* options/defines and Ddegner\\AvifLocalSupport namespace
• Docs: update contributor username to ddegner

0.1.1

• Improve accessibility and settings labels; better time input handling for scheduled conversions
• More robust DOM handling for wrapping images and avoiding double-wrapping
• UI: clearer Convert Now button text and styling on the settings page
• Minor performance and reliability improvements in scheduling and conversion pipeline

0.1.0

Initial release.