Smart Image Converter Documentation

Getting started

Installation and first configuration

KG Smart Image Converter creates WebP and AVIF versions of JPEG and PNG files in the WordPress Media Library. Generated versions are stored separately, while the original file remains unchanged.

Requirements

WordPress 6.2 or later.
PHP 7.4 or later.
GD or Imagick for local image processing. Optional cwebp and avifenc command-line encoders can also be used when installed on the server.
AVIF requires AVIF support in GD or Imagick, or a working avifenc binary.

Install

Upload and activate KG Smart Image Converter.
Open Media → KG Smart Image Converter.
Review the server diagnostics and available encoders.
Choose the image formats and quality settings you want to use.
Click Start converting to process the existing Media Library.

Originals stay safe. WebP and AVIF versions are separate files. KG Smart Image Converter does not overwrite, move or delete the original JPEG or PNG during conversion.

Recommended first setup

EncoderStart with Automatic so the plugin can use the best working encoder detected on the server.

WebPEnable WebP when a supported encoder is available.

AVIFEnable AVIF when the server diagnostics confirm AVIF support.

QualityUse a built-in profile or the Before & After comparison to choose values for your images.

Image formats

WebP and AVIF

WebP

WebP is widely supported and can be enabled or disabled independently. When AVIF is not available to a visitor, WebP can be used as the modern-format fallback before the original JPEG or PNG.

AVIF

AVIF can produce very small files, but it requires AVIF support in the selected local encoder. Use the plugin’s server diagnostics to confirm that AVIF is available on your hosting environment.

No external conversion account is required. Image conversion runs on your WordPress server using the locally available encoder.

Quality

Quality profiles and minimum savings

The plugin includes profiles for Photos, Line art & drawings, Maximum savings and a Custom profile. You can also compare one of your own images before saving the chosen quality.

Before & After comparison

Select an image, choose WebP or AVIF and test a quality value. The comparison view lets you inspect the visual result and the resulting file size before applying that quality to future conversions.

Minimum savings

A generated version is kept only when it is smaller than the original by the configured minimum margin. If a generated WebP or AVIF file is not small enough, the plugin skips it and the original remains available.

Line art needs a visual check. Coloring pages, illustrations and other images with thin high-contrast lines can react differently to compression than photographs. Use the Line art profile or the comparison tool before processing a large library.

Encoders

GD, Imagick, cwebp and avifenc

KG Smart Image Converter can automatically select a working local encoder. The available choices depend on the server.

PHP GDUses the GD extension when the requested format is supported.

ImagickUses ImageMagick through the PHP Imagick extension when the requested format is supported.

cwebpOptional locally installed command-line encoder for WebP.

avifencOptional locally installed command-line encoder for AVIF.

The plugin does not download cwebp or avifenc. They are used only when they already exist on the WordPress server.

Conversion

Existing images, thumbnails and new uploads

Existing Media Library

When you start a library conversion, the plugin finds JPEG and PNG media and their WordPress-generated thumbnail sizes. Conversion runs in short background steps so one request does not need to process the entire library at once.

Live progress

While the KG Smart Image Converter screen is open, conversion can run faster and show live progress such as files remaining, current speed, estimated time and the file currently being processed.

New uploads

New uploads are queued automatically after upload instead of making the upload request wait for every conversion. They are normally processed shortly afterwards by the background workflow.

Converter for Media migration

If existing WebP or AVIF files from Converter for Media are found in wp-content/uploads-webpc, KG Smart Image Converter can take them over so they do not need to be converted again. When migrating, keep Converter for Media active until the import/conversion progress reaches 100%, then deactivate it.

WP-Cron

Background conversion uses WP-Cron. On low-traffic sites, or when DISABLE_WP_CRON is enabled, background work may be delayed.

If WP-Cron is disabled: configure a server cron job for wp-cron.php, keep the plugin screen open while processing, or use WP-CLI.

Delivery

How modern image formats reach the browser

The standard delivery method adds a <picture> element with AVIF and WebP sources while retaining the original <img> as the fallback. Browsers that support a modern format can use it; other browsers keep the original image.

The standard <picture> method does not require server rewrite rules and is compatible with most page-cache setups. Cache or CDN systems that perform their own image or HTML rewriting can still affect delivery.

Server & CDN

Apache, Nginx and Cloudflare

Apache

The standard <picture> delivery works without Apache rewrite rules. The plugin also has optional server rules for serving generated versions at original image addresses in supported scenarios.

Nginx

The standard <picture> delivery also works on Nginx without extra configuration. The Tools area can show an optional Nginx configuration snippet for file types and server-level delivery.

Cloudflare and page caches

KG Smart Image Converter detects Cloudflare and avoids optional server-level behavior that can conflict with CDN caching. Page caches are cleared after a library-wide conversion and when generated versions are deleted.

Use the Delivery Test. The Tools section can request a generated image from your own site and verify the returned content type.

Advanced

Processing limits and shared hosting

The Advanced settings let you keep conversion work within the limits of your server. Available controls include:

time limit per processing step,
files processed per step,
maximum image dimensions in megapixels,
maximum source file size,
memory usage limit,
gentle/processing mode,
delay between processed files.

Images that exceed configured limits are skipped and continue using the original file. Gentle mode adds pauses between files to reduce sustained CPU load on shared hosting.

Maintenance

Logs, diagnostics and cleanup

Server diagnostics

The server test shows which image formats and encoders are available. Use it when AVIF or WebP conversion is unavailable or behaves differently after a hosting change.

Logs

The plugin keeps a conversion log with filtering and CSV export. Advanced settings let you choose the log level and how many recent entries to retain.

Cleanup

Tools can remove generated versions whose original image no longer exists and can delete all generated WebP/AVIF versions when required.

Deactivating the plugin does not remove the original images. When uninstalling, generated versions created or taken over by the plugin can be removed if the uninstall cleanup option is enabled; the original images are not deleted.

Command line

WP-CLI commands

KG Smart Image Converter includes commands for automation and server-side workflows:

wp sic status
wp sic start
wp sic run --until-done
wp sic pause
wp sic resume
wp sic regenerate
wp sic probe
wp sic cleanup
wp sic delete-versions

wp sic run --until-done is useful when you want to process the queue from a shell session instead of waiting for visitor-triggered WP-Cron.

Troubleshooting

Common problems

AVIF is unavailable

Run the server test. AVIF requires AVIF support in GD or Imagick, or a working avifenc program. If none are available, leave AVIF disabled and continue using WebP.

Background conversion is not moving

WP-Cron normally runs when the site receives requests. On a quiet site, with WP-Cron disabled, or with an unusual cron configuration, keep the plugin screen open, configure a server cron job or use wp sic run --until-done.

Some generated versions are skipped

A file can be skipped when the generated version is not smaller than the original by the configured minimum margin, or when the source image exceeds configured processing limits.

The site uses too much CPU or memory during conversion

Reduce the time/files per step, lower the memory limit used by the worker, enable a gentler processing mode or increase the delay between files.

Modern images are not being delivered

Run the Delivery Test, clear page/CDN caches and check whether another optimization system is rewriting image HTML. The standard delivery method relies on <picture> markup with the original image as fallback.

FAQ

Frequently asked questions

Are original images modified?

No. Generated versions are separate files. Original JPEG and PNG images are not overwritten during conversion.

Are images sent to an external conversion service?

No. Image conversion happens locally on the WordPress server. No external image-processing account or API key is required.

Does it work with Nginx?

Yes. Standard <picture> delivery does not require Nginx rewrites. An optional Nginx configuration snippet is available in the plugin tools for server-level behavior.

What happens if I deactivate the plugin?

The original files remain untouched. Generated WebP and AVIF files can remain on disk until you remove them with the plugin tools or uninstall cleanup.

Where do I get support?

Use the contact link below. After the plugin is approved in the WordPress.org directory, its public support resources can also be linked from this page.

Need help?

Support and project links

Plugin overviewFeatures, screenshots and product information. WordPress.org profileKrystian Gacek on WordPress.org. Contact supportAsk a question about KG Smart Image Converter.

KG Smart Image Converter Docs