Upmpdcli Media Server plugins

Return a parameter value. This usually comes from the upmpdcli configuration file (from the key nm), but also possibly from the environment variable named UPMPDCLI_<NM> where <NM> is the uppercased nm argument. The file is searched first, then the environment. If the key is not found, the dflt value is returned. If dflt is set, and a value is found, the method tries to convert the string value to the type of dflt.

Return the name of a cache directory for this plugin. The location will exist and be writable. It is private to the plugin, to store whatever it needs. The information will be persistent across reboots (typically under /var/cache/upmpdcli/<plgname>).

Create and return a container object with the specified values (see further down about container and item objects).

Return the upmpdcli configuration as a ConfSimple object (see the pycommon/conftree.py module). Normally not used as getOptionValue() will do a better job.

Print a message to the log (which is usually stderr at the moment).

Return a pair of values from the configuration, the values for the configuration parameters named <plgname>user and <plgname>password. The password may be empty or undefined in the configuration, but the user name will always be defined (even with a bogus non-null value) because its presence determines if upmpdcli will start a process for the corresponding plugin. This method need not be used by plugins which don’t actually require user credentials.

See the trackuri() plugin method description for a detailed explanation.

Return an URL constructed from the upmpdcli HTTP server host and port (UPMPDCLI_HOSTPORT), the plugin pathprefix (UPMPDCLI_PATHPREFIX), and the service track identifier.

See the trackuri() plugin method description for a detailed explanation.

Return a track identifier extracted from the path part of an URL constructed by url_from_trackid() (or built like them). The a parameter is the one received by trackuri().

The following are dictionary keys present in both containers and items. All keys and values are strings.

The following attributes relate to the performance itself, independantly of a concrete representation. All fields are largely optional:

The following attributes relate to a specific representation, e.g. a flac or mp3 file. Note that renderers will usually override the values by getting them from the actual data. Control Points may display some of them, especially "duration"

Additionally, if a "resources" field is present in the entry, it must be an array of additional objects each describing a specific representation of the performance, as above. Returning several resources with different formats (MIME, sample rate, etc.) may allow the Control Point and Renderer to choose the best one.

The input is single Python dict parameter with the following keys:

Note that a plugin can always chose to ignore offset and count and return all its data (indicating it does so in the return values).

Return value: this must return a Python dict with the following keys:

This gets a single Python dict parameter with the following keys:

The return value is identical to the one for the browse() method.

Some plugins act as proxies for streaming music services like Qobuz or Tidal. The streams supplied by most of these services have no permanent URLs. Rather, a temporary URL with a limited life time is used to get the data. Consequently the actual stream URLs cannot be directly used in the UPnP data, because, for example, they would become stale while sitting in the playlist waiting to be retrieved. Instead, the URLs initially supplied by the upmpdcli plugins in the return lists of browse() or search() just contain the permanent track identifier, and point to the internal upmpdcli HTTP server.

When the renderer actually requests the URL, the upmpdcli server obtains the actual service stream URL from the plugin, and either redirects the renderer to it, or, for renderers which would not support redirection, proxies the stream data. The choice between proxying or redirecting is currently done globally, for all plugins and renderers, but this could be changed. By default, redirection is used, being much more efficient.

This mechanism is implemented in the plugin by the trackuri() method, which receives the permanent URL, extracts the track id, and requests the temporary URL from which the audio data can actually be fetched from the streaming service.

Example, the Qobuz plugin trackuri() method:

The trackuri() method receives a single parameter which is the URL path part, and should extract the track identifier and request a temporary URL from the service.

Return value: the method must return a Python dictionary with a single key: "media_url", the temporary service URL.

The permanent URLs are constructed in the following way: the host and port are obtained from the UPMPDCLI_HOSTPORT configuration variable (e.g. "192.168.1.1:9090"), and the beginning of the path part is obtained from UPMPDCLI_PATHPREFIX (in practise "/" + <plgname>, e.g. "/tidal"). The host and port is of course necessary so that the renderer goes to the right server. The path prefix tells the server from what plugin it should request the actual URL. The rest of the URL is up to the plugin, but some common code (not of mandatory use) assumes the following form: <pathprefix>/track/version/1/trackId/<trackid>

Two helper methods in the upmplgutil module support the mechanism: url_from_trackid() constructs an appropriate URL, and trackid_from_urlpath() extracts the trackid from the path part of an incoming URL.