From 40a607edeb363617f864c3253f53b8bd9934c175 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sat, 29 Nov 2025 10:04:55 -0800 Subject: [PATCH 1/6] add ratingID3 extension --- content/en/docs/Endpoints/setrating.md | 4 +++ content/en/docs/Responses/ArtistID3.md | 2 ++ .../en/docs/Responses/ArtistWithAlbumsID3.md | 2 ++ openapi/endpoints/setRating.json | 28 +++++++++++++++++++ openapi/schemas/ArtistID3.json | 6 ++++ 5 files changed, 42 insertions(+) diff --git a/content/en/docs/Endpoints/setrating.md b/content/en/docs/Endpoints/setrating.md index 98543386..e7c4fe73 100644 --- a/content/en/docs/Endpoints/setrating.md +++ b/content/en/docs/Endpoints/setrating.md @@ -11,11 +11,15 @@ description: > Sets the rating for a music file. +Servers implementing the [ratingID3 extension](../Extensions/ratingID3.md) additionally support setting ratings for ArtistID3 and AlbumID3. + ### Parameters | Parameter | Req. | OpenS. | Default | Comment | | --- | --- | --- | --- | --- | | `id` | **Yes** | | | A string which uniquely identifies the file (song) or folder (album/artist) to rate. | +| `artistId` | No | **Yes** | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `albumId` | No | **Yes** | The ID of an albumID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | | `rating` | **Yes** | | | The rating between 1 and 5 (inclusive), or 0 to remove the rating. | ### Example diff --git a/content/en/docs/Responses/ArtistID3.md b/content/en/docs/Responses/ArtistID3.md index 13dfe36d..beb42fb5 100644 --- a/content/en/docs/Responses/ArtistID3.md +++ b/content/en/docs/Responses/ArtistID3.md @@ -51,6 +51,7 @@ description: > | `musicBrainzId` | `string` | No | **Yes** | The artist MusicBrainzID. | | `sortName` | `string` | No | **Yes** | The artist sort name. | | `roles` | Array of `string` | No | **Yes** | The list of all roles this artist has in the library. | +| `userRating` | `int` | No | **Yes** | The user rating of the artist. [1-5]| {{< alert color="warning" title="OpenSubsonic" >}} New fields are added: @@ -58,6 +59,7 @@ New fields are added: - `musicBrainzId` - `sortName` - `roles` +- `userRating` **Note**: All OpenSubsonic added fields are **optionals**. But if a server support a field it **must** return it with an empty / default value when not present in it's database so that clients knows what the server supports. diff --git a/content/en/docs/Responses/ArtistWithAlbumsID3.md b/content/en/docs/Responses/ArtistWithAlbumsID3.md index 07e144eb..710d8ac1 100644 --- a/content/en/docs/Responses/ArtistWithAlbumsID3.md +++ b/content/en/docs/Responses/ArtistWithAlbumsID3.md @@ -94,6 +94,7 @@ description: > | `musicBrainzId` | `string` | No | **Yes** | The artist MusicBrainzID. | | `sortName` | `string` | No | **Yes** | The artist sort name. | | `roles` | Array of `string` | No | **Yes** | The list of all roles this artist has in the library. | +| `userRating` | `int` | No | **Yes** | The user rating of the artist. [1-5] {{< alert color="warning" title="OpenSubsonic" >}} New fields are added: @@ -101,6 +102,7 @@ New fields are added: - `musicBrainzId` - `sortName` - `roles` +- `userRating` **Note**: All OpenSubsonic added fields are **optionals**. But if a server support a field it **must** return it with an empty / default value when not present in it's database so that clients knows what the server supports. diff --git a/openapi/endpoints/setRating.json b/openapi/endpoints/setRating.json index b29cd77a..51cb4e80 100644 --- a/openapi/endpoints/setRating.json +++ b/openapi/endpoints/setRating.json @@ -16,6 +16,34 @@ "type": "string" } }, + { + "name": "artistId", + "in": "query", + "description": "A string which uniquely identifies the artistID3 to rate. Supported by servers implementing the ratingID3 extension.", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true + }, + { + "name": "albumId", + "in": "query", + "description": "A string which uniquely identifies the albumID3 to rate. Supported by servers implementing the ratingID3 extension.", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": true + }, { "name": "rating", "in": "query", diff --git a/openapi/schemas/ArtistID3.json b/openapi/schemas/ArtistID3.json index df18a693..2f60617e 100644 --- a/openapi/schemas/ArtistID3.json +++ b/openapi/schemas/ArtistID3.json @@ -41,6 +41,12 @@ "type": "string" }, "description": "The list of all roles this artist has in the library." + }, + "userRating": { + "type": "integer", + "minimum": 1, + "maximum": 5, + "description": "The user rating for this artist (0-5)." } }, "required": [ From 93eb6662def3486c5bee12d05d5ba4c4761ef8a1 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sat, 29 Nov 2025 10:09:09 -0800 Subject: [PATCH 2/6] add new extension file, fix trailing space --- content/en/docs/Endpoints/setrating.md | 2 +- content/en/docs/Extensions/ratingID3.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/Extensions/ratingID3.md diff --git a/content/en/docs/Endpoints/setrating.md b/content/en/docs/Endpoints/setrating.md index e7c4fe73..279b2509 100644 --- a/content/en/docs/Endpoints/setrating.md +++ b/content/en/docs/Endpoints/setrating.md @@ -18,7 +18,7 @@ Servers implementing the [ratingID3 extension](../Extensions/ratingID3.md) addit | Parameter | Req. | OpenS. | Default | Comment | | --- | --- | --- | --- | --- | | `id` | **Yes** | | | A string which uniquely identifies the file (song) or folder (album/artist) to rate. | -| `artistId` | No | **Yes** | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `artistId` | No | **Yes** | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | | `albumId` | No | **Yes** | The ID of an albumID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | | `rating` | **Yes** | | | The rating between 1 and 5 (inclusive), or 0 to remove the rating. | diff --git a/content/en/docs/Extensions/ratingID3.md b/content/en/docs/Extensions/ratingID3.md new file mode 100644 index 00000000..6696c26f --- /dev/null +++ b/content/en/docs/Extensions/ratingID3.md @@ -0,0 +1,20 @@ +--- +title: "Rating ID3" +linkTitle: "Rating ID3" +OpenSubsonic: +- Extension +description: > + Adds support for setting user ratings to ArtistID3 and AlbumID3 types. +--- + +**OpenSubsonic version**: [1](../../opensubsonic-versions) + +**OpenSubsonic extension name**: `ratingID3` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions)) + + +## Version 1 + +Supporting this extension means that: + +- The server supports the `userRating` field on [`AlbumID3`](../Responses/AlbumID3.md) and [`ArtistID3`](../Responses/ArtistID3.md) +- The [`setRating`](../Endpoints/setrating.md) endpoint supports the `albumId` and `artistId` parameters to apply user ratings to AlbumID3 and ArtistID3. \ No newline at end of file From 401c59510171b363e09050669c13f68023a6b12b Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sat, 29 Nov 2025 10:10:31 -0800 Subject: [PATCH 3/6] fix columns in setRating param table --- content/en/docs/Endpoints/setrating.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/Endpoints/setrating.md b/content/en/docs/Endpoints/setrating.md index 279b2509..8f9f55cd 100644 --- a/content/en/docs/Endpoints/setrating.md +++ b/content/en/docs/Endpoints/setrating.md @@ -18,8 +18,8 @@ Servers implementing the [ratingID3 extension](../Extensions/ratingID3.md) addit | Parameter | Req. | OpenS. | Default | Comment | | --- | --- | --- | --- | --- | | `id` | **Yes** | | | A string which uniquely identifies the file (song) or folder (album/artist) to rate. | -| `artistId` | No | **Yes** | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | -| `albumId` | No | **Yes** | The ID of an albumID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `artistId` | No | **Yes** | | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `albumId` | No | **Yes** | | The ID of an albumID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | | `rating` | **Yes** | | | The rating between 1 and 5 (inclusive), or 0 to remove the rating. | ### Example From 7afe6fba8be9a4b38c848c3e4cdbfb325280198b Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sat, 29 Nov 2025 10:12:25 -0800 Subject: [PATCH 4/6] add ending newline to ratingID3.md --- content/en/docs/Extensions/ratingID3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Extensions/ratingID3.md b/content/en/docs/Extensions/ratingID3.md index 6696c26f..04592138 100644 --- a/content/en/docs/Extensions/ratingID3.md +++ b/content/en/docs/Extensions/ratingID3.md @@ -17,4 +17,4 @@ description: > Supporting this extension means that: - The server supports the `userRating` field on [`AlbumID3`](../Responses/AlbumID3.md) and [`ArtistID3`](../Responses/ArtistID3.md) -- The [`setRating`](../Endpoints/setrating.md) endpoint supports the `albumId` and `artistId` parameters to apply user ratings to AlbumID3 and ArtistID3. \ No newline at end of file +- The [`setRating`](../Endpoints/setrating.md) endpoint supports the `albumId` and `artistId` parameters to apply user ratings to AlbumID3 and ArtistID3. From 7114c870f5bc21f394c80b3c1ff4602266f02efd Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sat, 29 Nov 2025 10:14:58 -0800 Subject: [PATCH 5/6] fix more linter errors --- content/en/docs/Extensions/ratingID3.md | 1 - content/en/docs/Responses/ArtistWithAlbumsID3.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/content/en/docs/Extensions/ratingID3.md b/content/en/docs/Extensions/ratingID3.md index 04592138..c172d13f 100644 --- a/content/en/docs/Extensions/ratingID3.md +++ b/content/en/docs/Extensions/ratingID3.md @@ -11,7 +11,6 @@ description: > **OpenSubsonic extension name**: `ratingID3` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions)) - ## Version 1 Supporting this extension means that: diff --git a/content/en/docs/Responses/ArtistWithAlbumsID3.md b/content/en/docs/Responses/ArtistWithAlbumsID3.md index 710d8ac1..6b4400cd 100644 --- a/content/en/docs/Responses/ArtistWithAlbumsID3.md +++ b/content/en/docs/Responses/ArtistWithAlbumsID3.md @@ -94,7 +94,7 @@ description: > | `musicBrainzId` | `string` | No | **Yes** | The artist MusicBrainzID. | | `sortName` | `string` | No | **Yes** | The artist sort name. | | `roles` | Array of `string` | No | **Yes** | The list of all roles this artist has in the library. | -| `userRating` | `int` | No | **Yes** | The user rating of the artist. [1-5] +| `userRating` | `int` | No | **Yes** | The user rating of the artist. [1-5] | {{< alert color="warning" title="OpenSubsonic" >}} New fields are added: From 0aeffc852e5a41f5adaf257b688e6c2701605c14 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Wed, 3 Dec 2025 06:54:48 -0800 Subject: [PATCH 6/6] address review comments --- content/en/docs/Endpoints/setrating.md | 8 ++++---- openapi/endpoints/setRating.json | 6 +++--- openapi/schemas/ArtistID3.json | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/Endpoints/setrating.md b/content/en/docs/Endpoints/setrating.md index 8f9f55cd..b9423bac 100644 --- a/content/en/docs/Endpoints/setrating.md +++ b/content/en/docs/Endpoints/setrating.md @@ -9,7 +9,7 @@ description: > `http://your-server/rest/setRating` Since [1.6.0](../../subsonic-versions) -Sets the rating for a music file. +Sets the rating for a music file, folder, album, or artist. Servers implementing the [ratingID3 extension](../Extensions/ratingID3.md) additionally support setting ratings for ArtistID3 and AlbumID3. @@ -17,9 +17,9 @@ Servers implementing the [ratingID3 extension](../Extensions/ratingID3.md) addit | Parameter | Req. | OpenS. | Default | Comment | | --- | --- | --- | --- | --- | -| `id` | **Yes** | | | A string which uniquely identifies the file (song) or folder (album/artist) to rate. | -| `artistId` | No | **Yes** | | The ID of an artistID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | -| `albumId` | No | **Yes** | | The ID of an albumID3 to star. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `id` | No | | | A string which uniquely identifies the file (song) or folder (album/artist) to rate. | +| `artistId` | No | **Yes** | | The ID of an artistID3 to rate. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | +| `albumId` | No | **Yes** | | The ID of an albumID3 to rate. Multiple parameters allowed. Supported by servers implementing the ratingID3 extension. | | `rating` | **Yes** | | | The rating between 1 and 5 (inclusive), or 0 to remove the rating. | ### Example diff --git a/openapi/endpoints/setRating.json b/openapi/endpoints/setRating.json index 51cb4e80..63728bb5 100644 --- a/openapi/endpoints/setRating.json +++ b/openapi/endpoints/setRating.json @@ -11,7 +11,7 @@ "name": "id", "in": "query", "description": "A string which uniquely identifies the file (song) or folder (album/artist) to rate.", - "required": true, + "required": false, "schema": { "type": "string" } @@ -20,7 +20,7 @@ "name": "artistId", "in": "query", "description": "A string which uniquely identifies the artistID3 to rate. Supported by servers implementing the ratingID3 extension.", - "required": true, + "required": false, "schema": { "type": "array", "items": { @@ -34,7 +34,7 @@ "name": "albumId", "in": "query", "description": "A string which uniquely identifies the albumID3 to rate. Supported by servers implementing the ratingID3 extension.", - "required": true, + "required": false, "schema": { "type": "array", "items": { diff --git a/openapi/schemas/ArtistID3.json b/openapi/schemas/ArtistID3.json index 2f60617e..398f2aeb 100644 --- a/openapi/schemas/ArtistID3.json +++ b/openapi/schemas/ArtistID3.json @@ -46,7 +46,7 @@ "type": "integer", "minimum": 1, "maximum": 5, - "description": "The user rating for this artist (0-5)." + "description": "The user rating for this artist (1-5)." } }, "required": [