Expose playlists within web API

mgoltzsche commented 9 months ago

I am using mopidy with the mopidy-beets plugin to play music that it streams from a beets web server that runs on another machine. However, while mopidy-beets lets me search for tracks and browse albums, unfortunately it doesn't let me access playlists (probably because the beets web API doesn't expose them). On the other hand, using beets' smartplaylist plugin, I have defined rules to generate playlists within my beets config under smartplaylist.playlists already. Now ideally I'd like to browse those playlists within mopidy. One way to do that could be to enhance the mopidy-beets plugin to be able to configure the same rules as for the smartplaylist beets plugin. However, that would require users to duplicate the playlist configuration and maintain it in two different places. Instead, to maintain the playlist configuration in a single/central place, the beets web API could expose the playlists defined by the smartplaylist plugin's configuration. Alternatively, there could be a separate object introduced within the beets config to define playlists and both the web and smartplaylist plugin would obtain their configuration also from that configuration object. Either way, clients such as mopidy-beets could be enhanced to provide more useful and individual/personalized ways of browsing a beets library using the playlists defined within that library.

Proposed solution

Let the beets web API expose the playlists defined by the existing smartplaylist.playlists beets configuration. Two new GET endpoints should be added that each return a JSON response:

/playlist/ to list the available playlists (only their names really).
/playlist/{name} to list the tracks contained within a particular playlist (specified by path param) using the same response format as the /item/ endpoint. The endpoint would run all configured queries for the referenced playlist and return the merged results in the same way the smartplaylist plugin does.

Example response body of the /playlist/ endpoint:

{
  "playlists": [
    {
      "name": "jazz.m3u"
    },
  ]
}

Example response body of the /playlist/{name} endpoint:

{
  "items": [
    {
      "id": 1,
      "title": "Bag's Groove",
      "artist": "Miles Davis",
      ...
    },
    ...
  ]
}

Objective

Allow remote clients to easily access the playlists defined within the beets library.

Goals

Expose the playlists that can be defined and generated using the smartplaylist plugin within the beets web API.

Non-goals

No need to implement an optimized solution that involves caching or maintaining a materialized view of the playlists within a separate sqlite table (if needed, users could configure caching within the reverse-proxy (that is apparently needed anyway to make streaming/range queries work :disappointed:)).
To avoid maintenance/compatibility issues and to keep things simple, this feature should not modify sqlite data at all.

Anti-goals

Additional complexity such as mounting a distributed file system to access the generated playlist files.
Having to maintain the same set of playlist definitions in multiple places instead of maintaining them centrally within the beets library.
Ideally, there shouldn't be two different implementations to generate the m3u files and to expose playlists within the API but this code should be shared by both beets plugins in order to minimize maintenance efforts and guarantee the behaviour is consistent between both plugins.

sampsyo commented 9 months ago

The proposed API looks perfectly reasonable! Thanks for the detailed proposal.

Although mopidy-beets doesn't support it yet, I also want to point you toward the AURA plugin, which is meant to be a successor to the web UI plugin that prioritizes a flexible API over use from our little web interface.

mgoltzsche commented 9 months ago

The AURA API looks interesting but it doesn't expose playlists either, does it?

sampsyo commented 9 months ago

Ah, yes, indeed—sorry for not being clear. It doesn't support playlists either, but I brought it up just to point to a place where we might want to focus long-term efforts on evolving the API. It's sort of an academic point, however, since stuff like beets-mopidy only supports the "old" web API.

mgoltzsche commented 9 months ago

Okay, I created a corresponding issue within the AURA API repo now: https://github.com/beetbox/aura/issues/31

sampsyo commented 9 months ago

Awesome; thanks!!

mgoltzsche commented 3 months ago

There is an alternative now: the webm3u plugin can be used to serve M3U playlists (generated by the smartplaylist plugin) via HTTP. The plugin also allows to specify a playlist item URI template as HTTP request parameter (uri-format) in order to be able to let another integration take care of loading the contained songs efficiently. E.g. to access the playlists from your Beets library on another host within Mopidy, you can let the Mopidy-WebM3U plugin delegate to the Mopidy-Beets plugin to load the songs contained within playlists by configuring a seed M3U playlist URL (that points to a webm3u server) with the parameter uri-format=beets:library:track;$id. Something similar could be done using the AURA API potentially in the future.

beetbox / beets