From 4b6e1abc0881dfaa58a40a5fc44df543f8d3d6f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sun, 25 Feb 2024 13:08:25 +0100 Subject: [PATCH 1/4] Use `body` field as media caption MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2530. Signed-off-by: Kévin Commaille --- .../modules/instant_messaging.md | 60 +++++++++++++++++-- .../schema/m.room.message$m.audio.yaml | 23 ++++++- .../schema/m.room.message$m.file.yaml | 19 +++++- .../schema/m.room.message$m.image.yaml | 23 ++++++- .../schema/m.room.message$m.video.yaml | 23 ++++++- 5 files changed, 140 insertions(+), 8 deletions(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 5fcf379f6..b0ba26f9c 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -19,6 +19,8 @@ room itself such as a room name and topic. ##### m.room.message msgtypes +{{% changed-in v="1.10" %}} + Each [m.room.message](#mroommessage) MUST have a `msgtype` key which identifies the type of message being sent. Each type has their own required and optional keys, as outlined below. If a client cannot display the given @@ -27,10 +29,17 @@ instead. Some message types support HTML in the event content that clients should prefer to display if available. Currently `m.text`, `m.emote`, `m.notice`, -and `m.key.verification.request` support an additional `format` parameter of -`org.matrix.custom.html`. When this field is present, a `formatted_body` -with the HTML must be provided. The plain text version of the HTML -should be provided in the `body`. +`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request` +support an additional `format` parameter of `org.matrix.custom.html`. When this +field is present, a `formatted_body` with the HTML must be provided. The plain +text version of the HTML should be provided in the `body`. + +{{% boxes/note %}} +Until v1.10 of the spec, the `format` and `formatted` fields were limited to +`m.text`, `m.emote`, `m.notice`, and `m.key.verification.request`. As of v1.10 +this list is now expanded to include `m.image`, `m.file`, `m.audio` and +`m.video` for [media captions](#media-captions). +{{% /boxes/note %}} Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML @@ -320,6 +329,49 @@ to the media repository, then reference the `mxc://` URI in a markdown-style lin Clients SHOULD render spoilers differently with some sort of disclosure. For example, the client could blur the actual text and ask the user to click on it for it to be revealed. +##### Media captions + +{{% added-in v="1.10" %}} + +Media messages, comprised of `m.image`, `m.file`, `m.audio` and `m.video`, can +include a caption to convey additional information about the media. + +To send captions, clients MUST use the `filename` and the `body`, and optionally +the `formatted_body` with the `org.matrix.custom.html` format, described above. + +If the `filename` is present, and its value is different than `body`, then +`body` is considered to be a caption, otherwise `body` is a filename. `format` +and `formatted_body` are only used for captions. + +{{% boxes/note %}} +In previous versions of the specification, `body` was usually used to set the +filename of the uploaded file, and `filename` was only present on `m.file` with +the same purpose. +{{% /boxes/note %}} + +An example of a media message with a caption is: + +```json +{ + "msgtype": "m.image", + "url": "mxc://example.org/abc123", + "filename": "dog.jpg", + "body": "this is a ~~cat~~ picture :3", + "format": "org.matrix.custom.html", + "formatted_body": "this is a cat picture :3", + "info": { + "w": 479, + "h": 640, + "mimetype": "image/jpeg", + "size": 27253 + }, + "m.mentions": {} +} +``` + +Clients MUST render the caption alongside the media and SHOULD prefer its +formatted representation. + #### Server behaviour Homeservers SHOULD reject `m.room.message` events which don't have a diff --git a/data/event-schemas/schema/m.room.message$m.audio.yaml b/data/event-schemas/schema/m.room.message$m.audio.yaml index 6cf742e47..825419bdf 100644 --- a/data/event-schemas/schema/m.room.message$m.audio.yaml +++ b/data/event-schemas/schema/m.room.message$m.audio.yaml @@ -6,8 +6,29 @@ properties: content: properties: body: - description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'." + description: |- + If `filename` is not set or the value of both properties are + identical, this is the filename of the original upload. Otherwise, + this is a caption for the audio. + type: string + x-changedInMatrixVersion: + "1.10": This property can act as a caption for the audio. + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + x-addedInMatrixVersion: "1.10" + formatted_body: + description: |- + The formatted version of the `body`, when it acts as a caption. This + is required if `format` is specified. + type: string + x-addedInMatrixVersion: "1.10" + filename: + description: The original filename of the uploaded file. type: string + x-addedInMatrixVersion: "1.10" info: description: Metadata for the audio clip referred to in `url`. properties: diff --git a/data/event-schemas/schema/m.room.message$m.file.yaml b/data/event-schemas/schema/m.room.message$m.file.yaml index af1819647..8e2693660 100644 --- a/data/event-schemas/schema/m.room.message$m.file.yaml +++ b/data/event-schemas/schema/m.room.message$m.file.yaml @@ -6,8 +6,25 @@ properties: content: properties: body: - description: A human-readable description of the file. This is recommended to be the filename of the original upload. + description: |- + If `filename` is not set or the value of both properties are + identical, this is the filename of the original upload. Otherwise, + this is a caption for the file. + type: string + x-changedInMatrixVersion: + "1.10": This property can act as a caption for the file. + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + x-addedInMatrixVersion: "1.10" + formatted_body: + description: |- + The formatted version of the `body`, when it acts as a caption. This + is required if `format` is specified. type: string + x-addedInMatrixVersion: "1.10" filename: description: The original filename of the uploaded file. type: string diff --git a/data/event-schemas/schema/m.room.message$m.image.yaml b/data/event-schemas/schema/m.room.message$m.image.yaml index 91985ed06..15bdeda4f 100644 --- a/data/event-schemas/schema/m.room.message$m.image.yaml +++ b/data/event-schemas/schema/m.room.message$m.image.yaml @@ -6,8 +6,29 @@ properties: content: properties: body: - description: "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'." + description: |- + If `filename` is not set or the value of both properties are + identical, this is the filename of the original upload. Otherwise, + this is a caption for the image. + type: string + x-changedInMatrixVersion: + "1.10": This property can act as a caption for the image. + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + x-addedInMatrixVersion: "1.10" + formatted_body: + description: |- + The formatted version of the `body`, when it acts as a caption. This + is required if `format` is specified. + type: string + x-addedInMatrixVersion: "1.10" + filename: + description: The original filename of the uploaded file. type: string + x-addedInMatrixVersion: "1.10" info: allOf: - $ref: core-event-schema/msgtype_infos/image_info.yaml diff --git a/data/event-schemas/schema/m.room.message$m.video.yaml b/data/event-schemas/schema/m.room.message$m.video.yaml index e3b782b83..757525340 100644 --- a/data/event-schemas/schema/m.room.message$m.video.yaml +++ b/data/event-schemas/schema/m.room.message$m.video.yaml @@ -6,8 +6,29 @@ properties: content: properties: body: - description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'." + description: |- + If `filename` is not set or the value of both properties are + identical, this is the filename of the original upload. Otherwise, + this is a caption for the video. + type: string + x-changedInMatrixVersion: + "1.10": This property can act as a caption for the video. + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + x-addedInMatrixVersion: "1.10" + formatted_body: + description: |- + The formatted version of the `body`, when it acts as a caption. This + is required if `format` is specified. + type: string + x-addedInMatrixVersion: "1.10" + filename: + description: The original filename of the uploaded file. type: string + x-addedInMatrixVersion: "1.10" info: description: Metadata about the video clip referred to in `url`. properties: From b79a5b94f8828d590e645d95b7bba2a5ff79f803 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sun, 25 Feb 2024 13:12:21 +0100 Subject: [PATCH 2/4] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1731.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1731.feature diff --git a/changelogs/client_server/newsfragments/1731.feature b/changelogs/client_server/newsfragments/1731.feature new file mode 100644 index 000000000..f4561bf3c --- /dev/null +++ b/changelogs/client_server/newsfragments/1731.feature @@ -0,0 +1 @@ +Use the `body` field as media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). \ No newline at end of file From 46c87636146dadc887a975883050485114a33567 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 26 Feb 2024 15:31:39 +0100 Subject: [PATCH 3/4] Use `s` HTML tag in example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- content/client-server-api/modules/instant_messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index b0ba26f9c..e2c6f92be 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -358,7 +358,7 @@ An example of a media message with a caption is: "filename": "dog.jpg", "body": "this is a ~~cat~~ picture :3", "format": "org.matrix.custom.html", - "formatted_body": "this is a cat picture :3", + "formatted_body": "this is a cat picture :3", "info": { "w": 479, "h": 640, From 5fb91e9907535b560824e24bb9a80eaf7c92c99f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 26 Feb 2024 15:36:27 +0100 Subject: [PATCH 4/4] Move changed-in annotation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../client-server-api/modules/instant_messaging.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index e2c6f92be..1fda62f4b 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -19,8 +19,6 @@ room itself such as a room name and topic. ##### m.room.message msgtypes -{{% changed-in v="1.10" %}} - Each [m.room.message](#mroommessage) MUST have a `msgtype` key which identifies the type of message being sent. Each type has their own required and optional keys, as outlined below. If a client cannot display the given @@ -35,10 +33,11 @@ field is present, a `formatted_body` with the HTML must be provided. The plain text version of the HTML should be provided in the `body`. {{% boxes/note %}} -Until v1.10 of the spec, the `format` and `formatted` fields were limited to -`m.text`, `m.emote`, `m.notice`, and `m.key.verification.request`. As of v1.10 -this list is now expanded to include `m.image`, `m.file`, `m.audio` and -`m.video` for [media captions](#media-captions). +{{% changed-in v="1.10" %}} +In previous versions of the specification, the `format` and `formatted` fields +were limited to `m.text`, `m.emote`, `m.notice`, and +`m.key.verification.request`. This list is expanded to include `m.image`, +`m.file`, `m.audio` and `m.video` for [media captions](#media-captions). {{% /boxes/note %}} Clients should limit the HTML they render to avoid Cross-Site Scripting,