--- a
+++ b/doc/upmpdcli-or-mpdupnp.txt
@@ -0,0 +1,97 @@
+= MPD and UPnP
+
+There are two different approaches for integrating MPD in an UPnP
+context. They are very different, it makes no sense to use both, and they
+are often confused anyway. Here follows a tentative explanation.
+
+
+== Pure MPD (no UPnP)
+
+By default, MPD accesses audio data through a file-level protocol, either
+reading from the local file system, or from a network disk shared through
+NFS or Windows sharing (SMB).
+
+You tell MPD where the data is by setting a directory path in the MPD
+configuration file (e.g. `music_directory "/home/me/MyMusic"`.
+
+There are also standard plugins for fetching data in other ways, mostly
+used for internet radios. One of them, which I'll mention because it is
+used by the UPnP integration solutions, is the *curl* plugin, used for
+fetching data through HTTP (the WEB protocol).
+
+MPD manages its own tags catalog, which it builds from metadata extracted
+from the audio files.
+
+You browse the catalog and control playing with an MPD client, which uses
+an MPD-specific protocol to talk to the *mpd* daemon. There are many clients,
+from Linux command-line ones, to GUIs, to WEB/PHP based ones.
+
+
+== Why would you want to change this ?
+
+The main possible reasons:
+
+ - You want to use an UPnP control point for browsing and playing music,
+ because you are used to it, because you use it for other things, or
+ because you just prefer it to native MPD clients.
+ - Your audio data is stored on an UPnP Media Server, you took a
+ lot of care to organize the tags, and you don't like the way the MPD
+ database is organized.
+ - You have / want several music players, and duplicating the catalog on
+ each of them seems wasteful (which would happen with multiple MPD
+ instances in their default configuration).
+ - Your media server does not have a file-level interface (unlikely), so
+ you can't use bare MPD with it. Or you just don't want to set it up.
+
+There are two approaches to insert MPD in an UPnP context. They are very
+different, but from the user point of view, the only question which matters
+is:
+
+ - _Do you want to use an MPD client (e.g. MPDroid, Cantata, etc.) to
+ control the playing, or an UPnP one (e.g. Bubble UPnP, PlugPlayer,
+ Lumin, etc.) ?_
+
+If you want an MPD client, you will choose the mpd-upnp approach (back-end
+integration)
+
+If you want an UPnP Control Point, you will choose the front-end one.
+
+Both solutions are described in more detail below. Note that once you've
+decided the kind of control software that you want to use, there is no real
+need for more details: just go install the right one.
+
+== Front-end integration: upmpdcli, MediaPlayer
+
+These are applications which sit in front of MPD. Upmpdcli is C++,
+MediaPlayer is Java, they both do mostly the same things, the choice is
+largely about which will be easier to install on your particular Linux
+distribution.
+
+Both present a standard UPnP/DLNA/OpenHome interface to the network, and
+are usable with most UPnP Control Points.
+
+They talk the MPD client protocol behind the scenes to control actual music
+playing.
+
+Your UPnP Control Point (your user interface) directly browses catalog data
+from an UPnP Media Server (e.g. Minim Server, MiniDlna, Asset, Twonky,
+etc.), and tells upmpdcli or MediaPlayer what to play. upmpdcli/MediaPlayer
+then controls MPD, which fetches the audio data through an HTTP URL
+(pointing to the Media Server).
+
+MPD remains directly usable from an MPD client. It could also manage
+local audio data and a catalog, even if this does not make much sense.
+
+== Back-end integration: mpd-upnp
+
+This is implemented as an MPD Database plugin. Instead of reading files and
+building its own catalog, MPD accesses an UPnP Media Server both for tag
+and audio data. Tags are accessed through UPnP, and data is retrieved
+through HTTP.
+
+MPD then translates the UPnP catalog data to the native MPD client
+protocol, so that MPD clients think that they are talking to a normal MPD
+(but instead they are browsing the UPnP Media Server _through_ MPD).
+
+In this configuration, MPD can't manage local data and tags. The file and
+UPnP database plugins are mutually exclusive.