Animated GIF to video conversion (via mediabunny)

[adamsilverstein]

What

This PR adds client-side animated GIF to video conversion to the block editor.

When an animated GIF is uploaded, the new pipeline converts it to an MP4 (or WebM) client-side using the browser's native WebCodecs ImageDecoder for frame extraction and the mediabunny library for encoding. The converted video is stored as a companion file of the original GIF attachment, and the editor switches the block to a "GIF" variation of the Video block that plays just like the original animated GIF.

This is a standalone alternative to #76946 (which used inlined FFmpeg WASM); see Why and Supersedes.

Fixes #76942

Why

Bundle size and hardware-accelerated encode performance.

Approach	Worker bundle (raw)	Worker bundle (gzipped)	Total shipped JS
#76946 (FFmpeg WASM, inlined)	~14.1 MB	~14.1 MB	~14.1 MB
This PR (WebCodecs + mediabunny)	~380 KB	~77 KB	~775 KB total .mjs

Since WebCodecs encoding is hardware-accelerated on supported platforms, conversion is also significantly faster than software-only FFmpeg WASM.

How

Conversion pipeline (off the main thread)

1. @wordpress/video-conversion package (new): mirrors the @wordpress/vips worker-threads pattern. A web worker is bundled with the mediabunny library and exposed via a Comlink-style proxy. The main thread calls convertGifToVideo(file, mimeType), which runs fully off the main thread.
2. Frame pipeline (src/index.ts): ImageDecoder decodes each GIF frame, honoring real per-frame delay values. Each decoded VideoFrame is fed to mediabunny's VideoSampleSource, then encoded via VideoEncoder (AVC/H.264 for MP4, VP9 for WebM).
3. @wordpress/upload-media integration: a new OperationType.TranscodeGif operation, an isAnimatedGif() utility (GIF89a Graphic Control Extension detection), and a transcodeGifItem() action wired into prepareItem(). Conversion is gated on WebCodecs availability at prepareItem time, runs with a concurrency limit of 1 (memory-intensive encode), and falls back gracefully: an Unsupported error from the worker leaves the original GIF in the queue.

Storage model (companion files)

An uploaded opaque animated GIF stays a single core/image attachment - it remains one item in the media library. The converted video and a static first-frame poster are sideloaded as companion files of that same attachment (like the HEIC original), recorded in media_details.animated_video and animated_video_poster. They are never separate attachments.

Note: Transparent GIFs are not converted (a <video> cannot reproduce GIF transparency), so they have no companion and upload as a normal image.

Editor block switch

The GIF→video swap happens in the editor as a block switch, not at render time.

• A "GIF" variation of the Video block. core/video gains two variations, "Video" and "GIF", identified purely by their attribute combination (!controls && loop && autoplay && muted && playsInline) - no new block attribute. The GIF variation is scoped to block + transform (not the inserter), since it is the editor representation of a converted GIF. Its editor preview plays like a GIF (muted, looping, autoplaying).
• Conversion is a block switch on upload. Once the companion video is available, a standalone Image block is replaced with the Video block's GIF variation playing the companion. Images nested in a Gallery are left as GIFs (a gallery only accepts image blocks); Media & Text / Cover are unaffected (their media is not a core/image block). A .gif-URL gate keeps non-GIF images from triggering an attachment fetch, and a client-id guard keeps undo from immediately re-converting.
• Fully reversible. A "Display as GIF" toolbar control on the GIF video block switches it back to the original core/image (and opts it out of re-conversion). The Image block's "Display as original GIF" toggle (preserveAnimatedGif) controls this editor conversion, so the round-trip is reversible.
• Native rendering, no render-time PHP. Because the converted block is a real core/video, it serializes a native <video autoplay loop muted playsinline poster> and renders on the front end with no filtering.

PHP (minimal)

• Enqueues the @wordpress/video-conversion/loader script module in the editor (lib/client-assets.php).
• Allows the converted video and poster as valid sideload sizes on the attachment (class-gutenberg-rest-attachments-controller.php).
• Cleans up the sideloaded companion video and poster when their attachment is deleted, since core's wp_delete_attachment_files() does not know about them (lib/media/animated-gif-to-video.php).

Scope & browser support

Client-side media already requires Document Isolation Policy globally (for SharedArrayBuffer / crossOriginIsolated). This PR does not change that requirement, and Firefox (which lacks VideoEncoder) is out of scope for both approaches. The conversion path is gated on typeof ImageDecoder !== 'undefined' && typeof VideoEncoder !== 'undefined' and falls back gracefully to uploading the original GIF when WebCodecs is unavailable.

Screencasts

Uploaded GIF converted to GIF video block, then transformed to regular video block:

covert.to.gif.block.mp4

Transformed video, restore to show as GIF instead:

convert.to.gif.mp4

Testing

Test in Playground: https://playground.wordpress.net/?gutenberg-pr=78410

Verified manually end-to-end (see screencasts above): uploading an animated GIF converts it to the Video block's GIF variation, the front end renders a native looping <video>, and the round-trip back to the original GIF works in both directions.

Automated coverage:

• Unit tests for the mediabunny pipeline, isAnimatedGif, store selectors, and prepareItem wiring: 21 suites / 214 tests, all passing.
• Unit tests for the core/video GIF variation (isGifVariation detection; exactly one active variation; not in the inserter).
• PHP unit tests for the companion path resolution (including directory-traversal safety) and companion cleanup on attachment delete.
• E2E spec at test/e2e/specs/editor/various/gif-to-video.spec.js: uploads an animated GIF via the Image block and asserts the block is switched to the Video block's GIF variation playing the converted companion, while the attachment remains the original image/gif with the companion recorded in media_details.animated_video. The spec skips automatically if WebCodecs or cross-origin isolation is not active. PHP/E2E run in CI (wp-env was unavailable locally).

Changes from earlier revisions

Following review feedback (h/t @andrewserong and @swissspidy), the GIF→video swap moved from a render-time PHP filter to an editor block switch (the "GIF variation of the Video block" idea from the review thread). This removed most of the feature's PHP: the render_block_core/image marking filter and the wp_content_img_tag <img>→<video> swap are gone (~208 lines of PHP removed), leaving only companion cleanup on delete. The upload/conversion pipeline and the companion-file storage model are unchanged; only where the swap happens moved.

Supersedes

This PR consolidates the full GIF→video feature on the mediabunny/WebCodecs engine and replaces the FFmpeg-WASM stack:

• Supersedes Client-side media: Add animated GIF to video conversion (MP4/WebM) #76946 (FFmpeg-WASM conversion) — being closed in favor of this PR.
• Supersedes Client-side media: Transform image block to video block after GIF conversion #78369 (the ffmpeg-stacked render-swap/feedback PR) — its functionality is included here.

References

• FFmpeg WASM alternative: Client-side media: Add animated GIF to video conversion (MP4/WebM) #76946

[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: ramonjd <ramonopoly@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.

[adamsilverstein]

@andrewserong & @swissspidy - this one is ready for review :)

[swissspidy]

I wonder if we could come up with a more generalized way of enforcing concurrency limits for specific operations. Perhaps in the future.

[Mamaduka]

A nice feature, though I think it does a lot of the work on the user's behalf. I understand that using videos instead of GIFs is better for performance, but it's still confusing to have the conversion done automatically.

Related notes:

• New toolbar controls are too prominent, and toolbars always have a problem with space. Maybe we should use block transformations.
• Toolbar items are displayed even if the target block is disabled.
• They also use icon + text combo. Usually, it's one or another.
• What's the status of the new @wordpress/video-conversion package? Is it publicly available and accessible to everyone, or is it bundled? Honestly, I'm not sure what the policy is here, but anything exposed via wp.packageName.API must maintain backward compatibility.

I think it's a good start, and we can always polish the internals, but it would be nice to address these user-facing items sooner rather than later.

cc @jasmussen, since he has better sense when it comes to media blocks.

P.S. I've noticed a flaky e2e test, which led me to this PR - #79734.

[adamsilverstein]

Thanks for the feedback @Mamaduka!

I understand that using videos instead of GIFs is better for performance, but it's still confusing to have the conversion done automatically.

I can see how it could be a little confusing the first time used, however since the front end experience is the same or better, it should still make sense.

Related notes:

Great points about the toolbar changes, curious for the design feedback.

I feel Icons alone could work here along with their tooltip text. We can make @wordpress/video-conversion private for now so we can change it more easily, we may want to reuse it elsewhere.

P.S. I've noticed a flaky e2e test, which led me to this PR

I'll see what I can do to make this more reliable.

[Mamaduka]

Thanks for opening the issue, @adamsilverstein!

I'll see what I can do to make this more reliable.

The flaky test should be fixed now (#79758). The same bug also led me to another fix - #79783.

[jasmussen]

Hey, thanks for the ping. Back from summer AFK. I took a quick look at trunk and did not see any automatic GIF conversion. Then again I have a "fine-tune" tab next in line, perhaps the context will reveal itself as I catch up.

In short: the theoretical benefit of automatic conversion is that it's slightly more accessible, and uses less UI. The downside is: it's pretty presumptuous on behalf of the users intent to do this, and therefore probably not something we should do without asking first.