--- a/doc/upplay.html
+++ b/doc/upplay.html
@@ -818,7 +818,7 @@
<div class="paragraph"><p>You can clear the current playlist by clicking the broom icon above it on
the right.</p></div>
<div class="sect2">
-<h3 id="_saved_seek_position_mode">Saved seek position mode</h3>
+<h3 id="_saved_seek_position_mode_for_version_1_3_and_later">Saved seek position mode (for version 1.3 and later)</h3>
<div class="paragraph"><p>If "Save seek position when switching tracks" is set in the preferences,
then, when double-clicking a track in the playlist, the play will start at
a saved seek position instead of the beginning.</p></div>
@@ -832,7 +832,7 @@
<li>
<p>
If the playlist is in normal mode, the saved position will be the last
- position played (before previously switching tracks).
+ position played (before the previous track switch).
</p>
</li>
</ul></div>
@@ -1053,7 +1053,10 @@
<li>
<p>
<code>Save / Load playlist</code> 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 <strong>not</strong> work with <strong>Minidlna</strong> and
+ <strong>MediaTomb</strong>. See <a href="#SAVED-PLAYLISTS">the more detailed note on this subject</a>
</p>
</li>
<li>
@@ -1132,12 +1135,65 @@
a decimal scale factor.</p></div>
</div>
</div>
+<div class="sect1">
+<h2 id="SAVED-PLAYLISTS">Issues in saving and restoring playlists</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The Upplay file menu has an entry to save the current playlist to disk, and
+load the saved playlist.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>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).</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>It follows that these media servers are incompatible with the playlist
+saving facility. This would be very complicated to fix.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>I don’t have an exhaustive list of the servers which work or don’t. For
+now, just a few examples:</p></div>
+<div class="paragraph"><p>Media servers which do not preserve the URLs (incompatible with the
+playlist saving facility):</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Minidlna
+</p>
+</li>
+<li>
+<p>
+MediaTomb
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Media servers which do preserve the URLs:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Minimserver
+</p>
+</li>
+<li>
+<p>
+Upmpdcli local Media Server (uprcl module).
+</p>
+</li>
+</ul></div>
+</div>
+</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
- 2018-10-04 15:46:52 CEST
+ 2018-11-04 22:44:59 CET
</div>
</div>
</body>