MSC2705: Animated thumbnails for media

proposals/2705-thumbnail-requirements.md

@@ -0,0 +1,52 @@
+# 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.