HoatzinMedia — Library Cleaner & Storage Optimizer

Quick start

1. Install and activate the plugin.
2. Open WP Admin → HoatzinMedia.
3. Run a smart scan and review the unused results list.
4. Before deleting anything: verify usage (usage button) and take a backup.
5. Optional: convert images to WebP/AVIF and regenerate thumbnails.

Installation

Requirements

Install

1. Upload the hoatzinmedia-library-cleaner folder to /wp-content/plugins/.
2. Activate HoatzinMedia from Plugins.
3. Open WP Admin → HoatzinMedia.

Overview

HoatzinMedia helps you understand and reduce media bloat: it can find unused attachments, highlight large files, show where a media item is used, regenerate thumbnails, and convert images to modern formats.

Modules

HoatzinMedia uses a modular UI. You can enable/disable modules in the Modules tab. Disabled modules are hidden from the menu.

Available modules

• Dashboard: overview metrics and server requirements.
• Smart Scan & Unused Media: run unused scan, review results, delete unused.
• Large Files: lists attachments over a size threshold.
• Duplicate Checker: duplicate grouping (strategy: hash or legacy path).
• Convert (WebP / AVIF): conversion settings and conversion jobs.
• Regenerate Thumbnails: rebuild intermediate sizes.
• Settings: global plugin settings.

Smart scan & unused media

The Smart Scan checks each attachment and determines whether it is referenced by your site. The results are stored and shown in a paginated list.

What “unused” means

An attachment is treated as used if it is referenced by common WordPress/WooCommerce signals. Examples include:

• Site icon or custom logo
• WooCommerce placeholder image
• Featured image
• WooCommerce product galleries
• URLs or filenames found in post content
• References stored in common builder metadata

How to run a scan

1. Go to WP Admin → HoatzinMedia → Smart Scan & Unused Media.
2. Click Run smart scan.
3. Wait for the scan to finish; scanning is batch-based to be friendlier on large libraries.
4. Review results in the Unused media files list.

Deleting unused items

1. Select one or more items.
2. Click Delete selected.

Large files

The Large Files tool lists attachments over a selected threshold so you can quickly spot storage hogs.

How to use

1. Open WP Admin → HoatzinMedia → Large Files.
2. Select a threshold: 1 MB, 3 MB, or 5 MB.
3. Review results (sorted by size) and decide whether to compress, replace, or remove files.

Duplicate checker

Duplicate checking groups attachments that appear to be the same file. Two strategies are available:

• Hash strategy (recommended): groups by file content hash (md5 of the underlying file path).
• Path strategy (legacy): groups by the stored _wp_attached_file meta value.

Convert to WebP / AVIF

Convert JPEG/PNG images into modern formats (WebP/AVIF). HoatzinMedia supports both immediate conversion and background conversion jobs.

Before you convert

• Take a full backup (conversion can overwrite originals depending on your workflow).
• Confirm your server image editor supports the target format (GD/Imagick capabilities vary by host).
• Start with a small batch and validate frontend output (theme, CDN, caching).

Converter settings

Open the converter settings panel and configure:

• Scope: uploads only, or uploads + theme directories (for scanning sources).
• Image types: JPEG, PNG, or both.
• Destination folder: separate folder or same folder.
• File extension handling: append or replace extension (WebP/AVIF variants).
• Destination structure: mirror source structure, image roots, or flat.
• Cache control: optional caching header behavior for served files.
• Prevent larger conversions: skip WebP output if it would be larger than the source.

Conversion modes

• Convert now: converts selected IDs directly.
• Background job: enqueues a job, then you can check status/logs and pause/resume/cancel.

Regenerate thumbnails

Regenerating thumbnails recreates intermediate image sizes (registered by WordPress, themes, and plugins). This is useful after changing image sizes or switching themes.

How to use

1. Go to WP Admin → HoatzinMedia → Regenerate Thumbnails.
2. Select items (or choose the global select option).
3. Click Regenerate thumbnails and confirm.
4. Review any errors and re-run for failed items if needed.

Media library enhancements

HoatzinMedia can enhance the built-in Media Library to make day-to-day cleanup easier.

Media stats strip (grid view)

• Shows total media count and counts by type (images, video, audio, documents) in the Media Library grid view.
• Automatically positions itself even if other plugins modify the media header area.

File extension label (optional)

• Adds a small label like webp, jpg, png on each grid item.
• Enable it from Settings (see Settings).

Attachment usage (optional)

• Adds a “Usage” action to help confirm where a file is referenced before deleting it.
• Requires logged-in users with upload permissions and a valid REST nonce.

Settings

Open WP Admin → HoatzinMedia → Settings to configure global behavior.

General settings

• Max file size: used by some modules to prioritize heavy assets.
• Scan schedule: manual, every 3 hours, daily, weekly, monthly.
• Items per page: pagination size for certain lists.
• Unused media age (days): helps tune what “recent uploads” should be treated as (0–3650).

Media Library UI

• Enable image extension label: show extensions on Media Library grid items.
• Enable media usage button: show usage details in the Media Library.

WebP serving & quality

• Enable WebP serving: may update rewrite rules for serving WebP where applicable.
• WebP quality: 1–100.
• Auto-convert uploads: disabled, WebP, or AVIF.

Troubleshooting

Smart scan shows files as unused but they are used

• Check if the file is used in theme CSS, custom blocks, shortcodes, or a builder not covered by scanner patterns.
• Use the Media Library “Usage” feature to confirm detected usage contexts.
• Run scan again after clearing caches and updating content.

Conversion fails or formats are unsupported

• Verify GD/Imagick is installed and supports WebP/AVIF on your server.
• Try a smaller batch and check the background job log for details.
• Confirm filesystem permissions to create new files in uploads.

Regenerate thumbnails is slow

• Large libraries can take time. Regenerate in smaller batches.
• Ensure your PHP memory limit and execution time are adequate.

Developer notes

HoatzinMedia uses REST endpoints under /wp-json/hoatzinmedia/v1. Most endpoints require manage_options plus a valid X-WP-Nonce header.

Common REST endpoints

GET    /hoatzinmedia/v1/dashboard
POST   /hoatzinmedia/v1/scan
GET    /hoatzinmedia/v1/unused-results?page=1&limit=20
POST   /hoatzinmedia/v1/delete-unused
POST   /hoatzinmedia/v1/delete-unused-all
GET    /hoatzinmedia/v1/large-files?size=3&page=1&per_page=20
GET    /hoatzinmedia/v1/duplicates?strategy=hash&page=1&per_page=20
GET    /hoatzinmedia/v1/attachment-usage?attachment_id=123&limit=20
GET    /hoatzinmedia/v1/settings
POST   /hoatzinmedia/v1/settings
GET    /hoatzinmedia/v1/converter-settings
POST   /hoatzinmedia/v1/converter-settings
GET    /hoatzinmedia/v1/image-formats/library?page=1&per_page=20
POST   /hoatzinmedia/v1/image-formats/background
GET    /hoatzinmedia/v1/image-formats/background/status?job_id=...
GET    /hoatzinmedia/v1/regenerate/library?page=1&per_page=20
POST   /hoatzinmedia/v1/regenerate

Translation

For translation, reference the hoatzinmedia-library-cleaner text domain used across PHP and JavaScript.