From c6fdf6ff110b5b056add498ec42180db1b0d0c4d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 19 Mar 2024 14:00:27 -0600 Subject: [PATCH 1/3] Spec `?animated` on `/thumbnail` --- .../client_server/newsfragments/1757.feature | 1 + data/api/client-server/content-repo.yaml | 42 ++++++++++++++++++- 2 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1757.feature diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature new file mode 100644 index 000000000..f7f020929 --- /dev/null +++ b/changelogs/client_server/newsfragments/1757.feature @@ -0,0 +1 @@ +Add optional `animated` query string option to `GET /_matrix/media/v2/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index c8800279a..bfdda6bb8 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -633,6 +633,28 @@ paths: schema: type: boolean default: false + - in: query + name: animated + x-addedInMatrixVersion: "1.10" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server should behave as though `animated` is `false`. + example: false + schema: + type: boolean responses: "200": description: A thumbnail of the requested content. @@ -644,6 +666,9 @@ paths: enum: - image/jpeg - image/png + - image/apng + - image/gif + - image/webp content: image/jpeg: schema: @@ -651,7 +676,22 @@ paths: description: "**Required.** The bytes for the thumbnail." image/png: schema: - description: "**Required.** The bytes for the thumbnail." + x-changedInMatrixVersion: "1.10" + description: | + **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated + format if `animated=true`. + image/apng: + schema: + x-addedInMatrixVersion: "1.10" + description: "**Required.** The bytes for the *animated* thumbnail." + image/gif: + schema: + x-addedInMatrixVersion: "1.10" + description: "**Required.** The bytes for the *animated* thumbnail." + image/webp: + schema: + x-addedInMatrixVersion: "1.10" + description: "**Required.** The bytes for the *animated* thumbnail." "307": description: A redirect to the thumbnail of the requested content. headers: From 955b52670abf2b393529a98b2a222660f7e25589 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 19 Mar 2024 14:03:12 -0600 Subject: [PATCH 2/3] v3* --- changelogs/client_server/newsfragments/1757.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature index f7f020929..3471c1b96 100644 --- a/changelogs/client_server/newsfragments/1757.feature +++ b/changelogs/client_server/newsfragments/1757.feature @@ -1 +1 @@ -Add optional `animated` query string option to `GET /_matrix/media/v2/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file +Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file From 5773a79efe1f840a01f1e428d3ad62dcd0dbaae1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 Mar 2024 13:15:51 -0600 Subject: [PATCH 3/3] v1.11 --- data/api/client-server/content-repo.yaml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index bfdda6bb8..f69138749 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -635,7 +635,7 @@ paths: default: false - in: query name: animated - x-addedInMatrixVersion: "1.10" + x-addedInMatrixVersion: "1.11" required: false description: | Indicates preference for an animated thumbnail from the server, if possible. Animated @@ -676,21 +676,22 @@ paths: description: "**Required.** The bytes for the thumbnail." image/png: schema: - x-changedInMatrixVersion: "1.10" + x-changedInMatrixVersion: + "1.11": The PNG may be of the APNG variety if animation is supported and requested. description: | **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated format if `animated=true`. image/apng: schema: - x-addedInMatrixVersion: "1.10" + x-addedInMatrixVersion: "1.11" description: "**Required.** The bytes for the *animated* thumbnail." image/gif: schema: - x-addedInMatrixVersion: "1.10" + x-addedInMatrixVersion: "1.11" description: "**Required.** The bytes for the *animated* thumbnail." image/webp: schema: - x-addedInMatrixVersion: "1.10" + x-addedInMatrixVersion: "1.11" description: "**Required.** The bytes for the *animated* thumbnail." "307": description: A redirect to the thumbnail of the requested content.