Request for (better) documentation about WebP animation support

[GwynethLlewelyn]

Hi there!

This fantastic plugin of yours also works really well with animated WebP images and complies to specs, at least as far as I can tell; all Chromium-based viewers I tested on a Mac had zero issues with your animation support, and command-line tools (and a few online ones!) also reported no problems at all, perfectly converting a WebP animation to any other kind (GIF, APNG, etc.).

However, I'd say that you need to clarify the instructions on the README a little bit! You only say the following:

The Timeline data is not used; thus animations rely on layers for defining frames (set duration as "(123 ms)" in each layer's name), and they need to be rasterized before saving.

All right, it all makes sense after you've successfully created your first animation, but reaching that via trial and error is not obvious! In particular, there are only a few things that will make the animation "work", namely:

1. The Timeline is completely ignored (just like you say!).
2. Each frame for the animation must be in its own layer.
3. Layers should be ordered according to the sequence of animations, namely, the last layer on the list will usually be the first animation frame and so forth.
4. For better results, label each layer exactly in the same way, namely: Frame1 (100 ms). A few notes:

• Frame1 should be the bottom-most layer, and counting upwards from that, i.e. Frame2, Frame3 and so forth. Note the capitalised layer name, and the lack of space between the word Frame and its number.
• Exactly one space after that, place the desired delay setting (also known as duration) for this frame in milliseconds, e.g. (100 ms) for a 0.1s delay. Fractional parts or other units of time do not work (as far as I could test them).
• There is also one space between the number and the ms unit label, and everything should be enclosed in (rounded) parenthesis.
• No extraneous spaces, newlines or any other symbols, visible or not; also, the word Frame should not be replaced by an equivalent translation; and, when switching layers from their original location (namely, to swap frames), remember to change the numbering scheme as well (i.e., leave no layers with their frame number out of a proper sequence).
• No duplicate names, no missing frame names.
• Instead of duplicating a frame/layer — to get twice the duration! — just relabel that frame to have twice the duration, i.e. (200 ms) instead of two layers with the exact content and (100 ms) on each frame. Frames do not need to have consistent durations, or add up to a 'whole' number (say, 25 FPS or so).
• Durations of less than 100 ms weren't tested but might arguably be used; setting them to zero ('no delay' frames, as in GIF files) is usually a Bad Idea (mostly because the CPU will try to render each frame as fast as it can, leaving no free time for any other application to run until the animation is completed) and might even be ignored by the WebP libraries. Also, to the best of my knowledge, current Unix-based systems (and that includes macOS) have a CPU time slice of 10 ms, which means that the system might not be able to handle less than that anyway (not tested), at least not in CPU-bound rendering.

5. As mentioned, each frame must be fully rasterised; what that means is that each layer cannot have filters, masks, or any extra settings applied to the layer itself. Anything like that will make the WebPShop plugin refuse to recognise the sequence of layers as animation frames, and just save the currently selected frame instead.
6. Similarly, no layer grouping, no layer links, no extra layers before or after the actual frames, no global/partial settings, etc. Keep it as basic as you can, or, rather, do your processing first, and just use the finished 'raw' results, one frame per layer.
7. Re-read the limits in terms of colours and image size!
8. All frames should have the same exact dimensions on each layer (thus, avoid using artboards or similar 'tricks' to display some parts of the document in one frame but not the next).
9. Remember that if you just get one image instead of an animation, it's a sure sign that you have missed one of the steps above!

For me, the trickiest thing to figure out was the exact name of the first frame (the bottom-most layer), and the notion that "fully rasterised" meant "no special effects whatsoever". In my case, I was working with a square profile picture, which I wished to cut out using a circle mask, setting the rest to transparent. When doing GIF animations (the ones that can be saved with the built-in 'legacy' Web mode), this works wonderfully well, with just a single mask applied to all layers. In the case of WebP animations made with WebPShop, you can't even have a mask on each layer. Whatever you add as "special effects" will simply make the WebPShop plugin revert back to single-image saving instead of producing the desired animation.

That said, there is really nothing else to say about animation support: it just works :-) — so long as you stick strictly to the rules and don't 'expect' all the usual Photoshop bells & whistles that can be used for creating GIF animations.

One reasonable simple way of ensuring that everything is correctly assembled is to render a video of the finished animation first, and then import each frame as an individual layer, with the layer names correctly set to the scheme expected by WebPShop. One might argue that this could be easier using, say, command-line tools. In my personal case, however, as much as I love command-line tools, they're always tricky to use for animations with frames having a variable delay/duration. They're good (and fast!) when all frames have the exact duration; however, for animations to be used on a Web browser (desktop or mobile), that's usually not the best way ('best' meaning: most efficient, with the least memory footprint and disk space). Variable durations are very effective, when used properly; and even though the Timeline cannot be used to preview the animation, it's nevertheless easier just to change the layer names in Photoshop to reflect the desired duration rather than figuring out the precise convention of adding variable-duration frames on a command-line tool (which not all support!).

Anyway, thanks so much for making this plugin available!

[y-guyon]

Thank you for your interest in WebPShop and for the very detailed feedback!
It can be useful to others so I referenced your guidelines from the README.md. Let me know if I missed a critical advice in the new paragraph, but I would rather keep it short.

I did not test WebP native support in Photoshop for a while. Do you know if animations were added?

Setting durations to zero ('no delay' frames, as in GIF files) is usually a Bad Idea and might even be ignored by the WebP libraries

Correct, see the WebP specification:
"Note that the interpretation of the Frame Duration of 0 (and often <= 10) is defined by the implementation."

don't 'expect' all the usual Photoshop bells & whistles that can be used for creating GIF animations

I wish it was available to Format plug-ins but the Photoshop SDK API unfortunately does not expose all of that.