--- a
+++ b/doc/upmpdcli-cloud.txt
@@ -0,0 +1,87 @@
+= Upmpdcli and the Cloud
+
+== Introduction
+
+upmpdcli is initially a UPnP Media Renderer device: it receives music
+descriptors, and downloads and plays what it is requested to play (or more
+precisely, tells MPD to play it).
+
+As standard with UPnP, this is done in conjunction with a Control Point,
+with which the user interacts, and a Media Server, which stores the music
+and exports catalog and audio data. The Control Point browses the music
+catalog offered by the Media Server, and tells upmpdcli/mpd what to play.
+The Renderer then talks directly to the Media Server to download the audio
+data.
+
+This approach presents a difficulty for integrating a streaming service
+such as Tidal, Qobuz, or Google Play Music: they require authentication,
+and only provide temporary URLs for downloading (these URLs can't sit in a
+playlist in the Renderer, they would expire). Using a "natural" approach
+where the Control Point would browse the service, and the Renderer access
+its data, there would be two devices which would need to know about the
+details of the streaming service authentication and security: the Control
+Point and the Renderer, probably needing, in addition, more communication
+between the two than was standardized by UPnP.
+
+There is a relatively simple solution to this problem, which is to design a
+Media Server to act as a gateway to the services. The Media Server deals
+with authentication, presents the service assets inside a browsable and
+possibly searchable tree, and exports stable URLs to the local network
+Renderers. When the data is actually requested, the Media Server manages to
+provide it, which can be handled by an HTTP redirection to the freshly
+translated service URL, or by actually proxying the data stream.
+
+There are some potential reasons to closely associate such a Media Server
+to a Control Point (a solution adopted by a very well known Android Control
+Point), or to the Renderer itself, which is the approach chosen for
+upmpdcli. In practise though, it was found that a standalone Media Server
+works. The upmpdcli Media Server can provide access to any local Media
+Renderer (upmpdcli-based or not), not only to its upmpdcli instance.
+
+The current implementation supports Google Music, Qobuz and Tidal, and
+would be easy to extend for other cloud services.
+
+This only works for users who have a valid subscription for the service
+they want to access.
+
+The Media Server uses the services' WEB APIs which are in general not
+officially supported, so that any service could stop working at any moment
+if the supplier decides that they want to close access.
+
+== Implementation
+
+The Media Server was initially implemented as an embedded UPnP device
+inside the Renderer device. This was found to confuse many Control Points,
+so that the default approach is now to have the Media Server as a separate
+root device (running inside a separate process because of libupnp
+limitations).
+
+The Media Server device will be created if the configuration file has set
+parameters for any of the supported services. See the
+link:upmpdcli.html#upmpdcli.configfile[configuration documentation] for
+details (look for your service name).
+
+== Installation and service-specific notes
+
+The code for accessing most services is self-contained. There is an
+exception for Google Music, which needs the separate installation of a
+Python library.
+
+=== Google Music
+
+You need to install the
+link:http://unofficial-google-music-api.readthedocs.io/en/latest/usage.html#usage[gmusicapi Python Package]
+
+=== Tidal
+
+Nothing for now.
+
+=== Qobuz
+
+Nothing for now.
+
+
+
+
+
+