MSC4230: Flag for animated images

proposals/4230-animated-image-flag.md

@@ -0,0 +1,75 @@
+# MSC4230: 'Animated' flag for images
+
+Since animated images are thumbnailed to a still image, clients need to download the full
+image in order to display it animated. However, there is currently no way of telling that
+an image is animated without downloading the original image. This means that clients wishing
+to display the image as animated must download the original image for any image format which
+is capabale of being animated. This means they download the full size image for non-animated
+images even when the user never chooses to enlarge the image.
+
+Even clients that animate images on hover must pre-fetch the full size image if they want the
+animation to start without a delay while it's downloaded.
+
+## Proposal
+
+We add an optional boolean flag, `ia_animated` to the `info` object of image events indicating if
+the image is animated or not. This SHOULD match whether the original image contains animation. Note
+that this will require clients probe the image file for animation. Simpler clients may, therefore,
+choose to not send this value at all, or always set it to false, meaning receiving clients are
+likely to render the image as non-animated.
+
+Example:
+
+```json5
+{
+    "body": "partyparrot.gif",
+    "file": {
+      [...]
+    },
+    "info": {
+      "w": 640,
+      "h": 480,
+      "mimetype": "image/gif",
+      "size": 35295,
+      "is_animated": "true",
+    }
+```
+
+If this flag is `false`, receiving clients can assume that the image is not animated. If `true`, they should
+assume that it is.
+
+Behaviour when the field is omitted is left up to the client. They might choose to behave as if it is present
+and set to `true`, ensuring backwards compatibility whilst still saving bandwidth for images where the flag
+is present and set to `false`. Perhaps they might decide to change this behaviour once more clients start
+sending the flag.
+
+## Potential issues
+
+Clients may lie about the flag which would cause unexpected behaviour, for example, an image which
+was not presented might then animate when the user clicks to enlarge it, allowing for 'jump scares'
+or similar. Clients may wish to prevent images from being animated if the flag is set to false.
+
+As above, supporting animated images becomes harder for sending clients because they must work out if
+an image is animated in order to set the flag.
+
+## Alternatives
+
+We could specify that clients behave as if the flag is set to true if it's absent. This would mean
+clients that didn't want to probe images on upload could omit the flag, at the expense of receiving
+clients needing to download the original to probe for animation.
+
+We could require that servers, or clients in the case of encrypted rooms, preserve animation on
+thumbnailing. This is quite a burden for clients and would make thumbnails larger.
+
+## Security considerations
+
+Potential for clients to lie about the flag and cause unexpected animation is covered in 'Potential
+Problems'.
+
+## Unstable prefix
+
+Until stable, the flag will be `org.matrix.msc4230.is_animated`.
+
+## Dependencies
+
+None.