From f4428bb7404b1b4192f1833f9bb6032c3044dcf9 Mon Sep 17 00:00:00 2001 From: Alexey Murz Korepov Date: Tue, 19 May 2026 12:19:40 +0400 Subject: [PATCH 1/2] MSC4475: Media galleries by inline MXC links --- ...475-media-galleries-by-inline-mxc-links.md | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 proposals/4475-media-galleries-by-inline-mxc-links.md diff --git a/proposals/4475-media-galleries-by-inline-mxc-links.md b/proposals/4475-media-galleries-by-inline-mxc-links.md new file mode 100644 index 00000000000..2dd0700c6de --- /dev/null +++ b/proposals/4475-media-galleries-by-inline-mxc-links.md @@ -0,0 +1,132 @@ +# 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: + + + + +And especially look at this awesome group photo: + + +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 images in the timeline, clients should use thumbnail-sized +images and present them as a grid: two per row on narrow screens (for example, +mobile), with more columns on wider timelines. + +### Client-side composing + +In the message composer, clients should allow inserting images inline within the +message text. GUI clients can render these inline as thumbnails; text-based +clients can use a textual representation of the MXC link. + +### 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: + +- https://github.com/matrix-org/matrix-spec-proposals/pull/2881 +- https://github.com/matrix-org/matrix-spec-proposals/pull/3382 +- https://github.com/matrix-org/matrix-spec-proposals/pull/4274 + + +## Security considerations + +None identified. From 3a42554c3eca20a1774e8c695904c7caca2db99f Mon Sep 17 00:00:00 2001 From: Alexey Murz Korepov Date: Tue, 19 May 2026 18:34:19 +0400 Subject: [PATCH 2/2] Add more details for plaintext fallbacks --- ...475-media-galleries-by-inline-mxc-links.md | 65 ++++++++++++++----- 1 file changed, 48 insertions(+), 17 deletions(-) diff --git a/proposals/4475-media-galleries-by-inline-mxc-links.md b/proposals/4475-media-galleries-by-inline-mxc-links.md index 2dd0700c6de..b97c9380775 100644 --- a/proposals/4475-media-galleries-by-inline-mxc-links.md +++ b/proposals/4475-media-galleries-by-inline-mxc-links.md @@ -4,13 +4,13 @@ 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. +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. +This proposal describes a convenient and flexible way to attach multiple images +and other files into a single message using inline MXC links. ## Proposal @@ -48,15 +48,37 @@ server-side changes to use this approach. Matrix clients should consider messages with images that reference Matrix media via MXC URIs as messages containing an inline gallery. -To display the images in the timeline, clients should use thumbnail-sized -images and present them as a grid: two per row on narrow screens (for example, -mobile), with more columns on wider timelines. +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 images inline within the -message text. GUI clients can render these inline as thumbnails; text-based -clients can use a textual representation of the MXC link. +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 @@ -100,8 +122,8 @@ to 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. +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. @@ -122,10 +144,19 @@ 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: -- https://github.com/matrix-org/matrix-spec-proposals/pull/2881 -- https://github.com/matrix-org/matrix-spec-proposals/pull/3382 -- https://github.com/matrix-org/matrix-spec-proposals/pull/4274 +- [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