`isAnimated` metadata property

Feature request

What are you trying to achieve?

I need to check whether or not an image is animated (eg animated gif or webp). This may already be possible by checking something like metadata.pages > 1 && (metadata.format === 'gif' || metadata.format === 'webp'), but there may be subtleties that I am not considering, over time other formats such as avif or jxl will come along with animation support too.

Either way, it would be a nice developer experience win to have an easy accessible property for this instead of trying to infer it from the other metadata, is possible. Thoughts?

When you searched for similar feature requests, what did you find that might be related?

Can't quite find a feature request for this, specifically

What would you expect the API to look like?

const {isAnimated} = await sharp('someAnimated.gif').metadata()
console.log(isAnimated) // true

const {isAnimated} = await sharp('someSinglePage.jpg').metadata()
console.log(isAnimated) // false

What alternatives have you considered?

Manually checking the pages property and pairing with format checks, I suppose. PDFs are not animated, but does have pages - so it needs to be more than a pages check I believe?

Please provide sample image(s) that help explain this feature

Shouldn't be necessary for this one.

Start by reading the metadata() API and the existing pages and format metadata handling. Check how animated GIF and WebP images are represented, along with non-animated images and multi-page PDFs, then determine what a consistent isAnimated result should be for the formats discussed. Done means metadata() exposes the requested boolean without requiring callers to infer it.