MSC4475: Media galleries by inline MXC links

proposals/4475-media-galleries-by-inline-mxc-links.md

@@ -0,0 +1,163 @@
+# MSC4475: Media galleries by inline MXC links
+
+Users need an easy way to send multiple images together with their text message
+to represent them as a gallery in a single message. The same is true for files
+and other attachment types.
+
+Currently, most Matrix clients allow sending only a single file (image) together
+with a text message, which is not sufficient in many cases. Some clients provide
+a composer UI that appears to attach multiple images, but those images are
+actually sent as separate messages.
+
+This proposal describes a convenient and flexible way to attach multiple images
+and other files into a single message using inline MXC links.
+
+## Proposal
+
+There are three different popular approaches to handle multiple media in a
+single message:
+
+1. Multiple media file above with a single caption text below: WhatsApp,
+   Telegram.
+2. Message text above with multiple media attachments below: Slack.
+3. Message text with inline media: Microsoft Teams, Skype.
+
+Pros and cons of these approaches are described in the section "Alternatives".
+
+This proposal describes approach 3, which covers approaches 1 and 2.
+
+The Matrix protocol already allows inline links to Matrix media files using MXC
+URIs; here is an example:
+```html
+Check out my photos from FOSDEM 2025:
+<img src="mxc://example.org/JWEIFJweifjWIeifj" />
+<img src="mxc://example.org/JWEIFJweifjWIeifk" />
+<img src="mxc://example.org/JWEIFJweifjWIeifl" />
+
+And especially look at this awesome group photo:
+<img src="mxc://example.org/JWEIFJweifjWIeifm" />
+
+What a nice day at FOSDEM 2025!
+```
+
+This is sufficient to implement message galleries, so we don't need any
+server-side changes to use this approach.
+
+### Client-side rendering
+
+Matrix clients should consider messages with images that reference Matrix media
+via MXC URIs as messages containing an inline gallery.
+
+To display the media in the timeline, clients should use media thumbnails from
+the Media API and present them as a grid: two per row on narrow screens (for
+example, mobile), with more columns on wider timelines.
+
+By the click on the media, clients should show a listable gallery of full-sized
+images / videos from the current message. Optionally, they can also allow
+listing images from other messages too.
+
+#### Text-only rendering
+
+Text-only clients should render the message with plaintext links in the square
+brackets displaying the alt text of the link, falling back to the media filename
+(Content-Disposition value), and the media url as the last resort.
+
+#### Fallback for clients without support
+
+Clients, that do not support this feature, will render the message as just a
+text with MXC links to media fiels, that is a sufficient for the fallback.
+
+### Client-side composing
+
+In the message composer, clients should allow inserting files (images, videos,
+other files) inline within the message text in the current cursor position.
+
+Files can be pasted by a file chooser, from the clipboard, inserted by drag and
+drop.
+
+GUI clients can render these inline as thumbnails directly in the message
+composer.
+
+Plaintext-based composers can use a textual representation of the MXC link, like GitLab and Github composers do.
+
+### Server-side link tracking
+
+It is useful to explicitly track the media links referenced in a message,
+especially for encrypted messages where the server cannot inspect message
+content to discover links.
+
+This could be implemented via an additional array of links in the message
+object, but we'll keep that out of scope and describe it in a separate MSC.
+
+## Potential issues
+
+None identified.
+
+## Alternatives
+
+When a user wants to attach an image to the message, there are usually two
+intentions:
+
+**Intention 1**: Show the image as the main message content, and, optionally,
+add some comment to the image.
+
+**Intention 2**: Show the text as the main message content, and attach an image
+to it as context.
+
+These are two different purposes for sending images, and this proposal covers
+both of them.
+
+In the result, we have three popular approaches to handle multiple media in a
+single message:
+
+1. Text below the images.
+
+Used in messengers: Slack.
+
+If we display the message text below the images, the main content of the message
+will be the images, and the "body" will be just a commenting text, in addition
+to the images.
+
+2. Text above the images.
+
+Used in messengers: WhatsApp, Telegram.
+
+If we display the message text above the images, it will be the main body of the
+message, and the attached images will provide additional context.
+
+In this mode, users sometimes want to add individual captions or comments to
+specific images in a gallery, which is not possible today.
+
+3. Text with inline images
+
+Used in messengers such as Microsoft Teams and Skype.
+
+This approach covers the previous approaches and allows placing text anywhere:
+before images, after images, or between images.
+
+It also permits grouping images into sub-galleries inside a single message.
+
+Therefore, this approach appears to be the most flexible and user-friendly.
+
+---
+
+There were already several MSCs related to the image galleries and multiple
+media attachments:
+
+- [MSC2881: Message
+  Attachments](https://github.com/matrix-org/matrix-spec-proposals/pull/2881)
+
+- [MSC3382: Inline message
+  Attachments](https://github.com/matrix-org/matrix-spec-proposals/pull/3382)
+
+- [MSC4274: Inline media galleries via
+  msgtypes](https://github.com/matrix-org/matrix-spec-proposals/pull/4274)
+
+But they cover only one type of galleries, and require changes on the server
+side.
+
+This MSC covers all gallery times and requires only changes on the client side.
+
+## Security considerations
+
+None identified.