From f222b47ace21403b86df0d5486bf7135c7df99b2 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Fri, 27 Jun 2025 10:20:26 -0700 Subject: [PATCH 1/3] Music Folder extension MD docs update --- content/en/docs/Endpoints/getgenres.md | 5 ++++- content/en/docs/Endpoints/getsimilarsongs2.md | 1 + content/en/docs/Endpoints/gettopsongs.md | 1 + content/en/docs/Extensions/musicFolder.md | 18 ++++++++++++++++++ 4 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/Extensions/musicFolder.md diff --git a/content/en/docs/Endpoints/getgenres.md b/content/en/docs/Endpoints/getgenres.md index 5c7dae15..cccd5748 100644 --- a/content/en/docs/Endpoints/getgenres.md +++ b/content/en/docs/Endpoints/getgenres.md @@ -13,7 +13,10 @@ Returns all genres. ### Parameters -Takes no extra parameters. +Takes no extra parameters, unless the server supports the [Music Folder](../../extensions/musicfolder) extension, in which case the following parameter is supported. + +| Parameter | Req. | OpenS. | Default | Comment | +| `musicFolderId` | No| **Yes** | | Include only genres for which at least one song in the specified music folder is tagged with that genre. Servers **should** calculate and return `songCount` and `albumCount` relative to the specified music folder only. | ### Example diff --git a/content/en/docs/Endpoints/getsimilarsongs2.md b/content/en/docs/Endpoints/getsimilarsongs2.md index 88284a3c..7af3dbbf 100644 --- a/content/en/docs/Endpoints/getsimilarsongs2.md +++ b/content/en/docs/Endpoints/getsimilarsongs2.md @@ -17,6 +17,7 @@ Similar to [`getSimilarSongs`](../getsimilarsongs), but organizes music accordin | --- | --- | --- | --- | --- | | `id` | **Yes** | | | The artist ID. | | `count` | No | |50 | Max number of songs to return. | +| `musicFolderId` | No | **Yes** | | Include only songs from the music folder with the given ID. The [`Music Folder`](../../extensions/musicfolder) extension marks support for this parameter. | ### Example diff --git a/content/en/docs/Endpoints/gettopsongs.md b/content/en/docs/Endpoints/gettopsongs.md index ec52284c..cd27696e 100644 --- a/content/en/docs/Endpoints/gettopsongs.md +++ b/content/en/docs/Endpoints/gettopsongs.md @@ -17,6 +17,7 @@ Returns top songs for the given artist, using data from [last.fm](http://last.fm | --- | --- | --- | --- | --- | | `artist` | **Yes** | | | The artist name. | | `count` | No | | 50 | Max number of songs to return. | +| `musicFolderId` | No | **Yes** | | Include only songs from the music folder with the given ID. The [`Music Folder`](../../extensions/musicfolder) extension marks support for this parameter. | ### Example diff --git a/content/en/docs/Extensions/musicFolder.md b/content/en/docs/Extensions/musicFolder.md new file mode 100644 index 00000000..94f39767 --- /dev/null +++ b/content/en/docs/Extensions/musicFolder.md @@ -0,0 +1,18 @@ +--- +title: "Music Folder +linkTitle: "Music Folder" +OpenSubsonic: + - Extension +description: > + Adds support for the `musicFolderId` parameter on more browsing APIs. +--- + +**OpenSubsonic version**: [1](../../opensubsonic-versions) + +**OpenSubsonic extension name** `musicFolder` (As returned by [`getOpenSubsonicExtensions`](../../endpoints/getopensubsonicextensions)) + +When a server supports this extension, it supports the `musicFolderId` parameter on additional endpoints. + +## Version 1 + +This version requires servers to support the `musicFolderId` parameter on calls to the following endpoints: [`getGenres`](../../endpoints/getgenres), [`getSimilarSongs2`](../../endpoints/getsimilarsongs2), and [`getTopSongs`](../../endpoints/gettopsongs). When supplied by the client, these calls must only return songs contained within the specified music folder, and only genres for which at least one song is tagged with that genre in the specified music folder. From 61f03b4cee7d30de3e86f334fe3a9aea1afb2883 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sun, 13 Jul 2025 16:14:08 -0700 Subject: [PATCH 2/3] add suggested additional endpoints --- content/en/docs/Endpoints/getartist.md | 1 + content/en/docs/Endpoints/getbookmarks.md | 6 +++++- content/en/docs/Endpoints/getshares.md | 6 +++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/content/en/docs/Endpoints/getartist.md b/content/en/docs/Endpoints/getartist.md index fb057b75..8ad8bacd 100644 --- a/content/en/docs/Endpoints/getartist.md +++ b/content/en/docs/Endpoints/getartist.md @@ -16,6 +16,7 @@ Returns details for an artist, including a list of albums. This method organizes | Parameter | Req. | OpenS. | Default | Comment | | --- | --- | --- | --- | --- | | `id` | **Yes** | | | The artist ID. | +| `musicFolderId` | No | **Yes** | | Only include albums within the given top-level music folder | ### Example diff --git a/content/en/docs/Endpoints/getbookmarks.md b/content/en/docs/Endpoints/getbookmarks.md index 8ea89103..baebd16c 100644 --- a/content/en/docs/Endpoints/getbookmarks.md +++ b/content/en/docs/Endpoints/getbookmarks.md @@ -13,7 +13,11 @@ Returns all bookmarks for this user. A bookmark is a position within a certain m ### Parameters -Takes no extra parameters. +Takes no extra parameters, unless the server supports the [Music Folder](../../extensions/musicfolder) extension, in which case the following parameter is supported. + +| Parameter | Req. | OpenS. | Default | Comment | +| --- | --- | --- | --- | --- | +| `musicFolderId` | No | **Yes** | | Only include bookmarks within the given top-level music folder | ### Example diff --git a/content/en/docs/Endpoints/getshares.md b/content/en/docs/Endpoints/getshares.md index 54e80ac0..8d2b1b12 100644 --- a/content/en/docs/Endpoints/getshares.md +++ b/content/en/docs/Endpoints/getshares.md @@ -13,7 +13,11 @@ Returns information about shared media this user is allowed to manage. Takes no ### Parameters -Takes no extra parameters. +Takes no extra parameters, unless the server supports the [Music Folder](../../extensions/musicfolder) extension, in which case the following parameter is supported. + +| Parameter | Req. | OpenS. | Default | Comment | +| --- | --- | --- | --- | --- | +| `musicFolderId` | No | **Yes** | | Only include shares within the given top-level music folder | ### Example From 374109a3895a00dfa5b3dd0af8cad85819e210c2 Mon Sep 17 00:00:00 2001 From: Drew Weymouth Date: Sun, 13 Jul 2025 16:42:50 -0700 Subject: [PATCH 3/3] fix musicfolder.md --- content/en/docs/Extensions/musicFolder.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/Extensions/musicFolder.md b/content/en/docs/Extensions/musicFolder.md index 94f39767..95786046 100644 --- a/content/en/docs/Extensions/musicFolder.md +++ b/content/en/docs/Extensions/musicFolder.md @@ -1,5 +1,5 @@ --- -title: "Music Folder +title: "Music Folder" linkTitle: "Music Folder" OpenSubsonic: - Extension @@ -15,4 +15,4 @@ When a server supports this extension, it supports the `musicFolderId` parameter ## Version 1 -This version requires servers to support the `musicFolderId` parameter on calls to the following endpoints: [`getGenres`](../../endpoints/getgenres), [`getSimilarSongs2`](../../endpoints/getsimilarsongs2), and [`getTopSongs`](../../endpoints/gettopsongs). When supplied by the client, these calls must only return songs contained within the specified music folder, and only genres for which at least one song is tagged with that genre in the specified music folder. +This version requires servers to support the `musicFolderId` parameter on calls to the following endpoints: [`getGenres`](../../endpoints/getgenres), [`getSimilarSongs2`](../../endpoints/getsimilarsongs2), [`getTopSongs`](../../endpoints/gettopsongs), [`getArtist`](../../endpoints/getartist), [`getShares`](../../endpoints/getshares), and [`getBookmarks`](../../endpoints/getbookmarks). When supplied by the client, these calls must only return songs contained within the specified music folder, and only genres for which at least one song is tagged with that genre in the specified music folder.