--- a/doc/upplay.txt
+++ b/doc/upplay.txt
@@ -183,7 +183,10 @@
OpenHome, and will let you select the Source among the available ones
(`Playlist`, `Radio` etc.).
- `Save / Load playlist` will let you save the current playlist to a local
- file, or load one which you previously saved.
+ file, or load one which you previously saved. Please note that this can
+ only work with Media Servers which preserve URLs across database
+ rebuilds. Specifically this does *not* work with *Minidlna* and
+ *MediaTomb*. See xref:SAVED-PLAYLISTS[the more detailed note on this subject]
- `Open Songcast Tool` will open a dialog for managing the connections
between Linn Songcast Senders or Receivers. link:songcast.html[more
details here].
@@ -215,3 +218,45 @@
As of version 1.2.10, the font sizes can be adjusted from the preferences
menu ('view->preferences', 'Application Tab', 'Display Scale'). Just choose
a decimal scale factor.
+
+[[SAVED-PLAYLISTS]]
+== Issues in saving and restoring playlists
+
+The Upplay file menu has an entry to save the current playlist to disk, and
+load the saved playlist.
+
+Each saved playlist element is comprised of the audio track URL and the
+track metadata. These are the elements which need to be sent to the Media
+Renderer for playing a given track.
+
+Unfortunately, some Media Servers regenerate the audio track URLs in a more
+or less random way when they regenerate their database (e.g. after the user
+adds a new album).
+
+When this happens, the saved URLs become invalid or can point to a
+different audio track (the metadata: artist, title etc. is still valid of
+course). So, when playing a restored playlist, the correct metadata will be
+displayed, but the wrong audio, or no audio, will be playing.
+
+It follows that these media servers are incompatible with the playlist
+saving facility. This would be very complicated to fix.
+
+The media servers which I know to preserve the URLs build them based on the
+tracks' file system paths. This means that, even with these, the URLs could
+be invalidated if you rearrange the file tree. One could imagine basing the
+URLs on the file hashes, �� la git, but, as far as I know, nobody does
+things this way.
+
+I don't have an exhaustive list of the servers which work or don't. For
+now, just a few examples:
+
+Media servers which do not preserve the URLs (incompatible with the
+playlist saving facility):
+
+- Minidlna
+- MediaTomb
+
+Media servers which do preserve the URLs:
+
+- Minimserver
+- Upmpdcli local Media Server (uprcl module).