Developer:Media Server Extensions

Introduction

The ContentDirectory service has various limitations which become apparent when implementing control points on different hardware platforms. This document aims to outline some ideas that address the various shortcomings of the ContentDirectory specification. The ideas have been categorised in low, medium and high priority groups.

High

Container map

The current ContentDirectory specification makes it very difficult for a control point to display a container in an appropriate way. For example a container containing just albums a UI may decide it wants to display the albums in a grid showing off the artwork. Currently this is not easily achievable without a control point reading all the items in a container and checking that they are ALL albums, only then can it display the contents in a grid. It would be much better if a control point knew ahead of time what to expect when browsing any particular hierarchy served by the media server.

The proposal is to extend the device XML to add mapped containers. There are three types of mapped containers, Browse, Link and Search. A server indicates its capabilities by including or excluding X_MAP_BROWSE, X_MAP_LINK, X_MAP_SEARCH sections in its device XML.

Browse map

The X_MAP_BROWSE element should contain an X_MAP_BROWSE_ENTRY for each browse container map that has been configured. An X_MAP_BROWSE_ENTRY contains three elements, X_MAP_BROWSE_ENTRY_NAME, X_MAP_BROWSE_ENTRY_ID, and X_MAP_BROWSE_ENTRY_TYPE

Example Browse hierarchy that contains a list of albums which each contain tracks.

A control point would use the ContentDirectory Browse action with the ID defined by X_MAP_BROWSE_ENTRY_ID, in this example, "db/browse/albums", to get the DIDL-Lite that describes the container that has all the albums.

A control point would use the X_MAP_BROWSE_ENTRY_TYPE element to make decisions as to how best to represent the results. In this example "album" represents that the media server will return a list of albums that each will contain a list of tracks.

<X_MAP_BROWSE_ENTRY>
    <X_MAP_BROWSE_ENTRY_NAME>Albums</X_MAP_BROWSE_ENTRY_NAME>
    <X_MAP_BROWSE_ENTRY_ID>db/browse/albums</X_MAP_BROWSE_ENTRY_ID>
    <X_MAP_BROWSE_ENTRY_TYPE>album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

Link map

Link is the ability for a user to link between various pieces of metadata for an object. For example if the server supported linking on the artist tag then using the link map a control point would be able to provide the ability for a user to click on a track's artist and display all the albums (or tracks) by that artist.

The X_MAP_LINK element should contain an X_MAP_LINK_ENTRY for each link container map that is allowed.

Example Link that allows a control point to display a list of artist albums when a user click on an artist name associated with some metadata.

A control point would use the ContentDirectory Browse action with the ID "db/link/artist/<artist name>" to get the DIDL-Lite that describes the container that has all the albums.

A control point would use the X_MAP_LINK_ENTRY_TYPE element to make decisions as to how best to represent the results. In this example "album" represents that the media server will return a list of albums that each will contain a list of tracks.

<X_MAP_LINK_ENTRY>
    <X_MAP_LINK_ENTRY_TAG>artist</X_MAP_LINK_ENTRY_TAG>
    <X_MAP_LINK_ENTRY_ID_PREFIX>db/link/artist/</X_MAP_LINK_ENTRY_ID_PREFIX>
    <X_MAP_LINK_ENTRY_TYPE>album</X_MAP_LINK_ENTRY_TYPE>
</X_MAP_LINK_ENTRY>

Example device XML

<root xmlns="urn:schemas-upnp-org:device-1-0">
   <specVersion>
       <major>1</major>
       <minor>1</minor>
   </specVersion>
   <device>
       <deviceType>urn:schemas-upnp-org:device:MediaServer:1</deviceType>
       <dlna:X_DLNADOC xmlns:dlna="urn:schemas-dlna-org:device-1-0">DMS-1.50</dlna:X_DLNADOC>
       <dlna:X_DLNACAP xmlns:dlna="urn:schemas-dlna-org:device-1-0">av-upload,image-upload,audio-upload</dlna:X_DLNACAP>
       <openhome:X_MAP xmlns:openhome="http://www.openhome.org">
           <X_MAP_BROWSE>
               <X_MAP_BROWSE_ENTRY>
                   <X_MAP_BROWSE_ENTRY_NAME>Albums</X_MAP_BROWSE_ENTRY_NAME>
                   <X_MAP_BROWSE_ENTRY_ID>db/browse/albums</X_MAP_BROWSE_ENTRY_ID>
                   <X_MAP_BROWSE_ENTRY_TYPE>album</X_MAP_BROWSE_ENTRY_TYPE>
               </X_MAP_BROWSE_ENTRY>
               <X_MAP_BROWSE_ENTRY>
                   <X_MAP_BROWSE_ENTRY_NAME>Artists</X_MAP_BROWSE_ENTRY_NAME>
                   <X_MAP_BROWSE_ENTRY_ID>db/browse/artists</X_MAP_BROWSE_ENTRY_ID>
                   <X_MAP_BROWSE_ENTRY_TYPE>artist album</X_MAP_BROWSE_ENTRY_TYPE>
               </X_MAP_BROWSE_ENTRY>
               <X_MAP_BROWSE_ENTRY>
                   <X_MAP_BROWSE_ENTRY_NAME>Folders</X_MAP_BROWSE_ENTRY_NAME>
                   <X_MAP_BROWSE_ENTRY_ID>db/browse/folders</X_MAP_BROWSE_ENTRY_ID>
                   <X_MAP_BROWSE_ENTRY_TYPE>mixed</X_MAP_BROWSE_ENTRY_TYPE>
               </X_MAP_BROWSE_ENTRY>
           </X_MAP_BROWSE>
           <X_MAP_LINK>
               <X_MAP_LINK_ENTRY>
                   <X_MAP_LINK_ENTRY_TAG>artist</X_MAP_LINK_ENTRY_TAG>
                   <X_MAP_LINK_ENTRY_ID_PREFIX>db/link/artist/</X_MAP_LINK_ENTRY_ID_PREFIX>
                   <X_MAP_LINK_ENTRY_TYPE>album</X_MAP_LINK_ENTRY_TYPE>
               </X_MAP_LINK_ENTRY>
               <X_MAP_LINK_ENTRY>
                   <X_MAP_LINK_ENTRY_TAG>composer</X_MAP_LINK_ENTRY_TAG>
                   <X_MAP_LINK_ENTRY_ID_PREFIX>db/link/composer/</X_MAP_LINK_ENTRY_ID_PREFIX>
                   <X_MAP_LINK_ENTRY_TYPE>album</X_MAP_LINK_ENTRY_TYPE>
               </X_MAP_LINK_ENTRY>
           </X_MAP_LINK>
           <X_MAP_SEARCH>
               <X_MAP_SEARCH_ENTRY>
                   <X_MAP_SEARCH_ENTRY_NAME>Artist</X_MAP_SEARCH_ENTRY_NAME>
                   <X_MAP_SEARCH_ENTRY_ID_PREFIX>db/search/artist/</X_MAP_SEARCH_ENTRY_ID_PREFIX>
                   <X_MAP_SEARCH_ENTRY_TYPE>album</X_MAP_SEARCH_ENTRY_TYPE>
               </X_MAP_SEARCH_ENTRY>
               <X_MAP_SEARCH_ENTRY>
                   <X_MAP_SEARCH_ENTRY_NAME>Tracks</X_MAP_SEARCH_ENTRY_NAME>
                   <X_MAP_SEARCH_ENTRY_ID_PREFIX>db/search/all/</X_MAP_SEARCH_ENTRY_ID_PREFIX>
                   <X_MAP_SEARCH_ENTRY_TYPE></X_MAP_SEARCH_ENTRY_TYPE>
               </X_MAP_SEARCH_ENTRY>
           </X_MAP_SEARCH>
       </openhome:X_MAP>
       <presentationURL>http://10.2.1.170:4000/res/linn.co.uk.kazooserver/index.html</presentationURL>
       <friendlyName>Linn Kazoo Server [R&D Mac Mini]</friendlyName>
       <manufacturer>Linn</manufacturer>
       <manufacturerURL>http://www.linn.co.uk</manufacturerURL>
       <modelName>Kazoo Server</modelName>
       <modelURL>http://oss.linn.co.uk/trac/wiki/KazooServer</modelURL>
       <UDN>uuid:ac3d630e37b5f11ff5cdd23c0f5a7400</UDN>
       <iconList>
           <icon>
               <mimetype>image/png</mimetype>
               <width>65</width>
               <height>65</height>
               <depth>32</depth>
               <url>ac3d630e37b5f11ff5cdd23c0f5a7400/resource/icon/icon</url>
           </icon>
       </iconList>
       <serviceList>
           <service>
               <serviceType>urn:av-openhome-org:service:PlaylistManager:1</serviceType>
               <serviceId>urn:av-openhome-org:serviceId:PlaylistManager</serviceId>
               <SCPDURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/Upnp/av.openhome.org-PlaylistManager-1/service.xml</SCPDURL>
               <controlURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/av.openhome.org-PlaylistManager-1/control</controlURL>
               <eventSubURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/av.openhome.org-PlaylistManager-1/event</eventSubURL>
           </service>
           <service>
               <serviceType>urn:schemas-upnp-org:service:ContentDirectory:1</serviceType>
               <serviceId>urn:upnp-org:serviceId:ContentDirectory</serviceId>
               <SCPDURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/Upnp/upnp.org-ContentDirectory-1/service.xml</SCPDURL>
               <controlURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/upnp.org-ContentDirectory-1/control</controlURL>
               <eventSubURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/upnp.org-ContentDirectory-1/event</eventSubURL>
           </service>
           <service>
               <serviceType>urn:schemas-upnp-org:service:ConnectionManager:1</serviceType>
               <serviceId>urn:upnp-org:serviceId:ConnectionManager</serviceId>
               <SCPDURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/Upnp/upnp.org-ConnectionManager-1/service.xml</SCPDURL>
               <controlURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/upnp.org-ConnectionManager-1/control</controlURL>
               <eventSubURL>/ac3d630e37b5f11ff5cdd23c0f5a7400/upnp.org-ConnectionManager-1/event</eventSubURL>
           </service>
       </serviceList>
   </device>
</root>

Index maps

Large lists are difficult to navigate, especially on mobile devices. Mobile devices added the idea of an index map to improve this situation. The index map allows a users to jump to different sections in a large list, similar to what is possible with a scrollbar on desktops.

In order for a control point to generate an index map for any particular level in a ContentDirectory's hierarchy it first needs to download all the objects in the container, figure out if they are sorted and then calculate the index map. This means that a user will need to wait, perhaps minutes, before an index map is able to be presented on the UI.

The proposal is to allow the media server to calculate an index map and return it as part of the DIDL-Lite XML. Below shows some example DIDL-Lite with an index map included.

<DIDL-Lite xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/">
   <container id="db/ba37a2ac24efa676c8676aab71a6cdf074" parentID="0" restricted="true">
       <dc:title xmlns:dc="http://purl.org/dc/elements/1.1/">Worlds Apart [Deluxe Edition]</dc:title>
       <upnp:udn xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/">ac3d630e37b5f11ff5cdd23c0f5a7400</upnp:udn>
       <upnp:class xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/">object.container.album.musicAlbum</upnp:class>
       <upnp:artist xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/">...And You Will Know Us by the Trail of Dead</upnp:artist>
       <upnp:albumArtURI>http://10.2.1.170:4000/linn.co.uk.kazooserver/ms/artwork/37a2ac2?size=0</upnp:albumArtURI>
   </container>
   <desc nameSpace="openhome.org">
       <indexmap>
           <labels># A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +</labels>
           <indices>0 10 20 30 40 50 60 70 80 90 100 110 120 130 140 150 160 170 180 190 200 210 220 230 240 250 260 270</indices>
       </indexmap>
   </desc>
</DIDL-Lite>

The index map contains two, space separated, lists. These lists must contain the same number of elements. The example above is for a container who's contents are alphabetically sorted. But an index map could just as easily define a container who's contents are sorted by decade, e.g 1960 - 2015,

<desc nameSpace="openhome.org">
   <indexmap>
       <labels>60 70 80 90 00 10</labels>
       <indices>0 10 20 30 40 50</indices>
   </indexmap>
</desc>

Image Resolution

Control points running on different platforms have different memory limits and display technologies. This means that a control point on a PC might want to display artwork at a high resolution, while a control point on a PDA might want to display artwork at a much lower resolution.

Media servers often try to solve this problem using one of the following two methods:

1. A configurable parameter that scales all artwork to a user defined size
2. A profile system where a user can create profiles for each class of control point they have and configure a parameter that scales all artwork to a user defined size per profile

The first solution is highly problematic because it limits the resolution of artwork across the whole network. But a single network very often contains control points that can display high resolution images AND control points that can't.

The second solution is just architecturally poor, turning the relationship between a control point and a media server on its head. Why should the media server try to infer what a control point needs through configuration when the control point is perfectly capable of telling the media server its exact requirements in every single circumstance.

So, it is proposed that compliant media servers include a size element in their artwork uri's, where the size is the image's largest dimension. This allows a control point to ask for an image at a specified size.

Example

If the original artwork was 400x512, then a media server would provide the following albumArtURI: <uri>?size=512. If it is not possible for the media server to obtain the original resolution then the media server would provide the following albumArtURI: <uri>?size=0.

The presence of the size element tells the control point:

1. the media server implements the image scaling extension
2. the original size of the image.

Now the control point can request the image at any resolution by using <uri>?size=x, where x is the size it wants.

So, in this example, <uri>?size=1024 gets an 800x1024 image, and <uri>?size=200 gets a 156x200 image.

albumArtURI

The current specification only allows retrieval of artwork for a musicAlbum container through the property albumArtURI. When browsing a music library on a control point it quickly becomes clear that to implement a graphically rich control point the ContentDirectory service should provide a way to retrieve artwork for all of the content directory classes, not just musicAlbum containers.

There has become a somewhat defacto standard where just about all media server provide an albumArtURI property for a musicItem item as well as for a musicAlbum container, however this is still not good enough to implement a graphically rich control point.

It is proposed that an optional property is introduced to the object class called albumArtURI which may contain an attribute title, e.g. <albumArtURI title="Font Cover">http://Front Cover.jpg</albumArtURI>. The object class can contain zero or more albumArtURIs elements.

Low

Dynamic IP Addresses

At present all media servers return URIs that contain a reference to their IP address, e.g. http://172.20.1.1/music.flac etc. This means that if the media server's IP address were to change across reboots, then any control point or media renderer with URIs that referenced the media server before the reboot will become invalid.

It is proposed that a media server should always reference itself by host name and not by IP address in any XML that it sends to external devices, i.e. http://mynas/music.flac.

Disc Information

It is proposed that two new properties are added to the musicTrack item called OriginalDiscNumber and OriginalDiscCount

Replay Gain Information

It is proposed that four new properties are added to the musicTrack item called ReplayGainAlbum, ReplayGainAlbumPeak, ReplayGainTrack, and ReplayGainTrackPeak.

webURI

The current specification does not easily allow a control point to provide rich information about objects in the browse hierarchy.

It is proposed to add an optionally property to the object class called webURI which will contain a URI to a website that provides a rich collection of information about the object, e.g. for a musicArtist container it would provided a link to a website that provided information about the artist.