Main/docs/features/playlists.md

Playlists

Shanty can generate playlists from your library using similar-artist data from Last.fm. You can also create and edit playlists manually, export them as M3U files, and access them from Subsonic clients.

Requirements

Playlist generation requires a Last.fm API key. Set it via the SHANTY_LASTFM_API_KEY environment variable:

# In docker-compose.yml
environment:
  - SHANTY_LASTFM_API_KEY=your_api_key_here

Get a free API key at: https://www.last.fm/api/account/create

When creating your API account, use any application name and leave the callback URL blank or enter http://localhost.

Generating a playlist

1. Open the Shanty web UI and go to Playlists.
2. Click the Generate tab.
3. Search for and select one or more seed artists from your library. The dropdown shows all artists you have tracks for.
4. Adjust popularity bias (higher values favor well-known tracks, lower values dig deeper).
5. Set the track count (how many tracks in the playlist).
6. Choose ordering:
   • Interleave -- spreads artists evenly throughout the playlist, avoiding back-to-back tracks from the same artist.
   • By Score -- highest-scored tracks first (most similar to your seeds, weighted by popularity).
   • Random -- fully shuffled.
7. Click Generate.

The generated playlist is shown as a preview. You can then save it or adjust the parameters and regenerate.

How generation works

Shanty uses Last.fm's similar-artist data to find tracks from artists related to your seeds. For example, if you seed with "Radiohead," the playlist might include tracks by Radiohead, Thom Yorke, Portishead, Massive Attack, and other similar artists -- but only tracks that actually exist in your library.

The popularity bias slider (0-10) controls the balance:

• Higher values favor popular, well-known tracks from each artist.
• Lower values give more equal weight to deep cuts and lesser-known tracks.

Multiple seed artists are blended together -- artists similar to more of your seeds get higher scores.

Creating a blank playlist

From the Saved tab, click New to create an empty playlist and open it in the editor. You can then add tracks manually.

Saving a generated playlist

After generating a playlist, enter a name and click Save Playlist. Saved playlists appear in the Saved tab.

Editing a playlist

1. Go to the Saved tab in Playlists.
2. Click Edit on a playlist.
3. In the Edit tab, you can:
   • Drag and drop tracks to reorder them.
   • Remove tracks by clicking the remove button next to each track.
   • Add tracks by searching in the track picker at the bottom.
   • Rename the playlist.
4. Click Save when done.

Exporting as M3U

From the Saved tab, click M3U on any playlist to download it as an M3U file. M3U files are compatible with most music players and contain file paths relative to your library.

Playlists via Subsonic

Saved playlists are available through the Subsonic API. Any Subsonic client that supports playlists (most do) can see and play your Shanty playlists.

To use this, make sure you have Subsonic set up with a Subsonic password configured.