HoatzinMedia — Media Cleaner & Storage Optimizer

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:

1. Reduce storage usage by finding unused and heavy media files
2. Improve WordPress performance by keeping uploads lean and organized
3. Delete with confidence using a safe trash table with restore support
4. Scale to large sites with batch processing and scan locking

Modules

1. 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.

2. 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.

3. 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)

4. 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.

5. 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.

6. 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.

7. 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.

8. 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:

1. Dashboard with media health score and live metrics
2. Unused media scanner with batch processing and locking
3. Safe trash table for reversible deletions
4. Large file explorer by size threshold
5. Translation-ready UI and REST responses

Usage

1. Review the media health score and high-level stats on the dashboard.
2. Run an unused media scan from the Unused media scanner panel.
3. Inspect results and move files to the HoatzinMedia trash.
4. Use the large file explorer to identify heavy attachments by size.