About this plugin
HoatzinMedia is a WordPress media cleaner and storage optimizer that helps you reclaim disk space and improve site performance by identifying unused attachments, oversized uploads, and storage pressure signals. It includes a clear dashboard, a reversible trash workflow, and batch-based scanning designed for large media libraries.
Benefits:
- Reduce storage usage by finding unused and heavy media files
- Improve WordPress performance by keeping uploads lean and organized
- Delete with confidence using a safe trash table with restore support
- Scale to large sites with batch processing and scan locking
Modules
-
Dashboard
- What it does: Shows media health score, server/storage signals, and library breakdowns.
- REST endpoints: GET /wp-json/hoatzinmedia/v1/dashboard, GET /wp-json/hoatzinmedia/v1/dashboard/uploads-breakdown
- Hook points: Refreshes automatically after content changes via save_post cache bump; scan completion clears the dashboard transient.
-
Smart Scan & Unused Media
- What it does: Batch-based scanning to detect unused attachments, then review and delete safely.
- REST endpoints: POST /wp-json/hoatzinmedia/v1/scan, GET /wp-json/hoatzinmedia/v1/unused-results, POST /wp-json/hoatzinmedia/v1/delete-unused, POST /wp-json/hoatzinmedia/v1/delete-unused-all
- Hook points: WP-Cron action hoatzinmedia_scheduled_scan runs a full scan when scheduling is enabled; the scanner uses posts_where during content search to reduce query overhead.
-
Large Files Explorer
- What it does: Lists media files over a size threshold so you can quickly reclaim space.
- REST endpoints: GET /wp-json/hoatzinmedia/v1/large-files?size=1|3|5 (MB threshold)
-
Duplicate Checker
- What it does: Finds likely duplicate attachments and helps you validate before removal.
- REST endpoints: GET /wp-json/hoatzinmedia/v1/duplicates, GET /wp-json/hoatzinmedia/v1/attachment-usage?attachment_id=123
- Hook points: Adds Media Library UI enhancements via manage_upload_columns, manage_media_columns, and manage_media_custom_column.
-
Convert to WebP / AVIF
- What it does: Converts images to modern formats (WebP/AVIF) and manages converted variants.
- REST endpoints:
- Settings: GET/POST /wp-json/hoatzinmedia/v1/converter-settings, GET /wp-json/hoatzinmedia/v1/converter-settings/scan
- Converter: /wp-json/hoatzinmedia/v1/image-formats/library, /image-formats/convert, /image-formats/background, /image-formats/background/status, /image-formats/background/log, /image-formats/background/cancel, /image-formats/background/pause, /image-formats/background/resume, /image-formats/delete
- Hook points: add_attachment can auto-convert new JPEG/PNG uploads based on settings; delete_attachment cleans up converted variants; background jobs run on the hoatzinmedia_convert_job_run action.
-
Regenerate Thumbnails
- What it does: Rebuilds WordPress image sizes for selected attachments (useful after theme changes).
- REST endpoints: GET /wp-json/hoatzinmedia/v1/regenerate/library, GET /wp-json/hoatzinmedia/v1/regenerate/sizes, POST /wp-json/hoatzinmedia/v1/regenerate, plus background endpoints under /regenerate/background/*
- Hook points: Background jobs run on the hoatzinmedia_regenerate_job_run action.
-
Modules & Settings
- What it does: Enables/disables features and stores global plugin settings.
- REST endpoints: GET/POST /wp-json/hoatzinmedia/v1/modules, GET/POST /wp-json/hoatzinmedia/v1/settings, GET /wp-json/hoatzinmedia/v1/status
- Hook points: admin_menu registers the HoatzinMedia admin pages; init ensures scan scheduling and updates WebP serving rules when enabled.
-
SVG Upload Support (optional)
- What it does: Allows SVG uploads with sanitization safeguards (including Elementor compatibility).
- Hook points: upload_mimes, wp_check_filetype_and_ext, wp_handle_upload_prefilter, wp_handle_sideload_prefilter, elementor/files/allow_unfiltered_upload, elementor/files/allow-file-type/svg
Core features:
- Dashboard with media health score and live metrics
- Unused media scanner with batch processing and locking
- Safe trash table for reversible deletions
- Large file explorer by size threshold
- Translation-ready UI and REST responses
Usage
- Review the media health score and high-level stats on the dashboard.
- Run an unused media scan from the Unused media scanner panel.
- Inspect results and move files to the HoatzinMedia trash.
- Use the large file explorer to identify heavy attachments by size.