Search playlists

content/en/docs/Endpoints/search3.md

@@ -26,12 +26,23 @@ Music is organized according to ID3 tags.
 | `albumOffset` | No|    | 0   | Search result offset for albums. Used for paging. |
 | `songCount` | No |   | 20  | Maximum number of songs to return. |
 | `songOffset` | No |   | 0   | Search result offset for songs. Used for paging. |
+| `playlistCount` | No |  **Yes** | 0  | Maximum number of playlists to return. |
+| `playlistOffset` | No | **Yes**  | 0   | Search result offset for playlists. Used for paging. |
 | `musicFolderId` | No |   |     | (Since [1.12.0](../../subsonic-versions)) Only return results from music folder with the given ID. See `getMusicFolders`. |
 
 {{< 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.
 {{< /alert >}}
 
+{{< alert color="warning" title="OpenSubsonic" >}}
+New parameters are added:
+
+- `playlistCount`
+- `playlistOffset`
+
+To ensure compatibility with clients that are not expecting these playlist results, `playlistCount` defaults to 0. If you want playlist results, you must opt in by specifying a positive integer value.
+{{< /alert >}}
+
 ### Example
 
 {{< alert color="primary" >}} `http://your-server/rest/search3.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json&query=""&artistCount=1&albumCount=1&songCount=1` {{< /alert >}}
@@ -108,6 +119,20 @@ A [`subsonic-response`](../../responses/subsonic-response) with a nested [`searc
           "type": "music",
           "isVideo": false
         }
+      ],
+      "playlist": [
+        {
+          "id": "800000075",
+          "name": "testcreate",
+          "owner": "user",
+          "public": true,
+          "created": "2023-03-16T03:18:41+00:00",
+          "changed": "2023-03-16T03:18:41+00:00",
+          "songCount": 1,
+          "duration": 304,
+          "readonly": true,
+          "validUntil": "2023-03-23T03:18:41+00:00"
+        }
       ]
     }
   }

content/en/docs/Extensions/search3Playlists.md

@@ -0,0 +1,29 @@
+---
+title: "search3 Playlists"
+linkTitle: "search3 Playlists"
+OpenSubsonic:
+- Extension
+description: >
+  Allows searching for playlists by query text.
+---
+
+**OpenSubsonic version**: [1](../../opensubsonic-versions)
+
+**OpenSubsonic extension name**: `search3Playlists` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions))
+
+Allows searching for playlists by query text. Adds `playlistCount` and `playlistOffset` params to [`search3`](../../endpoints/search3) endpoint.
+
+## Version 1
+
+Adds parameters to [`search3`](../../endpoints/search3):
+
+- `playlistCount`
+- `playlistOffset`
+
+When the user wants to search for a playlist by name, call this endpoint with the query text and specify a positive integer for `playlistCount`. Page through additional results if needed with `playlistOffset`.
+
+The server **should** use the query text to search playlist names.
+
+The server **may** also use the query text to search playlists by other metadata; this is an implementation detail left up to the server developer. However it is implemented, the server **should not** return playlist results irrelevant to the user's query.
+
+The server **may** order playlist results by name, by relevance, or by some other criteria. The same input **should** return results in the same order every time (deterministic).

content/en/docs/Responses/searchResult3.md

@@ -66,6 +66,20 @@ description: >
       "type": "music",
       "isVideo": false
     }
+  ],
+  "playlist": [
+    {
+      "id": "800000075",
+      "name": "testcreate",
+      "owner": "user",
+      "public": true,
+      "created": "2023-03-16T03:18:41+00:00",
+      "changed": "2023-03-16T03:18:41+00:00",
+      "songCount": 1,
+      "duration": 304,
+      "readonly": true,
+      "validUntil": "2023-03-23T03:18:41+00:00"
+    }
   ]
 }
 {{< /tab >}}
@@ -136,3 +150,10 @@ description: >
 | `artist` | Array of [`ArtistID3`](../artistid3) | No |     | Matching artists |
 | `album` | Array of [`AlbumID3`](../albumid3) | No |     |  Matching albums  |
 | `song` | Array of [`Child`](../child) | No |     | Matching songs |
+| `playlist` | Array of [`Playlist`](../playlist) | No | **Yes** | Matching playlists |
+
+{{< alert color="warning" title="OpenSubsonic" >}}
+New field is added:
+
+- `playlist`
+{{< /alert >}}