matrix
/
matrix-doc
mirror of https://github.com/matrix-org/matrix-doc.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
matrix-doc/proposals/2705-thumbnail-requirements.md

2.4 KiB
Raw Permalink Blame History

MSC2705: Animated thumbnails

Users may already upload animated media to the media repository, such as gifs, webp images, and videos. When this media is used in an event or avatar, many clients are stuck with a static thumbnail until the user clicks on it to get the full, unedited, file. Some clients however would prefer to show an animated thumbnail in certain conditions, like when the user is hovering over the message or avatar.

This proposal introduces a new query parameter to the GET /_matrix/media/v3/thumbnail endpoint, allowing clients to specifically request an animated thumbnail.

Proposal

A new query parameter, animated, is added to the /thumbnail endpoint. It has the following behaviour:

  • When true: the server SHOULD return an animated thumbnail if possible/supported.
  • When false: the server MUST NOT return an animated thumbnail.
  • When not provided: the server SHOULD NOT return an animated thumbnail.

The default case is a relaxed version of the false behaviour to allow server owners to customize the default behaviour when their users' clients do not support requesting animated thumbnails.

Clients SHOULD respect a user's preference to reduce motion and request non-animated thumbnails in these cases.

The content types which are able to be animated is left as an implementation detail. The following SHOULD be supported at a minimum, however:

  • image/gif
  • image/png or image/apng ("APNG" format)
  • image/webp

The returned content type for an animated thumbnail is additionally left as an implementation detail, though servers SHOULD use image/webp whenever possible.

When media cannot be animated, such as a PDF or JPEG, the server should return a thumbnail as though animated was false.

Alternatives

No significant alternatives.

Security considerations

Server load could increase when the server tries to thumbnail a large file. Servers are expected to mitigate this on their own by providing an option to disable the feature or limiting how/when they will animate the media.

Unstable prefix

While this proposal is not considered stable, animated is specified as org.matrix.msc2705.animated on requests. No unstable endpoints are required due to backwards compatibility being built-in to the proposal.