start
commit
823a6f5152
258
How-to-Use-Smart-Playlists-in-Navidrome.md
Normal file
258
How-to-Use-Smart-Playlists-in-Navidrome.md
Normal file
@ -0,0 +1,258 @@
|
|||||||
|
# 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](https://github.com/navidrome/navidrome/issues).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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.*
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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).
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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](https://github.com/feishin/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 `.nsp` file (with `inPlaylist` and `notInPlaylist`).
|
||||||
|
- **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 `.nsp` file is in the correct folder and has the correct permissions.
|
||||||
|
- Ensure the file is correctly formatted (use a [JSON validator](https://jsonlint.com/)).
|
||||||
|
- 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 } }`).
|
||||||
|
> - `filepath` is 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}`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Additional Resources
|
||||||
|
|
||||||
|
- [Navidrome Documentation](https://www.navidrome.org/docs/)
|
||||||
|
- [Feishin Client](https://github.com/feishin/feishin)
|
||||||
|
- [JSON Validator](https://jsonlint.com/)
|
||||||
|
|
||||||
|
---
|
||||||
Loading…
x
Reference in New Issue
Block a user