From 4451266d63bdec5445719c48d229d451c2cf73f0 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@deluan.com>
Date: Thu, 16 Jul 2026 11:35:42 -0400
Subject: [PATCH 1/2] docs(smartplaylists): document per-playlist refreshDelay

---
 .../usage/features/smart-playlists/index.md   | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/content/en/docs/usage/features/smart-playlists/index.md b/content/en/docs/usage/features/smart-playlists/index.md
index 5d5ddedd..8513e4ec 100644
--- a/content/en/docs/usage/features/smart-playlists/index.md
+++ b/content/en/docs/usage/features/smart-playlists/index.md
@@ -118,6 +118,22 @@ This playlist includes 10% of all loved tracks, selected randomly. Use `limitPer
 }
 ```
 
+### Example 8: Daily Mix (stable for a day)
+
+This playlist picks 20 random tracks played in the last 30 days, and keeps the same track list for a full day
+before re-evaluating. Without `refreshDelay`, a playlist like this would change after every song you play,
+which breaks offline caches. See [Refreshing Playlists](#refreshing-playlists) for details.
+
+```json
+{
+  "name": "Daily Mix",
+  "all": [{ "inTheLast": { "lastPlayed": 30 } }],
+  "sort": "random",
+  "limit": 20,
+  "refreshDelay": "1d"
+}
+```
+
 ## Creating Smart Playlists using the UI
 
 Currently Smart Playlists can only be created by manually editing `.nsp` files. We plan to add a UI for creating and
@@ -164,6 +180,33 @@ This delay can be adjusted by setting the
 By default, this is set to `5s`, meaning that Smart Playlists refreshes are spaced at least 5 seconds apart.
 You can adjust this value in the configuration file.
 
+#### Per-Playlist Refresh Delay
+
+You can override the global delay for an individual playlist by adding a `refreshDelay` to its `.nsp` file. The
+playlist then keeps the same track list until that much time has passed since it was last evaluated. This is useful
+for "daily mix" style playlists whose rules would otherwise reshuffle the tracks on every access, and it keeps the
+track list stable for clients that cache playlists for offline playback.
+
+```json
+{
+  "name": "Weekly Discoveries",
+  "all": [{ "notInTheLast": { "lastPlayed": 90 } }],
+  "sort": "random",
+  "limit": 50,
+  "refreshDelay": "1w"
+}
+```
+
+The value is a duration string. Besides the standard units (`h`, `m`, `s`), `d` (days) and `w` (weeks) are also
+supported, so values like `"12h"`, `"1d"`, `"1w"` or `"1d12h"` all work. The delay is a rolling window measured
+from the last evaluation, not aligned to calendar days. When `refreshDelay` is not set, the global
+`SmartPlaylistRefreshDelay` applies.
+
+Editing the playlist's rules (by changing the `.nsp` file or via a client) always takes effect on the next access,
+even if the refresh delay has not elapsed yet.
+
+`refreshDelay` is available since version 0.64.0.
+
 ## Troubleshooting Common Issues
 
 ### Playlist Not Showing Up

From 3a87420644feffec6a9129754f553080ae224bd3 Mon Sep 17 00:00:00 2001
From: Deluan <deluan@deluan.com>
Date: Thu, 16 Jul 2026 14:42:17 -0400
Subject: [PATCH 2/2] docs(smartplaylists): drop version availability note

---
 content/en/docs/usage/features/smart-playlists/index.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/content/en/docs/usage/features/smart-playlists/index.md b/content/en/docs/usage/features/smart-playlists/index.md
index 8513e4ec..d7c57f27 100644
--- a/content/en/docs/usage/features/smart-playlists/index.md
+++ b/content/en/docs/usage/features/smart-playlists/index.md
@@ -205,8 +205,6 @@ from the last evaluation, not aligned to calendar days. When `refreshDelay` is n
 Editing the playlist's rules (by changing the `.nsp` file or via a client) always takes effect on the next access,
 even if the refresh delay has not elapsed yet.
 
-`refreshDelay` is available since version 0.64.0.
-
 ## Troubleshooting Common Issues
 
 ### Playlist Not Showing Up