Bulk Optimization & AI Alt Text

Running Bulk Optimization

Bulk optimization processes all JPEG and PNG images in your WordPress media library that have not yet been optimized. It is the fastest way to compress your existing image library after installing BD Image Optimizer.

Starting a Bulk Optimization

1. Navigate to BD Image → Optimize tab.
2. Click the Start Optimization button.
3. A progress bar will appear showing the percentage complete, the number of processed images, and how many were optimized vs. skipped.
4. The optimization runs via chunked AJAX requests (50 images per chunk) so your browser stays responsive and the server does not time out.
5. When complete, the results show total images processed, optimized count, and skipped count.

Note: Only one bulk optimization job can run at a time. If you try to start a second job while one is already running, you will see an error message.

What Gets Optimized

For each image attachment, the plugin processes:

1. The original full-size image: Resized if it exceeds max dimensions, then compressed, then a WebP version is created.
2. All generated thumbnails: Each WordPress thumbnail size is individually compressed and gets its own WebP version.

The plugin queries the database for all image attachments (JPEG and PNG) that do not have an existing entry in the optimization log table, ensuring already-optimized images are never re-processed.

Skipped Images

An image is skipped (counted in the “skipped” total) if:

• The file does not exist on disk.
• The file is not an optimizable format (only JPEG and PNG are supported).
• The file is smaller than the “Skip Small” threshold (default: 10 KB).
• Compression achieved less than 5% savings — the original is restored from the in-process backup to avoid degrading quality for negligible gain.

Cancelling a Bulk Job

Click the Cancel button that appears next to the progress bar. The job state is cleared, but images already processed during the current job are not reverted — they remain optimized.

Compression Quality Settings

The compression quality setting controls the trade-off between file size and visual quality.

Adjusting Quality

1. Go to BD Image → Settings tab.
2. Use the Compression Quality slider to set a value from 1 to 100.
3. The current value is displayed next to the slider.
4. Click Save Settings.

Quality Guidelines

The default quality of 82 is carefully chosen to provide meaningful file size reduction while maintaining visual quality that is indistinguishable from the original for most viewers.

How Quality Applies

• JPEG: The quality value is passed directly to imagejpeg(). A value of 82 means 82% JPEG quality.
• PNG: The quality is converted to PNG’s 0-9 compression scale using the formula: png_level = round((100 - quality) * 9 / 100). At quality 82, this produces a PNG compression level of approximately 2.
• WebP: The same quality value is passed to imagewebp().

WebP Conversion

WebP is a modern image format that provides superior compression compared to JPEG and PNG, typically reducing file sizes by 25-35% at equivalent visual quality.

Enabling WebP

1. Go to BD Image → Settings tab.
2. Toggle Generate WebP to create WebP versions during optimization.
3. Toggle Serve WebP on Frontend to automatically serve WebP images to browsers that support them.
4. Click Save Settings.

How WebP Files Are Named

WebP files are created by appending .webp to the original filename:

• photo.jpg → photo.jpg.webp
• banner.png → banner.png.webp
• photo-300x200.jpg → photo-300x200.jpg.webp (thumbnails too)

How WebP Serving Works

When “Serve WebP on Frontend” is enabled, the plugin uses the wp_content_img_tag filter (available since WordPress 6.0) to wrap each <img> tag in a <picture> element:

<picture> <source type="image/webp" srcset="photo.jpg.webp"> <img src="photo.jpg" alt="..." /> </picture>

Key behaviors:

• The plugin only wraps images that have a corresponding WebP file on disk. If the WebP file does not exist, the original <img> tag is left unchanged.
• If the image has a srcset attribute for responsive images, the plugin generates a matching WebP srcset with all available WebP variants.
• The sizes attribute is preserved and copied to the WebP source.
• Images already wrapped in <picture> tags, SVGs, and data URI placeholders are automatically skipped.
• Only JPEG and PNG images are wrapped — other formats are left as-is.

Large Image Resizing

Oversized images waste storage space and bandwidth. BD Image Optimizer can automatically resize images that exceed your configured maximum dimensions.

Configuring Max Dimensions

1. Go to BD Image → Settings tab.
2. Set Max Image Dimensions width and height values (minimum: 100px each).
3. Default: 2560 x 2560 pixels.
4. Click Save Settings.

How Resizing Works

• If an image’s width OR height exceeds the maximum, it is scaled down to fit within the maximum dimensions while maintaining the original aspect ratio.
• The scaling ratio is calculated as: min(max_width / orig_width, max_height / orig_height).
• Resizing happens before compression, so the compressed version starts from the resized dimensions.
• Only the original full-size image is resized — thumbnails are generated by WordPress at their own dimensions.
• PNG transparency is preserved during resizing.

AI Alt Text Generation

BD Image Optimizer uses the Claude API (Anthropic) to analyze your images and generate descriptive, accessible alt text. This feature is available on Professional and Agency license tiers.

Setting Up AI Alt Text

1. Ensure you have a Professional or Agency license activated.
2. Navigate to BD Image → Alt Text tab.
3. Enter your Anthropic API key in the Claude API Key field (starts with sk-ant-).
4. Click Validate to verify the key works. The plugin makes a small test request to confirm connectivity.
5. Once validated, the key is encrypted using AES-256-CBC (using your site’s AUTH_SALT) and stored securely in the database.

Note: You provide your own Anthropic API key and pay Anthropic directly for API usage. BD Image Optimizer does not charge separately for alt text generation. Claude Haiku is extremely cost-effective — typically less than $0.001 per image.

Running Bulk Alt Text Generation

1. On the Alt Text tab, click Generate Alt Text.
2. The plugin queries your media library for all image attachments (JPEG, PNG, GIF, WebP) that are missing alt text.
3. Images are processed in chunks of 5 per AJAX request (smaller chunks to respect API rate limits).
4. A progress bar shows the number processed, generated, and failed.
5. Each image is resized to a maximum of 1024 pixels in memory (not on disk), converted to JPEG, and sent to the Claude API as a base64-encoded image.
6. The generated alt text is saved to WordPress’s standard _wp_attachment_image_alt post meta field.

Alt Text Language

You can configure the language for generated alt text:

1. Go to BD Image → Settings tab.
2. Select your preferred language from the Alt Text Language dropdown.
3. Supported languages: English, Spanish, French, German, Italian, Portuguese, Dutch, Arabic, Japanese, Chinese, Korean, Russian.
4. Click Save Settings.

How the AI Generates Alt Text

The plugin sends each image to the Claude API with the following instructions:

• Generate concise, descriptive alt text in the configured language.
• Keep it to 1-2 sentences describing key visual elements.
• Make it suitable for screen readers.
• Do not start with “Image of” or “Photo of”.
• Return only the alt text, nothing else.

The response is limited to 300 tokens maximum to keep alt text concise and appropriate.

Backup Originals

BD Image Optimizer can keep a copy of your original images before optimization, allowing you to restore them later if needed.

Enabling Backups

1. Go to BD Image → Settings tab.
2. Toggle Backup Originals (enabled by default).
3. Click Save Settings.

Backup Storage

• Backups are stored in wp-content/uploads/bdio-originals/{year}/{month}/.
• The directory structure is organized by date, matching WordPress’s upload organization.
• If a backup with the same filename already exists, a random 4-character suffix is added to avoid overwriting.
• The backup directory is created automatically during plugin activation.

Restoring an Original

1. Go to BD Image → Optimize tab.
2. In the Optimization Log table, find the image you want to restore.
3. Click the Restore button.
4. The original file is copied back from the backup, the WebP version and all thumbnail WebP files are deleted, and the optimization log entry is removed.

Warning: If “Backup Originals” was disabled when an image was optimized, the Restore button shows “No backup” and the original cannot be recovered.

License Tiers and Limits

BD Image Optimizer has three license tiers with different capabilities:

Starter

• Sites: 1
• Image Limit: 5,000 images. Once reached, bulk optimization stops with a message to upgrade.
• Image Compression: Yes
• WebP Conversion: Yes
• Auto-Resize: Yes
• AI Alt Text: No
• White Label: No

Professional

• Sites: 3
• Image Limit: Unlimited
• Image Compression: Yes
• WebP Conversion: Yes
• Auto-Resize: Yes
• AI Alt Text: Yes (requires your own Claude API key)
• White Label: No

Agency

• Sites: 25
• Image Limit: Unlimited
• Image Compression: Yes
• WebP Conversion: Yes
• Auto-Resize: Yes
• AI Alt Text: Yes
• White Label: Yes

How the Image Limit Works (Starter Tier)

When you start a bulk optimization job on the Starter tier:

1. The plugin checks how many unique attachments have already been optimized.
2. The remaining quota is calculated: 5000 - already_optimized.
3. If the quota is zero, the job is blocked with the message: “Image limit reached for your plan. Upgrade to Professional for unlimited images.”
4. If some quota remains, the job processes only up to the remaining number of images.

Tip: Auto-optimize on upload also counts toward the 5,000 image limit. If you are approaching the limit, consider upgrading to Professional for unlimited optimization.

Settings Reference

Complete reference for all BD Image Optimizer settings, stored in the bdio_settings WordPress option:

Database and Storage

BD Image Optimizer uses one custom database table and one storage directory:

• Database table: {prefix}_bdio_optimization_log — Stores a record for each optimization action, including attachment ID, file path, original and optimized sizes, savings percentage, WebP size and path, backup path, alt text, action type, and timestamp. Indexed on attachment_id and action.
• Backup directory: wp-content/uploads/bdio-originals/{year}/{month}/ — Stores original images before optimization.
• WebP files: Stored alongside the original images in the standard WordPress uploads directory structure.

Uninstallation

If you uninstall (delete) BD Image Optimizer, the uninstall.php script removes the optimization log database table and the bdio_settings option. Backup originals in bdio-originals/ and generated WebP files are NOT automatically deleted — you would need to remove those manually via FTP or your hosting file manager if desired.