isAnimated metadata property

[rexxars]

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.

[lovell]

Multi-page and animated images are treated as the same thing by libvips, so this logic would probably live in sharp itself and very closely represent the sample metadata.pages > 1 && ... statement you've provided. Happy to accept a PR for this.

[styfle]

This sounds useful!

I've used the is-animated package in the past for this detection but having it in sharp would be a great addition. Might be worth comparing their implementation (a cursory look at the code also indicates PNG can be animated too)

Might be better off assuming all formats with multiple pages are animated besides PDF:

const isAnimated = metadata.pages > 1 && metadata.format !== 'pdf'