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 using the similar-artist strategy 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

Other playlist strategies (genre, random, smart rules) do not require an API key.

Generating a playlist

1. Open the Shanty web UI and go to Playlists.
2. Click the Generate tab.
3. Choose a generation strategy:
   • Similar Artists -- Start with one or more seed artists and build a playlist from their music and music by similar artists. This is the most useful strategy for discovering connections in your library.
   • Genre -- Filter tracks by genre tags.
   • Random -- A random selection from your library.
   • Smart Rules -- Define rules based on track attributes (artist, album, year, genre, etc.).
4. For the Similar Artists strategy:
   • Search for and select one or more seed artists.
   • Adjust popularity bias (higher values favor well-known tracks, lower values dig deeper).
   • Set the track count (how many tracks in the playlist).
   • Choose ordering: interleave (mix artists evenly), score (highest match first), or random.
5. Click Generate.

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

Saving a playlist

After generating a playlist, click Save to give it a name and store it. 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 or update its description.

Exporting as M3U

To export a playlist as an M3U file (compatible with most music players):

1. Open a saved playlist.
2. Click Export M3U.
3. The file downloads to your computer.

M3U files contain file paths relative to your library, so they work with any music player that has access to the same library directory.

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.

Generation strategies explained

Similar Artists

This 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 exist in your library.

The popularity bias slider controls the balance:

• High bias (closer to 1.0): favors popular/well-known tracks
• Low bias (closer to 0.0): gives equal weight to all tracks

Genre

Filters your library by genre tags and selects tracks that match. You can specify one or more genres.

Random

A random sample from your entire library. If ordering is not set to "random," tracks are ordered by artist/album for easier listening.

Smart Rules

Define custom rules like:

• Artist contains "Pink Floyd"
• Year is between 1970 and 1980
• Genre is "Progressive Rock"

Tracks matching all rules are included, up to the count limit.