Table of Contents
- Navidrome Smart Playlists Guide
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Navidrome Smart Playlists Guide
Smart Playlists in Navidrome offer a dynamic way to organize and enjoy your music collection. They are created using JSON objects stored in .nsp files and are automatically updated based on specified criteria, providing a personalized and evolving music experience.
Beta Feature
Smart Playlists are currently in beta and may have some limitations. Please report issues or suggestions to the Navidrome GitHub issues page.
Creating Smart Playlists
To create a Smart Playlist, define a JSON object with specific fields and operators that describe the criteria for selecting tracks. Save this object in a .nsp file.
Example Playlists
1. Recently Played Tracks
Tracks played in the last 30 days, sorted by most recently played.
{
"name": "Recently Played",
"comment": "Recently played tracks",
"all": [{ "inTheLast": { "lastPlayed": 30 } }],
"sort": "lastPlayed",
"order": "desc",
"limit": 100
}
2. 80’s Top Songs
Top-rated songs from the 1980s.
{
"all": [
{ "any": [{ "is": { "loved": true } }, { "gt": { "rating": 3 } }] },
{ "inTheRange": { "year": [1981, 1990] } }
],
"sort": "year",
"order": "desc",
"limit": 25
}
3. Favourites
All loved tracks, sorted by the date they were loved.
{
"all": [{ "is": { "loved": true } }],
"sort": "dateLoved",
"order": "desc",
"limit": 500
}
4. All Songs in Random Order
All songs in a random order.
Note: Not recommended for large libraries.
{
"all": [{ "gt": { "playCount": -1 } }],
"sort": "random"
// "limit": 1000 // Uncomment to limit the number of songs
}
5. Multi-Field Sorting
Songs from the 2000s, sorted by year (descending), then rating (descending), then title (ascending).
{
"name": "2000s Hits by Year and Rating",
"all": [{ "inTheRange": { "year": [2000, 2009] } }],
"sort": "-year,-rating,title",
"limit": 200
}
6. Library-Specific Playlist
High-rated songs from a specific library.
{
"name": "High-Rated Songs from Library 2",
"all": [{ "is": { "library_id": 2 } }, { "gt": { "rating": 4 } }],
"sort": "-rating,title",
"limit": 100
}
Creating Smart Playlists Using the UI
Currently, Smart Playlists can only be created by manually editing .nsp files.
A UI for creating and editing Smart Playlists is planned for future releases.
Alternatively, you can use Feishin, a desktop/web client for Navidrome, which supports creating Smart Playlists.
Smart Playlists created/edited in Feishin will be available in Navidrome UI as soon as they are saved.
Importing Smart Playlists
Smart Playlists are imported like regular (.m3u) playlists during the library scan.
Place your .nsp files in any folder in your library or the path specified by the PlaylistsPath configuration.
Navidrome will automatically detect and import these playlists.
Managing Smart Playlists
Visibility and Ownership
- Visibility: To make a Smart Playlist accessible to all users, set it to
public. This is crucial if you want to use it in another.nspfile (withinPlaylistandnotInPlaylist). - Ownership: By default, Smart Playlists are owned by the first admin user. You can change the ownership in the Playlists view.
User-Specific Playlists
Smart Playlists based on user interactions (e.g., play count, loved tracks) are automatically updated based on the owner’s interactions.
For personalized playlists, create separate .nsp files for each user and assign ownership accordingly.
Refreshing Playlists
Smart Playlists are refreshed automatically when accessed by the UI or any Subsonic client.
To avoid unnecessary load, there is a minimum delay between refreshes, controlled by the SmartPlaylistRefreshDelay configuration (default: 5s).
Troubleshooting
Playlist Not Showing Up?
- Check the logs for errors during the library scan.
- Ensure the
.nspfile is in the correct folder and has the correct permissions. - Ensure the file is correctly formatted (use a JSON validator).
- Check the playlist’s visibility and ownership settings.
Referencing Other Playlists
When referencing another playlist by ID (using inPlaylist), ensure the referenced playlist is set to public.
Special Characters in Conditions
Operators like contains or endsWith may ignore special characters (e.g., _). Adjust your conditions accordingly.
Sorting by Multiple Fields
Sort by multiple fields by separating them with commas.
Prefix with + (ascending, default) or - (descending).
Examples:
"sort": "year,title"— Sort by year, then title (both ascending)"sort": "year,-rating"— Sort by year (ascending), then rating (descending)"sort": "-lastplayed,title"— Sort by last played (descending), then title (ascending)
The global order field reverses the direction of all sort fields.
Fields
| Field | Description |
|---|---|
| title | Track title |
| album | Album name |
| hascoverart | Track has cover art |
| tracknumber | Track number |
| discnumber | Disc number |
| year | Year of release |
| date | Recording date |
| originalyear | Original year |
| originaldate | Original date |
| releaseyear | Release year |
| releasedate | Release date |
| size | File size |
| compilation | Compilation album |
| dateadded | Date added to library |
| datemodified | Date modified |
| discsubtitle | Disc subtitle |
| comment | Comment |
| lyrics | Lyrics |
| sorttitle | Sorted track title |
| sortalbum | Sorted album name |
| sortartist | Sorted artist name |
| sortalbumartist | Sorted album artist name |
| albumtype | Album type |
| albumcomment | Album comment |
| catalognumber | Catalog number |
| filepath | File path (relative to MusicFolder) |
| filetype | File type |
| duration | Track duration |
| bitrate | Bitrate |
| bitdepth | Bit depth |
| bpm | Beats per minute |
| channels | Audio channels |
| loved | Track is loved |
| dateloved | Date track was loved |
| lastplayed | Date track was last played |
| playcount | Number of times track was played |
| rating | Track rating |
| mbz_album_id | MusicBrainz Album ID |
| mbz_album_artist_id | MusicBrainz Album Artist ID |
| mbz_artist_id | MusicBrainz Artist ID |
| mbz_recording_id | MusicBrainz Recording ID |
| mbz_release_track_id | MusicBrainz Release Track ID |
| mbz_release_group_id | MusicBrainz Release Group ID |
| library_id | Library ID (multi-library) |
Notes:
- Dates must be in the format
"YYYY-MM-DD".- Booleans must not be enclosed in quotes (e.g.,
{ "is": { "loved": true } }).filepathis relative to your music library folder.- Numeric fields support numeric comparisons (
gt,lt,inTheRange, etc.).- You can use any imported or custom tag as a field.
Operators
| Operator | Description | Argument Type |
|---|---|---|
| is | Equal | String, Number, Boolean |
| isNot | Not equal | String, Number, Boolean |
| gt | Greater than | Number |
| lt | Less than | Number |
| contains | Contains | String |
| notContains | Does not contain | String |
| startsWith | Starts with | String |
| endsWith | Ends with | String |
| inTheRange | In the range (inclusive) | Array of two numbers/dates |
| before | Before | Date ("YYYY-MM-DD") |
| after | After | Date ("YYYY-MM-DD") |
| inTheLast | In the last | Number of days |
| notInTheLast | Not in the last | Number of days |
| inPlaylist | In playlist | Playlist ID |
| notInPlaylist | Not in playlist | Playlist ID |
The field type determines the argument type.
To get a playlist’s ID for inPlaylist/notInPlaylist, check the URL in the Navidrome UI (/playlists/{ID}).