= 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.