53 lines
2.4 KiB
Markdown
53 lines
2.4 KiB
Markdown
# 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`](https://spec.matrix.org/v1.9/client-server-api/#get_matrixmediav3thumbnailservernamemediaid)
|
|
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](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-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.
|