1 · Overview & System Architecture
Easy Media Optimiser is an all-in-one performance and hygiene suite engineered for WordPress media libraries. The plugin unifies two fundamental operations: deep filesystem and database auditing (Media Cleaner) and lossy/lossless image and video compression (Optimizer) under a streamlined administrative dashboard.
Core Philosophy
- Two-in-One Toolkit: Eliminates the need to run separate plugins for cleaning orphan uploads, generating WebP/AVIF images, transcoding videos, and optimizing database overhead.
- Zero Unchecked Deletions: All cleaner operations operate through multi-stage reference detection and sandboxed isolation before any physical file or database record is removed.
- Modular Architecture: Built defensively so that missing components or disabled features fail gracefully without causing runtime fatal errors or breaking the WordPress admin.
- Free & Pro Decoupling: The free base plugin (
easy-media-optimiser) contains the full local cleaner and optimizer engines, while the premium add-on (easy-media-optimiser-pro) activates video transcoding, AI vision integrations, cloud offloading, and advanced animation options.
Server & Environment Requirements
| Component | Minimum Requirement | Recommended Specification |
|---|---|---|
| WordPress | 5.8+ | 6.7+ (latest stable) |
| PHP Version | 7.4 | 8.2 - 8.4 (with OPcache active) |
| Image Processing | GD Library (with WebP support) | ImageMagick (Imagick 3.4+ with libwebp & libavif) |
| Video Transcoding | None (Video features disabled) | FFmpeg 4.4+ accessible via server PATH |
| PHP Memory Limit | 128 MB | 256 MB - 512 MB (for high-resolution batch jobs) |
Configuration Constants (wp-config.php)
Administrators and hosting providers can enforce global behaviors or disable specific subsystems by defining configuration constants in wp-config.php:
// Disable the Image Optimizer module and unhook all its upload listeners
define( 'EMOPT_DISABLE_OPTIMIZER', true );
// Disable the Media Cleaner module and hide its menu views
define( 'EMOPT_DISABLE_MEDIA_CLEANER', true );
// Override the vendor documentation endpoint
define( 'EMOPT_DOCS_URL', 'https://webpies.com/easy-media-optimiser-docs' );
// Activate offline developer mode for Pro license testing
define( 'EMOPT_PRO_LICENSE_DEV', true );
2 · Installation, Setup & Pro Licensing
00:00 Overview & System Architecture01:45 Deep Media Cleaner & Safety Scan03:30 Two-Phase Image Optimizer (WebP/AVIF)06:15 Video Transcoding (H.264 / AV1)08:30 Cloud Offload (AWS S3 & Cloudflare)10:45 License Activation & Domain TransferEasy Media Optimiser can be deployed either as a standalone free plugin or paired with the Pro add-on for enterprise workloads.
Step-by-Step Installation
- Free Base Plugin: Upload the
easy-media-optimiserfolder to/wp-content/plugins/(or install via the WordPress Plugins repository) and click Activate. - Admin Menu Activation: A new primary menu labeled Easy Media Optimiser will appear with dedicated dashboards for Image Optimizer, Media Cleaner, and Settings.
- Pro Extension (Optional): Upload the
easy-media-optimiser-profolder alongside the base plugin and activate it. The free plugin will automatically detect Pro presence and display the License (Pro) panel.
Paddle-Backed Licensing Architecture
Easy Media Optimiser Pro uses a cryptographic, single-domain seat model verified against WebPies's license server:
- Navigate to Easy Media Optimiser → License (Pro).
- Enter your license key formatted as
EMOPT-XXXX-XXXX-XXXX-XXXXand submit Activate License. - The plugin transmits an encrypted handshake containing the domain name, site title, WordPress version, and PHP version.
- Once verified, the server binds the domain seat and returns an authorization token. Pro features (video optimization, AI tools, cloud offloading) load immediately into memory.
Domain Migration & Seat Transfer
To transfer an active license from a staging site to a live production environment:
- On the existing site, click Remove license from this site on the License page, or simply deactivate the Pro plugin. The deactivation hook calls the remote endpoint to free your activation slot automatically.
- Navigate to your new destination site and enter the license key to bind the new domain.
- If an active license is activated on a second domain without releasing the first, the interface displays a clear notification identifying the existing domain and offering remote transfer options.
Developer & Localhost Testing Mode
For development in local environments (such as localhost, *.test, *.local, or DDEV), offline testing can be activated without communicating with remote servers by adding this flag to wp-config.php:
define( 'EMOPT_PRO_LICENSE_DEV', true );
In developer mode, keys matching EMOPT-TEST-* activate instantly and emulate production seat validation rules.
3 · Media Cleaner: Database Audit & Pruning
Over months and years of editorial changes, WordPress sites accumulate gigabytes of unreferenced images, orphaned thumbnails, and broken database attachments. The Media Cleaner engine executes a deep cross-referencing scan comparing the physical filesystem against every possible database reference.
Deep Scanner Algorithm
Unlike simplistic cleaners that only check post content, Easy Media Optimiser inspects every layer of the WordPress schema:
- wp_posts: Classic editor HTML, Gutenberg block JSON comment attributes, shortcodes, and post excerpts across all public and custom post types.
- wp_postmeta: Standard attachment associations (
_thumbnail_id), gallery lists, serialized metadata, and proprietary page builder data trees (Elementor JSON payloads, Divi builder codes, WPBakery markup). - wp_options: Customizer logos, header images, site favicons, widget payloads, and theme framework options.
- wp_termmeta: Category, tag, and product category banner images and icons.
- wp_comments: Avatars, user-submitted comment uploads, and embedded feedback imagery.
Status Classifications
| Status | Criteria | Action Recommended |
|---|---|---|
| Used | Actively referenced in published posts, pages, or active options. | Keep. Protected from deletion. |
| Was Used | Referenced only in trashed items, drafts, or post revisions. | Review. Reclaimable if drafts/trash are pruned. |
| Unused | Registered attachment in WordPress, but no references exist anywhere. | Safe to delete via bulk action. |
| Orphan | Physical file exists in /uploads/, but has no DB attachment record. |
Delete to reclaim disk space. |
| Missing | Attachment record exists in DB, but the file is gone from the disk. | Remove database ghost record to clean up media library. |
Safety & Sandboxed Deletion
When deleting registered items, the engine invokes wp_delete_attachment( $id, true ), which cleanly removes database rows, parent images, and all generated intermediate thumbnail sizes. Orphan file deletion utilizes realpath-sandboxed filesystem calls that strictly verify target paths reside within the configured WordPress uploads directory before executing an unlinking operation.
4 · Image Optimizer: Compression & Modern Formats
The Image Optimizer reduces photographic and graphic payload weights without compromising visual quality, leveraging a two-phase optimization algorithm.
The Two-Phase Compression Algorithm
- Phase 1 (Quality Binary Search): The optimizer iteratively tests JPEG/WebP quality parameters between 60% and 92% at native resolution to find the exact threshold meeting your configured byte target (default: 100 KB).
- Phase 2 (Proportional Downscaling): If the file size cannot reach the target even at the lower quality boundary, the engine preserves the aspect ratio and scales down the dimensions incrementally (e.g., from 4000px to 2400px), repeating Phase 1 until the target size is achieved.
Output Format Modes
- Keep Original Format: Compresses JPEG, PNG, and WebP files in place while retaining original file extensions (Included in Free).
- WebP (Replace): Converts images directly to WebP, updating the attachment record in
wp_postsand_wp_attached_fileon disk (Pro). - Side-by-Side WebP: Generates a companion
.webptwin alongside the original file. A front-endthe_contentfilter transforms<img>tags into<picture>elements, serving modern WebP to compatible browsers while delivering the original JPEG/PNG to legacy clients (Pro). - AVIF Conversion: Encodes images using the AV1 Image File Format, delivering up to 30–50% better compression ratios than WebP at comparable visual fidelity (Pro).
- Progressive JPEG: Re-encodes JPEG images with progressive scanlines, allowing images to render blurred immediately and sharpen as data streams in.
Quality Enhancements
- Color Profile Retention: Extracts and embeds ICC color profiles to prevent color-shift desaturation on wide-gamut displays (sRGB / Display P3).
- Unsharp Masking: Post-resize sharpening is applied automatically via Imagick (radius: 0.5, sigma: 1.0, amount: 0.8) to eliminate resampling blur.
- 4:4:4 Chroma Subsampling: When compressing above quality 80, the optimizer switches from 4:2:0 to 4:4:4 chroma subsampling, preventing color bleeding on sharp graphic edges and typographic artwork.
- Automatic Upload Trigger: Hooking into
wp_handle_upload, new uploads can be processed immediately in the background without requiring manual batch executions.
5 · Duplicate Media Detection & Re-Pointing
Content editors frequently re-upload the same product images, logos, or hero graphics under slightly different filenames or file formats. The Duplicate Detector identifies visual and binary redundancy across your entire library.
Dual Matching Engine
- Exact Byte Fingerprint (SHA-256): Computes cryptographic checksums for documents (PDFs, ZIPs), audio, video, and raw image files to identify 100% bitwise identical files.
- Perceptual Hashing (pHash): For images, the detector decodes pixels into a normalized 8x8 grayscale matrix and computes a Discrete Cosine Transform (DCT) frequency hash. This allows the system to identify duplicates even if an image was converted between formats (e.g.
hero.pngvshero.webp) or re-saved with metadata stripped.
Automated Reference Re-Pointing Engine
Deleting a duplicate image manually usually breaks links and leaves broken 404 image boxes across blog posts and shop pages. Easy Media Optimiser solves this with an automated re-pointing engine:
- When you select which duplicate to keep, the engine scans all references pointing to the duplicate IDs.
- It systematically updates:
- Featured image metadata (
_thumbnail_id). - Post content
<img src="..." class="wp-image-{id}">tags. - Gutenberg block gallery and image JSON attributes.
- Page builder components (Elementor, Divi, Beaver Builder JSON).
- Custom fields and theme settings.
- Featured image metadata (
- Only after all references are repointed to the primary image is the redundant attachment deleted.
6 · Video Optimizer & ffmpeg Transcoding (Pro)
Modern web video demands lightweight codecs that play smoothly on mobile devices without exhausting server bandwidth. The Pro Video Optimizer brings server-side FFmpeg transcoding directly into the WordPress dashboard.
Encoder Discovery & Fallback Chain
The plugin probes your hosting environment to identify compiled FFmpeg codecs and configures available options dynamically:
- H.264 / MP4 (libx264): The universal compatibility standard. Works across 100% of desktop, mobile, and smart-TV browsers.
- H.265 / HEVC (libx265): Next-generation high-efficiency video coding, ideal for Apple ecosystems and 4K media.
- VP9 / WebM (libvpx-vp9): Open-source Google standard offering superior web streaming performance for Chrome and Android.
- AV1 (libaom-av1 / libsvtav1): The cutting-edge royalty-free video format providing state-of-the-art compression efficiency.
- Auto Mode: Automatically selects the best supported format based on host capabilities and input video dimensions.
Transcoding Modes
- CRF (Constant Rate Factor): Maintains perceptual video quality while allowing bitrate to fluctuate based on motion complexity (values 18–28).
- Target File Size (MB): Calculates target bitrate dynamically using the video's total runtime duration to compress files down to a specific target weight (e.g. 5 MB).
Asynchronous Batch Processing
Video transcoding is computationally heavy. Easy Media Optimiser Pro runs jobs asynchronously with live progress percentage, elapsed time, ETA calculation, and the ability to pause or stop long queues without corrupting files.
7 · AI Content, Alt Text & Vision Suite (Pro)
Easy Media Optimiser Pro integrates with top vision AI providers to automate accessibility compliance, metadata translation, and visual image editing.
Supported AI Engines
- OpenAI Vision: GPT-4o and GPT-4 Turbo models for contextual scene analysis, accessibility auditing, and descriptive copy generation.
- Google Gemini Vision: High-speed image inspection and semantic taxonomy classification.
- remove.bg: Enterprise background cutout service providing precision alpha transparency for e-commerce products and portraits.
Smart Accessibility (Alt Text & Captions)
Missing image alt text harms search engine rankings and violates accessibility standards (WCAG 2.1 / ADA). Easy Media Optimiser Pro analyzes the visual contents of images and generates natural, descriptive alt texts and captions automatically.
// Example output generated automatically on upload:
Image: leather-boots-brown.jpg
Alt: Handcrafted brown leather ankle boots on rustic wooden flooring
Caption: Artisan leather boots with Goodyear welted soles
AI-Assisted Smart Compression
Instead of applying blanket compression numbers to every image, the AI Smart Compression engine examines visual frequency, color gradients, and text presence to dynamically recommend whether an image should be saved as WebP, AVIF, or JPEG and selects the optimal compression curve.
One-Click Background Removal
Directly inside the WordPress media modal or list view, clicking Remove Background sends the asset to remove.bg and saves a transparent PNG/WebP cutout as a new attachment alongside the original.
8 · Lazy Loading, Animations & SVG Spinners
De-prioritizing off-screen media loading is essential for achieving a 100/100 Google Lighthouse and Core Web Vitals score. Easy Media Optimiser provides a comprehensive front-end lazy loading engine.
Loading Strategies
- Native Browser Lazy Loading: Injects
loading="lazy"anddecoding="async"onto all content images and iframes with zero JavaScript overhead. - JavaScript Intersection Observer: High-precision view-threshold detection that supports custom root margins, placeholder transitions, and smooth entrance reveals.
6 Entrance Animation Reveal Modes
Transform standard abrupt image pop-ins into elegant visual transitions:
9 Animated SVG Spinners
Choose from 9 lightweight inline vector spinners to display while assets are streaming: Ripple, Ellipsis, Grid, Pulse, Dual Ring, Ring, Bars, Wave, and Orbit. Spinners render at a fixed 72px center bounding box, preventing layout shifts.
Embedded Video Facades
YouTube and Vimeo iframes download hundreds of kilobytes of third-party JavaScript before a user even interacts with the player. Easy Media Optimiser replaces embeds with lightweight thumbnail facades that load the real video player only upon a user click, dramatically reducing Total Blocking Time (TBT).
9 · Cloud Offload (S3), CDN & Google Drive (Pro)
High-traffic WordPress installations offload static media to external object storage and content delivery networks to reduce origin server load and ensure rapid global asset delivery.
S3-Compatible Cloud Storage Offload
Easy Media Optimiser Pro supports all standard S3 storage protocols:
- Amazon Web Services (AWS S3)
- Cloudflare R2 Storage (Zero egress fee architecture)
- DigitalOcean Spaces
- Google Cloud Storage
When offload is enabled, new uploads are transferred to your bucket automatically. You can choose to retain copies on local disk or purge local copies to preserve hosting storage limits.
Content Delivery Network (CDN) Integration
Point your media delivery to any global CDN (Cloudflare, KeyCDN, BunnyCDN, Fastly). The plugin rewrites URL paths on the fly via output buffering or URL filters without permanently mutating your database URLs.
Google Drive Media Hub & Scheduled Backups
- Media Library Import: Browse connected Google Drive folders directly inside the WordPress admin and import assets into your media library with one click.
- Scheduled Off-Site Backups: Schedule automated nightly or weekly snapshots of your optimized media library directly to Google Drive, ensuring off-site disaster recovery preparedness.
10 · Database Maintenance, Activity Log & API Hooks
Easy Media Optimiser includes built-in tools for maintaining database health, tracking optimization history, and integrating with custom development workflows.
Database Optimizer Subsystem
- Post Revisions: Prunes obsolete revision entries while keeping recent snapshots.
- Auto-Drafts & Trashed Content: Purges abandoned auto-drafts and empties post trash bins.
- Spam & Trash Comments: Deletes unapproved, spam, and trashed discussion records.
- Expired Transients: Flushes stale cached transient rows from
wp_options. - Orphan Metadata: Deletes orphaned
postmeta,termmeta, andcommentmetarecords pointing to nonexistent parent IDs. - Table Optimization: Executes
OPTIMIZE TABLEqueries across InnoDB tables to defragment storage and reclaim unallocated space.
Activity Logging & Backup Restore
Every optimization, file deletion, and database cleanup is recorded in an auditable event log. Furthermore, before any destructive file optimization occurs, original assets are archived into a protected backup folder at /wp-content/uploads/emopt-optimizer-backups/. The admin interface provides granular, single-item Undo and global Restore All actions.
Developer Filter Hooks
// Adjust the daily optimization cap for free users
add_filter( 'emopt_daily_cap', function( $cap ) {
return 100; // Allow 100 images per day
});
// Exclude specific file paths or directories from Media Cleaner
add_filter( 'emopt_cleaner_skip_paths', function( $paths ) {
$paths[] = 'custom-folder';
return $paths;
});
// Force custom JPEG quality for specific custom post types
add_filter( 'emopt_jpeg_quality', function( $quality, $attachment_id ) {
return 85;
}, 10, 2 );