Media: prompt to convert animated GIF uploads to video

[adamsilverstein]

What?

Closes #80136.

Adds the upload-time prompt for animated GIFs proposed by @jasmussen in #79787: uploading an animated GIF asks whether to convert it to a video (the Video block's GIF variation) or keep it as a GIF. Converting is the steered default.

Stacked on #80072 (opt-in block transforms); only the last commits are new.

Why?

#80072 made the conversion opt-in via the block switcher, but the block switcher is a discovery-dependent surface. The prompt from the issue discussion makes the choice explicit at the moment it matters - upload time - while still leaving the author in control:

• No conversion work happens (and no companion video is stored) unless the author asks for it.
• Converting is presented as the primary, focused action to steer users to the better default, per the issue discussion.

The prompt appears for every animated GIF upload. An earlier iteration added a "Remember my choice" checkbox and a Preferences → Media setting; per the discussion below that was removed - a per-upload conversion is a genuine choice rather than a nag to silence, and a remembered preference (if it turns out users want it) is better revisited separately once the direction for a general drag-and-drop prompt is settled.

The prompt is opened by an explicit action, not by the editor observing the upload pipeline. This addresses @andrewserong's review point and is built as a small, reusable primitive so a future general upload/drag-and-drop prompt can adopt it:

• @wordpress/upload-media gains a generic uploadPrompts store slice with private requestUploadPrompt( { type, itemId, data } ) / resolveUploadPrompt( id ) actions and a getUploadPrompts() selector. The flow that needs an answer requests a typed prompt; the record is deliberately decoupled from any specific upload lifecycle. GIF conversion is its first consumer.
• @wordpress/editor renders prompts through a generic UploadPromptHost that maps each prompt's type to a component (only 'gif-conversion' today). Adding a new prompt later = register a type + component and call requestUploadPrompt().

Flow, end to end:

• @wordpress/upload-media: the gifConvert setting accepts a new 'prompt' value. In prompt mode, as soon as a drop passes the animated/opacity checks (both read only the local file bytes), prepareItem records a pending GifConversion lifecycle record and dispatches requestUploadPrompt( { type: 'gif-conversion', itemId } ) — so the modal opens immediately while the GIF uploads as a plain image in the background (the upload is never blocked). resolveGifConversion( itemId, 'video' | 'gif' ) then discards the record or enqueues the exact same TranscodeGif companion sideload the automatic mode uses (mid-upload answers ride the running upload; post-upload answers use a bare finalize parent). true/false behavior is unchanged for other consumers.
• @wordpress/editor: UploadPromptHost renders a transient, single-GIF GifConversionPrompt modal while its prompt is pending; on answer it resolves the conversion and dismisses the prompt. A separate, always-mounted GifConversionBlockSwapper owns the completion side effect — once the companion video is recorded it swaps matching Image blocks via the regular Image → Video transform from GIF to video conversion: make it opt-in. Switching via block transforms #80072 (switchToBlockType + its canInsertBlockType guard). The swap is deliberately separate from the prompt because the transcode finishes after the modal has closed. The upload progress snackbar is suppressed while any prompt is open (useHasActiveUploadPrompt).

Declining ("Not now") skips the transcode entirely rather than hiding its result, so no CPU or storage is spent on a declined conversion. Consequence: such an image won't offer the block-switcher Video transform (it's gated on the companion existing) - converting later means re-uploading. An on-demand transcode from the switcher could be a follow-up.

Testing Instructions

1. Enable client-side media processing (Gutenberg → Experiments) in a cross-origin-isolated environment.
2. Upload an animated GIF into an Image block. The upload proceeds immediately and a "Convert to video" dialog appears, with Convert focused.
3. Press Enter (or click Convert): the block becomes the Video block's GIF variation once the transcode finishes.
4. Undo (Cmd+Z) to go back to the Image block - and note the block switcher still offers the Video transform (the companion is kept).
5. Upload another GIF and choose Not now: the block stays an Image block and no companion video is created (check the attachment's media_details has no animated_video).
6. Transparent or non-animated GIFs never prompt.

npm run test:e2e -- test/e2e/specs/editor/various/gif-to-video.spec.js
npm run test:unit -- packages/upload-media

Screenshots or screencast

The prompt after uploading an animated GIF (the upload itself already completed - it is never blocked by the dialog):

[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: swissspidy <swissspidy@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>

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

[jasmussen]

Here's what I see:

This is really fast and nice work. I'm impressed. Overnight delivery.

This can work, however I'll be honest it wasn't what I was thinking of—apologies I should've been clearer. In this implementation, the GIF is uploaded and inserted, and then after a second, the modal appears giving you a choice of conversion. The "remember" is a nice choice, though important if we add such a thing we'll want to also give you a section of settings to let you under a "remember" choice.

What I was picturing was that as soon as you drop an item, it prompts you, immediately, before anything happens. Before the GIF is uploaded, before anything at all is inserted into the document. And I was thinking the smallest possible modal. It has to feel super ephemeral, like part of the fluid action of dragging an image into the editor.

I guess the tricky thing here is that we can't necessarily know that a GIF is animated by looking only at the filetype we read on-drop, that maybe we have to look at the bytes to truly know. However if it allows us to fire the modal before upload, I still think it might be the right thing to do: I doubt very many people use GIF as a format for anything not animated in this day and age, so it feels safe to assume. So if it becomes a problem, I'd rather handle the "it was not animated" edge-case post-upload.

My hope with this feedback is that the implementation could possibly be simple and basic. On-drop: if GIF → fire modal.

What do you think?

[adamsilverstein]

I guess the tricky thing here is that we can't necessarily know that a GIF is animated by looking only at the filetype we read on-drop, that maybe we have to look at the bytes to truly know. However if it allows us to fire the modal before upload, I still think it might be the right thing to do: I doubt very many people use GIF as a format for anything not animated in this day and age, so it feels safe to assume. So if it becomes a problem, I'd rather handle the "it was not animated" edge-case post-upload.

Another challenge is transparency: we don't know if the GIF has transparency until we at least partially process it - and video conversion is only offered if there is no transparency detected since video can't represent transparency well.

So I think we will need to at least process the gif a bit to know whether we can convert it to a video. I already avoid doing the video transcode if the user selects no or hits escape.

That said, I think we could do what you suggest and show the modal before doing the upload - although since the GIF always gets uploaded even if you convert to video so I'm not sure why waiting to upload makes sense here. I think what you are really after is a more of a different feeling...

feel super ephemeral, like part of the fluid action of dragging an image into the editor.

so maybe instead of

the GIF is uploaded and inserted, and then after a second, the modal appears giving you a choice of conversion.

we try this:

As soon as the gif is dropped we determine if it is a conversion candidate, showing the modal immediately if so while the upload continues in the background. maybe avoid showing the upload progress snackbar in this case since its distracting.

The "remember" is a nice choice, though important if we add such a thing we'll want to also give you a section of settings to let you under a "remember" choice

to me this feels important, as a hypothetical user who regularly uploads GIFs, I want WordPress to remember my conversion preference. I can add a settings under Preferences->Media.

[adamsilverstein]

Implemented as discussed:

• The prompt now fires immediately on drop. The animated + transparency checks only need the local file bytes, so the conversion candidate is recorded before the upload starts and the modal opens as part of the drop action - no more waiting for the upload to finish. The upload continues in the background either way; answering "Convert to video" while it's still running simply attaches the transcode to the in-flight upload.
• The upload progress snackbar is suppressed while the prompt is open, so the prompt is the single point of attention (it reappears if uploads are still running once you answer).
• Smaller modal: switched to the small size and dropped the lead-in sentence - since the prompt appears as you drop, "the GIF you uploaded is animated" no longer added anything.

The Preferences → Media setting for the remembered choice was already in place from the first round.

[github-actions]

Size Change: +1.94 kB (+0.03%)

Total Size: 7.72 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	422 kB	+13 B (0%)
build/scripts/edit-post/index.min.js	52.1 kB	+52 B (+0.1%)
build/scripts/edit-site/index.min.js	303 kB	+75 B (+0.02%)
build/scripts/editor/index.min.js	497 kB	+969 B (+0.2%)
build/scripts/upload-media/index.min.js	16 kB	+830 B (+5.46%)	🔍

_{compressed-size-action}

[github-actions]

Flaky tests detected in 3709fd2.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29437238650
📝 Reported issues:

• [Flaky Test] should insert media, convert to blocks, and undo in one step #36123 in /test/e2e/specs/editor/blocks/classic.spec.js

[andrewserong]

Conceptually I like the idea of showing a modal to confirm what the user intends to do when they go to upload a media item (in this case gifs). A few thoughts on the approach code-wise:

• In other discussions it was brought up the idea that we might eventually have a general purpose modal that shows up for lots of different upload / drag and drop cases. So, how might we structure this for the idea that there could be many different kinds of prompts, not just a GifConversionPrompt?
• Currently this this code subscribes to some stuff to determine whether or not to show the modal. This might be unnecessary most of the time as we only need to open the modal in response to something that's happening based on a user interaction (in this case uploading a file). So an option might be to trigger the modal to open via an action — I'm wondering if that could simplify things a little? The potential downside is figuring out the right shape of how we want to open the modal.
• The above question leads me to: should we consider what a general upload / drag and drop prompt might look like, and what the shape of data it needs might be?
• Also, if we use an imperative action to open a prompt, I'm wondering if that'll bypass the need to have gifConversions in state?

These are just observations from having a quick look over the code, by the way — so consider them thoughts rather than a review. I think my main hesitation over this PR is just that it's making lots of decisions quite quickly for this particular feature (nice work there), but I'd really like us to also consider how we'll eventually move toward some of the ideas @jasmussen raised about other kinds of drag-and-drop modal prompts.

We don't need to solve it all just yet — but getting a sense of how we might step in that direction, and what the mechanism is for triggering the prompt, might help here.

[jasmussen]

In other discussions it was brought up the idea that we might eventually have a general purpose modal that shows up for lots of different upload / drag and drop cases. So, how might we structure this for the idea that there could be many different kinds of prompts, not just a GifConversionPrompt?

Very good question to ask. This needs a little design work, for me coming to mind, keep it concise, and make the buttons really big, multiline buttons. I feel like @fcoveram might have instincts since he has worked closely with the media work overall.

One thing stands out though: such a dialog cannot be dismissed with a checkbox. It should always be there. Or, probably at least.

I do wonder if this is one of those cases where we should land this PR without the "remember my choice" options: extract those options to a separate PR, and come back to them only if feedback tells us users really want it?

[adamsilverstein]

On a side note, I am working on showing video conversion progress (since it can take some time for larger GIFs) in #80325 and would appreciate some design feedback about how/where to show progress. Since we know the conversion progress exactly I'm thinking we can do better than the current long running spinner for conversions.

I do wonder if this is one of those cases where we should land this PR without the "remember my choice" options: extract those options to a separate PR, and come back to them only if feedback tells us users really want it?

Good point @jasmussen - I instinctively wanted to add this for completeness, but its not really needed and complicates the PR unnecessarily. I agree we can add this later and will remove for now.

keep it concise, and make the buttons really big, multiline buttons

   OK   

[adamsilverstein]

Removed "Remember my choice" in 3709fd2 as discussed with @jasmussen: the checkbox, the Preferences → Media "Animated GIF uploads" setting, and the whole core/media animatedGifUploads preference are gone. The prompt now simply appears for every animated GIF upload, and gifConvert is always 'prompt' when client-side media is on. Smaller diff, and it matches @jasmussen's point that a per-upload conversion is a real choice, not something to permanently dismiss with a checkbox. Updated the description accordingly.

@andrewserong thanks for the architectural read - a few honest thoughts:

• General-purpose prompt: fully agree this is the right direction, and @jasmussen + @fcoveram flagged it needs some design work (concise, big multiline buttons, always-present). I'd suggest we land this as the concrete first case and do the generalization as a follow-up once that design settles.
• Imperative trigger vs. subscription: I like the instinct, and I think the modal-opening concern can absolutely become an imperative "open prompt X" action in a general design. Worth separating that from the next point though.
• Bypassing gifConversions in state: That state isn't only gating the modal - it's the coordination record for an async lifecycle: created on drop (in upload-media, block-editor layer), it has to survive the upload completing, carry the answer so the "convert" case can attach the companion sideload to the right in-flight or finished upload item, and then persist until the transcode records the companion so the editor (a higher layer) can swap the blocks. An imperative open-action could sit on top of that, but I don't think the tracking state itself can go away without losing the cross-layer coordination.

So: I'd love to keep this focused, and treat the general drag-and-drop prompt (imperative trigger + shared data shape) as the next step with design input. Does that split sound reasonable?

[swissspidy]

Unrelated change?

[adamsilverstein]

@swissspidy good catch on the workflow file - that was an accidental lint-staged formatter reflow, unrelated to this PR. Reverted to trunk in 459a84b.

[adamsilverstein]

In other discussions it was brought up the idea that we might eventually have a general purpose modal that shows up for lots of different upload / drag and drop cases. So, how might we structure this for the idea that there could be many different kinds of prompts, not just a GifConversionPrompt?

I've started to break this out separately so we can discuss the architecture/design.

[adamsilverstein]

@andrewserong I took your "trigger the modal via an action" point and built it out, as a small reusable primitive rather than gif-specific glue so a future general drag-and-drop prompt can adopt it directly. Pushed as a few commits on top.

What changed

• New generic uploadPrompts primitive in @wordpress/upload-media — private requestUploadPrompt( { type, itemId, data } ) / resolveUploadPrompt( id ) actions + a getUploadPrompts() selector, backed by a small state slice. A prompt request is now a typed, first-class thing, deliberately decoupled from the gif conversion lifecycle records.
• The editor opens the modal via that action, not by observing the pipeline. A generic UploadPromptHost maps each pending prompt's type to a component (only 'gif-conversion' today). Adding a new prompt later = register a type + a component and call requestUploadPrompt().
• The old component split into two so responsibilities stay clean: a transient, single-GIF GifConversionPrompt (mounted by the host only while its prompt is pending) and an always-mounted GifConversionBlockSwapper that owns the completion side effect (swap Image→Video once the transcode finishes — which happens after the modal has closed, so it can't live in the prompt). Snackbar suppression now keys off useHasActiveUploadPrompt() instead of reaching into the gif records.

On removing gifConversions state — I kept it, and I think that's right. As I dug in, that state is doing real cross-layer coordination inside the pipeline, independent of how the modal opens: it's created on drop in upload-media, has to survive the upload completing to receive its attachmentId, carries the kept original file to the transcode, and correlates cancellations. An imperative open-action sits cleanly on top of that, but the tracking state itself can't go away without losing that coordination. So the win here is the trigger becoming explicit and the prompt concept becoming generic/reusable — not state removal.

On the multi-drop / gallery case (from a separate thread): I tried suppressing the prompt for multi-file drops in the upload store, but it's not reliably detectable there — upload paths batch inconsistently (a one-shot multi-file upload is a single batch, but the Gallery block uploads each file separately), and the authoritative "this can't become a Video block" signal lives in the editor's block context. So I've pulled that out and will do it properly as a follow-up at the editor layer (gating on canInsertBlockType( 'core/video' )). The block-switcher transform's existing guard already prevents an actual bad swap inside a gallery in the meantime.

Convert/decline flows verified green via the e2e; unit + typecheck clean. Happy to iterate on the primitive's shape.

[andrewserong]

Thanks for the updates here!

So: I'd love to keep this focused, and treat the general drag-and-drop prompt (imperative trigger + shared data shape) as the next step with design input. Does that split sound reasonable?

I haven't taken a close look at the code again just yet, but I did want to mention that I'm a little cautious about the inclusion of the modal at this stage due to the current hanging / conversion timing issue being looked at in: #80260 (comment)

Given that we're past Beta 1 and that the feature itself is still buggy, would it be worth parking adding a conversion modal for 7.1? Basically, I'm wondering if we should try to keep things as invisible to the user for 7.1, and once we're more confident in the feature, expose it a little more deliberately in 7.2?

I thought it worth asking the question now rather than spending too much time polishing something if it's not going to be included in the release. (I don't have a strong opinion here, just mindful of whatever's going to help us release things smoothly)

[adamsilverstein]

I thought it worth asking the question now rather than spending too much time polishing something if it's not going to be included in the release. (I don't have a strong opinion here, just mindful of whatever's going to help us release things smoothly)

Its fine to leave this off for now, I'd like to get more design review as well.

[fcoveram]

Apologies for chiming late here, but I need to disagree with this idea.

I don’t think this is the right path for suggesting content changes. Using a modal to recommend a block transformation interrupts the UX abruptly by forcing users to make a decision that could be intentionally triggered. In a way, it feels like infantilizing users as if they are not aware of what media file they’re adding.

I fully agree with the idea of suggesting a block transformation, but the friction should be less prominent.

I’m drawn to add a suggestion in context, by either an action in the toolbar, as part of 58418 discussion, or a dismissible Notice message in the block communicating that the file is heavy and might impact the site.

[jasmussen]

I don’t think this is the right path for suggesting content changes. Using a modal to recommend a block transformation interrupts the UX abruptly by forcing users to make a decision that could be intentionally triggered. In a way, it feels like infantilizing users as if they are not aware of what media file they’re adding.

I appreciate your careful attention to the UX. One of the sources my proposal here come from older discussion in the make/core space, slack chats, and older GitHub chats where @mtias suggested we should generally do more with providing you choice when you upload material to WordPress. This is to leverage the broad features of WordPress itself and its ability to handle many different filetypes, and notably the conversations zeroed in on MD files, which you might both want to add as files you can download, or you might want to insert their content inside a post. OR, if you drop an MD file in the Posts list, we can offer to convert it to a draft post, because WordPress knows how to handle drafts.

This is proposed less as intentional friction, and more as ambiguating between choices with the intent to be helpful. It's both a "did you know" on features you might not have been aware of, but also simply offering an upfront choice where ambiguity is present, rather than making that choice in advance.

If I read you correctly, your concern is mostly with the GIF detection: whether we should offer a conversion offer on upload or after. I agree this is a bit of a gray-area, since the choice is less: do you want to embed as a link or upload. Media you virtually always want to embed. I guess that also translates to concern about automatically converting to video. I could agree a notice in the image inspector is also a good idea to explore.

But in case your concern is with on-upload modals in general, including for other filetypes, let's connect, I think there's some nuance I would like to relay and I believe I might convince you it can be a beautiful experience.

[adamsilverstein]

Thanks for the feedback on this exploration @jasmussen and @fcoveram. Closing this out for now.