Client-side image processing ready for testing; reduces server load

Client-side media processing is a progressive enhancement to WordPress’s existing server-based media pipeline. When a user uploads an image in the block editor, their browser decodes, resizes, and encodes all sub-sizes locally using the VIPS image processing library running in WebAssembly (via wasm-vips) before sending them to the server. Browsers that can’t handle the work silently fall back to the existing server-side path without user-visible errors.

The advantage of this approach is that we can provide a uniform, modern image processing experience across all WordPress sites without relying on server-side capabilities. The client-side pipeline supports modern formats (AVIF, WebP, HEIC, UltraHDR, JPEG XL), offering better compression, and more consistent resizing quality regardless of hosting environment. It also reduces CPU and memory load on the server during image uploads by offloading the work to capable devices.

The feature graduated from a Gutenberg experiment to a core Gutenberg feature during the 7.0 cycle and is now targeting WordPress 7.1 as a core capability.

With 7.1 on the horizon, the feature could use testing to help us shake out bugs, validate performance on real content and devices, and stress-test the new capabilities.

Tracking issues:

#76756 — Client Side Media iteration for WordPress 7.1

#74333 — Client Side Media iteration for WordPress 7.0 (previous cycle, closed)

What’s included in this round of testing

The 7.1 iteration tracked in #76756 builds on the 7.0 groundwork and adds several new capabilities. Highlights include improved format support, error handling and upload resilience.

A note on bundle size

Download weight and the lack of new capabilities was the biggest piece of feedback during the 7.0 cycle, so it has been a focus this iteration. Client-side processing now exceeds the format and quality capabilities of the best server-side setups, while loading less ahead of time than the 7.0 prototype

• Nothing heavy loads up front. The WebAssembly image pipeline (wasm-vips and friends) is fetched on demand the first time a user uploads media – it is not part of the editor’s initial bundle.
• New capabilities UltraHDR, HEIC and JPEGXL support, as well as the new GIF→video conversion feature, are all new capabilities and added minimal weight.

How to test

Please run through as many of the scenarios below as your environment allows, and report anything that looks wrong — slow, broken, unexpectedly falling back to server-side, visibly lower quality, etc. Test with the latest Gutenberg plugin and in a chromium browser for the feature to be active.

System and Browser Requirements

• Non-Chromium browsers: Disabled by default because Firefox and Safari don’t support Document-Isolation-Policy. The HEIC canvas fallback still runs in Safari.
• Low-memory devices: Devices reporting 2 GB of RAM or less are excluded.
• 2g / slow-2g / Browsers sending the Save-Data header: Excluded because of the large worker download and increased upload bandwidth.
• CSP restrictions: Sites with worker-src directives that don’t allow blob: fall back to server-side.

You can verify that the feature is active by checking window.__clientSideMediaProcessing in the browser console (should be true), or by looking for network requests to the sideload endpoint. You can also use this mini plugin to check the upload processing type (client or server) – it shows a label on the front end and adds a column to the Media library list view.

1. Baseline upload flow

• Upload a handful of JPEGs, WebPs, HEICs, AVIFs, GIFs and PNGs (mix of sizes: ~500 KB, ~5 MB, and a >20 MB original) in the editor.
• Confirm the Image block renders the uploaded image.
• Verify all expected sub-sizes exist on disk.
• Compare file sizes and visual quality to the same image uploaded using the media library (which uses server processing).
• Test uploading avif, webp, heic, png (with various transparency and bit depths), and jpg files and confirm they are processed correctly.

2. HEIC (iPhone photos)

• Upload a `.heic` image from an iPhone. Use your computer to do the upload (the iPhone’s uploader will automatically convert to JPEG before upload, so you won’t be testing the client-side features if you upload directly from the phone).
• Confirm it is transcoded to a web format (JPEG/WebP/AVIF depending on your settings) and that sub-sizes are generated.
• Confirm the original HEIC is also uploaded and preserved.
• Confirm Portrait and Landscape HEICs work correctly.
• Try a browser that lacks native HEIC decoding to verify the canvas fallback – see #76731 for browser support details.

3. Modern output formats (AVIF / WebP)

• use the image_editor_output_format filter to output different formats from jpeg uploads.
• test uploading avif, webp, heic, png (with various transparency and bit depths), and jpg files and confirm they are processed correctly according to the configured output format.
• Upload a large JPEG and confirm sub-sizes are emitted in the configured format, including the -scaled variant.

4. Ultra HDR

• Testable in #74873
• Upload an Ultra HDR image (you can capture one on a recent Pixel or iPhone, or download samples from gainmap-js demos).
• Confirm the gain map is preserved through resizing and that sub-sizes still render as HDR on a capable display/browser.

5. JPEG XL (JXL)

• Testable in #77584.
• Upload a `.jxl` image (sample gallery).
• Confirm it is accepted and processed. Report any unexpected behavior.

6. Animated GIF → video

• Ready to test once #76946 merges
• Upload a large animated GIF.
• Confirm it is converted to an MP4 or WebM (depending on implementation), and that the resulting block plays correctly in the editor and on the front end.

7. Batch and concurrent uploads

• Drag-and-drop 10–20 images at once into the Image block or Media Library.
• Watch for progress UI, confirm all uploads complete, and check timing against a baseline where client-side is disabled.

8. Resilience

• Test in #76765.
• Use browser dev-tools to simulate a slow/flaky network during a batch upload and confirm retry behavior.
• Try to save a post mid-upload and confirm the editor prevents or defers the save #76973.
• Upload something, then refresh mid-upload — confirm the editor recovers cleanly.

9. Fallback paths

• Test in a browser that does not meet capability requirements (Safari, Firefox)
• Confirm the upload succeeds via the server-side path without user-visible errors. The only signal should be a developer-console message.

10. Extensibility

• If you maintain a media-related plugin (image optimizers, DAM integrations, custom workflows), try it against a site with client-side media enabled.
• Exercise the new filters/actions from #74913 and report any gaps.
• Test disabling Client-side media.

11. Low-powered devices

• Test on a low-end laptop, older Chromebook, or mid-range phone.
• Confirm that the capability detection correctly gates the feature off when the device is underpowered and that processing does not lock up the browser.

Questions & bugs

Please report bugs by opening issues on the Gutenberg repo tagged with [Feature: Client Side Media]. Or, leave questions or comments on the tracking issue.

Thank you

Client-side media is a substantial shift in how WordPress handles images, and it only ships well with real-world testing across the full diversity of WordPress sites, browsers, and devices. Every report helps!

Props

Thanks to @jorbin and @ozgursar for reviewing this post!

#call-for-testing, #media