Add artistRoleFilter extension

content/en/docs/Endpoints/getartists.md

@@ -1,6 +1,9 @@
 ---
 title: "getArtists"
-linkTitle: "getArtists"
+linkTitle: "getArtists [OS]"
+opensubsonic:
+- Addition
+- Extension
 categories:
 - Browsing
 description: >
@@ -16,6 +19,15 @@ Similar to [`getIndexes`](../getindexes), but organizes music according to ID3 t
 | Parameter | Req. | OpenS. | Default | Comment |
 | --- | --- | --- | --- | --- |
 | `musicFolderId` | No  |  |  | If specified, only return artists in the music folder with the given ID. See [`getMusicFolders`](../getmusicfolders). |
+| `role` | No | **Yes** |  | Repeat this parameter to filter the returned artists by one or more roles. Requires the [`Artist role filter`](../../extensions/artistRoleFilter/) extension. |
+
+{{< alert color="warning" title="OpenSubsonic" >}}
+If the server supports the [`Artist role filter`](../../extensions/artistRoleFilter/) extension, it **must** accept the `role` parameter and filter the returned artists accordingly.
+
+`role` may be repeated to request several roles, using the values found in the [`ArtistID3`](../../responses/artistid3) `roles` field (e.g. `albumartist`, `artist`, `composer`). An artist is returned if it has **any** of the requested roles. The special value `all` returns every artist regardless of role.
+
+When `role` is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected.
+{{< /alert >}}
 
 ### Example
 

content/en/docs/Endpoints/getopensubsonicextensions.md

@@ -56,6 +56,12 @@ A [`subsonic-response`](../../responses/subsonic-response) element with a nested
                 "versions": [
                     1
                 ]
+            },
+            {
+                "name": "artistRoleFilter",
+                "versions": [
+                    1
+                ]
             }
         ]
     }

content/en/docs/Endpoints/search3.md

@@ -3,6 +3,8 @@ title: "search3"
 linkTitle: "search3 [OS]"
 opensubsonic:
 - Clarification
+- Addition
+- Extension
 categories:
 - Searching
 description: >
@@ -27,9 +29,14 @@ Music is organized according to ID3 tags.
 | `songCount` | No |   | 20  | Maximum number of songs to return. |
 | `songOffset` | No |   | 0   | Search result offset for songs. Used for paging. |
 | `musicFolderId` | No |   |     | (Since [1.12.0](../../subsonic-versions)) Only return results from music folder with the given ID. See `getMusicFolders`. |
+| `artistRole` | No | **Yes** |     | Repeat this parameter to filter the returned artists by one or more roles. Requires the [`Artist role filter`](../../extensions/artistRoleFilter/) extension. |
 
 {{< alert color="warning" title="OpenSubsonic" >}}
 Servers must support an **empty query** and return all the data to allow clients to properly access all the media information for offline sync.
+
+If the server supports the [`Artist role filter`](../../extensions/artistRoleFilter/) extension, it **must** accept the `artistRole` parameter and filter the returned **artists** accordingly (albums and songs are unaffected).
+
+`artistRole` may be repeated to request several roles, using the values found in the [`ArtistID3`](../../responses/artistid3) `roles` field (e.g. `albumartist`, `artist`, `composer`). An artist is returned if it has **any** of the requested roles. The special value `all` returns every artist regardless of role. When `artistRole` is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected.
 {{< /alert >}}
 
 ### Example

content/en/docs/Extensions/artistRoleFilter.md

@@ -0,0 +1,26 @@
+---
+title: "Artist role filter"
+linkTitle: "Artist role filter"
+OpenSubsonic:
+- Extension
+description: >
+  Add support for filtering artist lists by artist role.
+---
+
+**OpenSubsonic version**: [1](../../opensubsonic-versions)
+
+**OpenSubsonic extension name**: `artistRoleFilter` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions))
+
+When a server supports this extension it means that it supports filtering the returned artists by role: the `role` parameter of the [`getArtists`](../../endpoints/getartists) endpoint and the `artistRole` parameter of the [`search3`](../../endpoints/search3) endpoint. (The parameter is named `artistRole` on `search3` to disambiguate it from that endpoint's album and song results.)
+
+## Version 1
+
+You can now filter the artists returned by [`getArtists`](../../endpoints/getartists) and [`search3`](../../endpoints/search3) by role, letting clients choose whether they want album artists, track artists, or every artist regardless of role.
+
+Historically these endpoints return only album artists. Some clients want the full set of artists (composers, track artists, etc.) - for example to mirror the whole library - while legacy clients rely on the album-artist-only behavior. This extension lets the client, rather than the server, decide.
+
+The parameter may be repeated to request several roles, using the values found in the [`ArtistID3`](../../responses/artistid3) `roles` field (e.g. `albumartist`, `artist`, `composer`). An artist is returned if it has **any** of the requested roles. The special value `all` returns every artist regardless of role.
+
+When the parameter is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected. On [`search3`](../../endpoints/search3), the parameter only affects the returned artists; albums and songs are unaffected.
+
+This extension requires the support of the `role` parameter of [`getArtists`](../../endpoints/getartists) and the `artistRole` parameter of [`search3`](../../endpoints/search3).

content/en/docs/opensubsonic-versions.md

@@ -12,7 +12,7 @@ This table shows the supported extensions by OpenSubsonic versions:
 
 | OpenSubsonic version | Supported extension |
 | --- | --- |
-| 1 | [Template extension](../extensions/template), [Sonic similarity](../extensions/sonicSimilarity) |
+| 1 | [Template extension](../extensions/template), [Sonic similarity](../extensions/sonicSimilarity), [Artist role filter](../extensions/artistRoleFilter) |
 
 **Note**: Since extensions are optional, more extensions can be added over time to the same OpenSubsonic API version.
 

openapi/endpoints/getArtists.json

@@ -15,6 +15,20 @@
                 "schema": {
                     "type": "string"
                 }
+            },
+            {
+                "name": "role",
+                "in": "query",
+                "description": "Requires the `artistRoleFilter` OpenSubsonic extension. Repeat this parameter to filter the returned artists by one or more roles (as in `ArtistID3.roles`, e.g. `albumartist`, `artist`, `composer`); an artist is returned if it has any of the requested roles. The special value `all` returns every artist regardless of role. When omitted, the behavior is server-defined.",
+                "required": false,
+                "explode": true,
+                "style": "form",
+                "schema": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
             }
         ],
         "responses": {
@@ -51,6 +65,13 @@
                             "musicFolderId": {
                                 "type": "string",
                                 "description": "If specified, only return artists in the music folder with the given ID. See `getMusicFolders`."
+                            },
+                            "role": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string"
+                                },
+                                "description": "Requires the `artistRoleFilter` OpenSubsonic extension. Repeat this parameter to filter the returned artists by one or more roles (as in `ArtistID3.roles`, e.g. `albumartist`, `artist`, `composer`); an artist is returned if it has any of the requested roles. The special value `all` returns every artist regardless of role. When omitted, the behavior is server-defined."
                             }
                         }
                     }

openapi/endpoints/search3.json

@@ -91,6 +91,20 @@
                 "schema": {
                     "type": "string"
                 }
+            },
+            {
+                "name": "artistRole",
+                "in": "query",
+                "description": "Requires the `artistRoleFilter` OpenSubsonic extension. Repeat this parameter to filter the returned artists by one or more roles (as in `ArtistID3.roles`, e.g. `albumartist`, `artist`, `composer`); an artist is returned if it has any of the requested roles. The special value `all` returns every artist regardless of role. Only affects the returned artists (albums and songs are unaffected). When omitted, the behavior is server-defined.",
+                "required": false,
+                "explode": true,
+                "style": "form",
+                "schema": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
             }
         ],
         "responses": {
@@ -168,6 +182,13 @@
                             "musicFolderId": {
                                 "type": "string",
                                 "description": "(Since 1.12.0) Only return albums in the music folder with the given ID. See `getMusicFolders`."
+                            },
+                            "artistRole": {
+                                "type": "array",
+                                "items": {
+                                    "type": "string"
+                                },
+                                "description": "Requires the `artistRoleFilter` OpenSubsonic extension. Repeat this parameter to filter the returned artists by one or more roles (as in `ArtistID3.roles`, e.g. `albumartist`, `artist`, `composer`); an artist is returned if it has any of the requested roles. The special value `all` returns every artist regardless of role. Only affects the returned artists (albums and songs are unaffected). When omitted, the behavior is server-defined."
                             }
                         },
                         "required": [