From 823a6f5152c950e46d7920d3f69d912e17f4726c Mon Sep 17 00:00:00 2001 From: Aaron Date: Fri, 26 Sep 2025 19:31:36 -0400 Subject: [PATCH] start --- How-to-Use-Smart-Playlists-in-Navidrome.md | 258 +++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 How-to-Use-Smart-Playlists-in-Navidrome.md diff --git a/How-to-Use-Smart-Playlists-in-Navidrome.md b/How-to-Use-Smart-Playlists-in-Navidrome.md new file mode 100644 index 0000000..cca108b --- /dev/null +++ b/How-to-Use-Smart-Playlists-in-Navidrome.md @@ -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/) + +--- \ No newline at end of file