Media: Add an opt-in filter to generate animated image sub-sizes

[adamsilverstein]

What?

Adds a developer opt-in filter, wp_generate_animated_image_subsizes, that re-enables animated (multi-frame) sub-size generation for animated GIFs in the client-side media processing pipeline:

add_filter( 'wp_generate_animated_image_subsizes', '__return_true' );

Fixes #80383.
Also fixes the 12-year-old core request Trac #28474 - "WordPress destroys animation in animated GIF when it resizes", as proposed in comment:58.

Core backport: Trac #65656 / WordPress/wordpress-develop#12572.

Note

Stacked on #80268, which makes static first-frame sub-sizes the default. This PR adds the opt-in path back on top of it. Only the last commit is new; review the diff from fix/animated-gif-subsize-performance.

Why?

#80268 switched sub-sizes of animated GIFs to static first-frame images, matching what WordPress core has always done server-side, because full animated re-encodes were extremely expensive (~88 s combined for a 769-frame GIF, with sub-sizes larger than the original - see #80266).

But there is long-standing, sustained demand for resized GIFs that keep their animation: Trac #28474 has been open since 2014 and stalled server-side because GD cannot do it and Imagick is only available on a subset of hosts. Client-side processing sidesteps both constraints - the cost is paid once in the uploading user's browser, and wasm-vips is available regardless of host configuration. That makes animated sub-sizes reasonable as an explicit developer opt-in while keeping the fast, core-consistent static behavior as the default.

How?

The flag follows the exact same path as image_strip_meta / image_max_bit_depth (#80218):

1. PHP (lib/media/load.php): wp_generate_animated_image_subsizes (boolean, default false) is applied in gutenberg_media_processing_filter_rest_index() and exposed as animated_image_subsizes on the REST API root index. The field is also added to the preload/entities field lists (lib/compat/wordpress-7.1/preload.php, packages/core-data/src/entities.js), which must match exactly.
2. Editor settings: mapped to a generateAnimatedImageSubsizes setting in use-block-editor-settings.js and forwarded by use-media-upload-settings.js.
3. Upload pipeline: resizeCropItem reads the setting from the @wordpress/upload-media store and passes it to the vips worker as a new preserveAnimation option on resizeImage() (options object from Client Side Media: Consolidate optional positional params into options objects in vips / upload-media #80328).
4. Vips: when preserveAnimation is set and the resize is uncropped, resizeImage() restores the pre-Client-side media: generate animated image sub-sizes from the first frame only, matching core #80268 [n=-1] load path so all frames are decoded and re-encoded. Cropped sizes (e.g. thumbnail) always flatten to the first frame, matching the pre-existing behavior - per-frame smart-cropping is out of scope.

Tuned gifsave settings

The profiling in #80266 showed ~85% of the animated resize cost is GIF re-encoding (per-frame palette quantization), and that default gifsave settings cause the output-larger-than-input bloat. When writing an animated GIF, this PR applies the settings benchmarked there:

• effort: 2, interframe_maxerror: 8, interpalette_maxerror: 16 - measured 4-8x faster and eliminates the size bloat.

That turns the opt-in cost from ~88 s into roughly 10-20 s for a very large GIF - still too slow to be the default, but a reasonable trade for a site that has explicitly chosen animated sub-sizes.

Notes

• The filter name says "animated image", not "GIF", deliberately: vips can also preserve frames for animated WebP, and APNG has come up on the Trac ticket. This implementation is exercised with GIFs; the door is open.
• Core's wp_calculate_image_srcset() still never mixes the full-size GIF and its sub-sizes in one srcset. With animated sub-sizes that guard becomes overly conservative but harmless; relaxing it is a server-side follow-up.
• Server-side uploads (Media Library taking the server path) still produce static sub-sizes, so enabling the filter reintroduces a difference between upload surfaces - this time as an explicit developer choice. Documented on the filter.
• Guardrail interplay with Client-side media: add timeout and size guardrails to GIF to video conversion #80376 (timeout/pixel budgets, falling back to a static sub-size) is a follow-up once Media: Add timeout and size guardrails to client-side GIF to video conversion #80379 lands.

Testing Instructions

1. Enable the filter, e.g. in a mu-plugin: add_filter( 'wp_generate_animated_image_subsizes', '__return_true' );
2. In the block editor, upload an animated GIF to an Image block and wait for the upload to finish.
3. Inspect the attachment's medium / large sub-sizes (e.g. via /wp-json/wp/v2/media/<id>): they should be animated GIFs (multiple frames), while thumbnail (cropped) remains a static first frame.
4. Without the filter, all sub-sizes remain static first-frame images (the Client-side media: generate animated image sub-sizes from the first frame only, matching core #80268 default), and the existing e2e test covers this.

Documentation

The client-side media docs (#75895) are updated alongside: the how-to guide gains an "Animated image sub-sizes" section for the new filter, and the architecture reference adds it to the filter table and REST index field list (plus corrects the now-stale note that sub-sizes preserve all frames).

Automated tests

• packages/vips/src/test/resize-image.ts: new preserveAnimation suite - [n=-1] + tuned gifsave for uncropped animated resizes, first-frame flattening for crops, no effect on still formats.
• phpunit/media/media-processing-test.php: REST index exposes generate_animated_image_subsizes (default false, honors the filter, hidden without upload_files).
• test/e2e/specs/editor/various/gif-to-video.spec.js: new test uploads an animated GIF with the filter enabled (via a new e2e test plugin) and asserts the medium sub-size keeps all frames.

npm run test:unit packages/vips/src/test/
vendor/bin/phpunit phpunit/media/media-processing-test.php
npm run test:e2e -- test/e2e/specs/editor/various/gif-to-video.spec.js

[github-actions]

Size Change: +264 B (0%)

Total Size: 7.73 MB

📦 View Changed

Filename	Size	Change
build/modules/vips/worker.min.js	3.69 MB	+97 B (0%)
build/scripts/block-editor/index.min.js	421 kB	+21 B (0%)
build/scripts/components/index.min.js	272 kB	+76 B (+0.03%)
build/scripts/core-data/index.min.js	31.9 kB	+19 B (+0.06%)
build/scripts/editor/index.min.js	499 kB	+39 B (+0.01%)
build/scripts/upload-media/index.min.js	15.5 kB	+12 B (+0.08%)

_{compressed-size-action}

[adamsilverstein]

Core backport of the server-side changes: WordPress/wordpress-develop#12572 (draft; Trac ticket to follow).

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: swissspidy <swissspidy@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: annezazu <annezazu@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[t-hamano]

We do sometimes add enhancements to new features introduced in a cycle during beta such as this filter. That said, I am also fine leaving it for 7.2!

Understood. If so, I would be happy if we could merge this at an early stage. Will this PR and the core backport PR make it in time for Beta2? Also, it would be good to add an explanation of the new filters introduced in this PR to the dev note for client-side media.

[swissspidy]

Nit: can we rename the flag?

animated_image_subsizes / animatedImageSubsizes doesn't make it obvious that it's a boolean.

Maybe prefix with "generate" or so.

[adamsilverstein]

Understood. If so, I would be happy if we could merge this at an early stage. Will this PR and the core backport PR make it in time for Beta2?

If approved, I can definitely land this and the backport before Beta 2.

[adamsilverstein]

Renamed in f976f20: the REST index field is now generate_animated_image_subsizes and the editor setting generateAnimatedImageSubsizes, matching the wp_generate_animated_image_subsizes filter they carry.

Also merged trunk to resolve the conflicts, and documented the new filter in the client-side media docs (10a1b7c).

[adamsilverstein]

That turns the opt-in cost from ~88 s into roughly 10-20 s for a very large GIF - still too slow to be the default, but a reasonable trade for a site that has explicitly chosen animated sub-sizes.

Honestly 10-20 seconds doesn't seem like that long, but still is a significant change in behavior (storage also increases) so probably not what we want to make the default? Curious what others think the default behavior should be?

Regardless, making it filterable seems like a good idea!

cc: @swissspidy & @andrewserong

[adamsilverstein]

Also, it would be good to add an explanation of the new filters introduced in this PR to the dev note for client-side media.

I added it to docs in this PR in 10a1b7c and will add to my make core post (as yet unpublished) if merged.

[adamsilverstein]

Nit: can we rename the flag?

@swissspidy always appreciate the naming support! Renamed in f976f20

[andrewserong]

Honestly 10-20 seconds doesn't seem like that long, but still is a significant change in behavior (storage also increases) so probably not what we want to make the default? Curious what others think the default behavior should be?

For me, these sorts of questions mean that I think we should park this feature for 7.1 and give it more time to explore for 7.2+. Speaking for myself, I'm a little spread thin across 7.1 features that I'm trying to support, and I'd be keen for us to carefully contain scope here if we can.

It also seems that in order for GIF sub-size processing to feel stable, we'll need more UI state in order to balance out the longer processing time (#80329).

Taken together, this feels like a good well-scoped feature for 7.2 ("WP now preserves animated GIFs at all image sub-sizes"), whereas in the context of client-side media processing, this seems more the nice-to-have territory than must have.

What do you all think? I'll just ping @annezazu for visibility on this one, too, as I want to make sure I'm helping out with the high priority features in the release. (If this is high priority, happy to help review of course).

[swissspidy]

I'll defer the final call to someone else, but code-wise this LGTM. It's a low-risk opt-in filter for devs who really would like to have animated thumbnails and are aware of the trade-offs.

[t-hamano]

Suggested change

	* @since 23.7.0
	* @since 23.6.0

Nit: I intend to backport this PR not only to 7.1 but also to Gutenberg 23.6.

[annezazu]

Hey folks! Thanks for tagging me in this. I read through the issue and, zooming out across the release, I'd like this to be punted to 7.2. This is a conservative decision and it comes from not looking solely at just this isolated change but looking at the weight of all of the features across the release when combined against the collective capacity of our current active contributors. Put another way, we already have a lot of features that we will need to be ready to do bug fixes for during beta and I'm hesitant to continue adding to it. Looking at this in isolation, I can see how it's lower risk since it's a dev focused change but it's not zero risk and everything we add takes up review time.

We do sometimes add enhancements to new features introduced in a cycle during beta such as this filter. That said, I am also fine leaving it for 7.2!

Relatedly, client side media wasn't noted as an area to be "blessed" and I want to honor that original commitment when it was discussed previously. Otherwise, it becomes easy to start "moving the goal posts" late in the game and I don't believe in doing that, unless project leadership overrides something.

[adamsilverstein]

Hey folks! Thanks for tagging me in this. I read through the issue and, zooming out across the release, I'd like this to be punted to 7.2.

That makes sense, thanks for deciding! We will wait until 7.2 to land this one.