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