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: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: swissspidy <swissspidy@git.wordpress.org>

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

[andrewserong]

Thanks for looking into this.

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.

Before reviewing, we're now past Beta 1 and this sounds like a new feature to me. Should we be pursuing this, or focusing on bug fixing / polishing tasks?

I.e. #80268 definitely sounds good to fix for the release, but I'm wondering where we should draw the line with the available time we have left for the release (and since we're both also trying to polish other features, too). Just feeling mindful of the time and attention we have to polish these things, but don't want to be a blocker needlessly of course!

[t-hamano]

I don't fully understand client-side media, but is my understanding correct?

• Before #80268: uncropped sub-sizes preserved animation.
• #80268: all sub-sizes are flattened to the first frame (for core consistency and performance).
• #80385: the #80268 behavior remains the default. Only when the filter is enabled do uncropped sub-sizes preserve animation again.

Generally, new features cannot be added after the Beta phase. I believe this applies not only to the core but also to Gutenberg. Since this PR introduces a new filter, I consider it to be a new feature addition.

Can we punt this PR to 7.2 and focus on #80268? Even if #80268 is merged, it should not be a regression as it only aligns with the core behavior. I think it would be better to focus on bug fixes for now.

[adamsilverstein]

I don't fully understand client-side media, but is my understanding correct?

• Before #80268: uncropped sub-sizes preserved animation.
• #80268: all sub-sizes are flattened to the first frame (for core consistency and performance).
• #80385: the #80268 behavior remains the default. Only when the filter is enabled do uncropped sub-sizes preserve animation again.

Generally, new features cannot be added after the Beta phase. I believe this applies not only to the core but also to Gutenberg. Since this PR introduces a new filter, I consider it to be a new feature addition.

Can we punt this PR to 7.2 and focus on #80268? Even if #80268 is merged, it should not be a regression as it only aligns with the core behavior. I think it would be better to focus on bug fixes for now.

Your understanding is correct, the description is accurate.

We are merging #80268 once CI passes; it is approved.

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!

[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