Davidd: /* Troubleshooting */

= Introduction =

Konfig provides advanced configuration of a Linn DS, notification and updating of a Linn DS to the latest firmware, restoring Linn DS settings back to factory defaults and manual updating of a Linn DS firmware.

Konfig can also be run from a web-browser with all functions except the software update. Get the IP address of the Linn DS/DSM from the front panel using either the: 
:[http://docs.linn.co.uk/wiki/index.php/REM_020 REM 020 Remote control] by pressing and holding the # button or with the 
:[http://docs.linn.co.uk/wiki/index.php/DS_%26_REM_019 REM 019 Remote control] by pressing DVD then the INFO buttons.

When you are in DS web page select Control, this will give you the same options (except Software update) as below

= Installation =
== System Requirements ==
=== Windows ===
* Windows Vista or later version of Windows
* IE9 or later
* 32 or 64-bit hardware
* Internet connection when using Exakt Systems

=== Mac ===
* Mac OS X Snow Leopard 10.6.8 or later
* 32 or 64-bit hardware
* Internet connection when using Exakt Systems

== Installing ==
=== Windows ===
* Download the installer from the [http://www.linn.co.uk/support/software#konfig download] page
* Double click the downloaded .exe file
* Follow the on screen instructions in the installer program

=== Mac ===
* Download the .pkg file from the [http://www.linn.co.uk/support/software#konfig download] page
* Double click the downloaded .pkg file
* Follow the on screen instructions in the installer program

== Uninstalling ==
=== Windows ===
* Open the Windows Control Panel and double click "Programs and Features"
* Select "Konfig" in the list of programs and click the "Uninstall" button
* Follow the on screen instructions in the uninstall window

=== Mac ===
* Using Finder drag the Konfig icon from Applications/Konfig to the waste bin

== Updating ==

Konfig for Mac and Windows will automatically check for new software updates. Checking for available updates can also be performed manually as described below. Alternatively, Konfig can be updated by manually downloading the installation packages from the [http://www.linn.co.uk/support/software#konfig download] page and installing them using the method described in the [[#Installing| Installing]] section above.

= Operation =

Konfig has four main views, [[#Configuration| Configuration]], [[#Updates| Updates]], [[#Diagnostics| Diagnostics]], and [[#Advanced| Advanced]]

[[File:Header.png|740px|Header]]

== Configuration ==

[[File:Configuration.png|740px|Configuration Page]]

Click the '''Show Devices''' button to slide a list of available devices in from the left. Selecting a device from the list will show it's configuration page in the right hand pane.

A Linn device's configuration page will only show in the right hand pane if the device is running firmware version Davaar 9 (4.9.4) or later. If your Linn device is running firmware version less that Davaar 9 (4.9.4), Konfig will provide a link to allow you to open the configuration page in your default browser.





=== Linn Preamplifier, Volume, Delay modes, Songcast, Net-Aux and HDMI settings ===
[[file:771px-DS_Name_10.jpg|300px|center]]

== DS Volume control & Proxy RS232 control ==
There are two way to control the Volume on a Linn DS system:

* '''Internal Volume''' control that will directly control the analogue audio level coming out of the Linn DS. This is good for directly connecting to a Power amplifier on your speakers.
[[file:635px-Internal_Vol_ctrl_10.jpg|400px|center]]

===Proxy RS232 control ===
* Or use an external preamplifier, this means that the Linn DS will always output Line-level audio.
:If you have a Linn Pre-amplifier this can be set to be controlled by the Kinsky control software.

[[file:771px-DS_Name_10.jpg|300px|right]]
: ''1.'' Wire up the Linn DS and Linn preamplifiers/CD players '''RS232''' and audio connections as shown [http://docs.linn.co.uk/wiki/index.php/Systems Here] '''(Ignore this if you are using an Akurate Kontrol/1)'''
:''2.'' Select the Linn DS and go into the Linn DS '''Device'' screen
:''3.'' Take note of the text in '''Name''' field
:''4.'' Go into the Linn DS '''RS232 connections'' screen
:''5.'' Under Linn Preamplifier/CD player select the Linn product and Linn DS com port it is wired to.
:''6.'' Press the Circle arrow to Reboot the Linn DS

[[file:824px-DS_Ktrl_Name_10.jpg|300px|right|thumb|DS Name in Kontrol - click to enlarge]]
:''7.'' Click on "Show Devices" and
:''8.'' Select the Linn Kontrol (preamplifier) and go into the Linn Kontrol '''Sources''' screen
:''9.'' Select the Input that the Linn DS is connected to and enter the '''Name''' of the Linn DS that was take from the Linn DS - Devices screen Name field (taken in point 3)
:''10.'' If a Linn CD player was also enabled enter the '''Name''' of the Linn CD device that was take from the Linn CD player - Devices screen

===Ethernet controlled Linn Pre-Amplifier (Akurate Kontrol/1)===
:''1.'' Select the Linn DS and go into the Linn DS '''Device'' screen
:''2.'' Take note of the text in '''Name''' and the '''Room''' fields
:''3.'' Click on "Show Devices" and
:''4.'' Select the Linn Kontrol (preamplifier) and go into the Linn Kontrol '''Sources''' screen
:''5.'' Change the Akurate Kontrol '''Device - Room''' name matches the Linn DS Room field taken in point 2.
:''6.'' Select the Input that the Linn DS is connected to and enter the '''Name''' of the Linn DS that was take from the Linn DS Name field taken in point 2.

I would suggest a "cut and paste" of the Room field and DS name field as this is case-senative ("lounge" is not the same as "Lounge")

==Sources==

===Name===
This is the source name that will appear in the DS user control software (Kinksy, Kazoo etc) 

===Visible===
This allows you to hide sources.
If you set Visible-NO, then this input is hidden from selection in the Front panel and the user control software selection list. 
This does not mean that you have disabled the input, it only means that you cannot see it.

===Delay Mode===
[[file:584px-DSM_delays.jpg|400px|right|thumb|Source delays - click to enlarge]]

There are 3 different delays modes with the Linn DSI/DSM/Exakt for external sources (Analogue, Toslink, SPDIF & HDMI)
:'''Direct''' - This will feed the audio in real-time to the local Linn DSI/DSM, but the audio fed to the other Linn DS products will be delayed by 150mS. If this is setup and the other Linn DS products are fairly close, the music will sound like an echo 
:'''Fixed''' - This will delay the audio to ALL Linn DS/DSI/DSM products (including Exakt products) to keep the audio in perfect sync. This common delay is 150mS 
:'''Variable''' - This is a lipsync delay from 20ms-1999ms on this local DS. However the Songcast listening rooms will ONLY be in perfect sync for Lip-sync delays of =>150mS.
:If the lip-sync is less than 150ms, the listening rooms will always have a 150mS from original source, this means that the audio will be out of sync by 150ms minus the lip sync value. (eg Lipsync delay 90mS, then the delay from the sender DS audio to the listening room DS is 60mS)
:Lipsync delay time is variable from from 20mS-2S either from the Konfig app or the IR handset. 
For operation detail check [[DSM Audio Latencies Explained]] 

===Input level, Unity Gain, Volume offset===
[[file:808px-Sources-setup.jpg|404px|right|thumb|Source settings - click to enlarge]]
:'''Input level (Vrms)''' - This is to allow you to change that input profile for the specific sources. This may be due to input adapters, such as RCA-XLR, XLR-RCA etc, being used giving different output levels.

:'''Transformer''' - This is only on some of the Linn DSM's and enables the input to electrically isolated via an audio transformer on this input. This should '''NOT''' be enabled if you are connecting to another product with an audio transformer on it output, such as a '''URIKA''' or '''Klimax DS/1'''.

:'''Unity Gain''' -This will turn off the DSM volume control whenever that input/source is selected. This is a pass-through state

:'''Volume Offset''' - this is an trim adjustment. Some audio sources have a higher or lower output than normal. This trim/offset will allow you to you to switch between source and keep the same DSM volume.

==Songcast / Net Aux inputs==
[[file:669px-Net_Aux_10.jpg|300px|right|thumb|Sources - click to enlarge]]
* To show the Linn DS sources you need to make these visible. This allows you to hide source that you are not going to use, such as UpnpAV that is only used with some media controllers.
* '''Songcast''' listen to Music playing on your [http://oss.linn.co.uk/trac/wiki/SongcastWindowsDavaarManual#KnownIssues PC SONGCAST] software or listen to another DS,
** '''Visible'''
*** Set Visible to '''NO''' will hide this on the inputs listing within the control software Kinsky.
*** Set Visible to '''YES''' will make this a visible source in Kinsky
 
* '''Net-Aux''' To have 3rd party Media streamers to play on your Linn DS
** '''Visible'''
*** Set Visible to '''NO''' will hide this on the inputs listing within the control software Kinsky.
*** Set Visible to '''YES''' will make this a visible source in Kinsky
** '''Auto Select'''
*** Set Auto Select to '''ON''' will get have the Linn DS to automatically switch to the Net-Aux input on receipt of a third party media stream.
*** Set Auto Select to '''OFF''' if you do '''NOT''' want the Linn DS to automatically switch to the Net-Aux input on receipt of a third party media stream

== HDMI ==
[[file:764px-HDMI_Konfig_10.jpg|400px|right|thumb| HDMI - click to enlarge]]
* The HDMI connection can be shutdown whilst the product is in Sleep mode
* Usage of the Audio mode etc are explained [http://docs.linn.co.uk/wiki/index.php/HDMI_Setup#Audio_Mode here]
 

 

== Songcast Sender ==

[[File:809px-Songcast_sender.jpg‎| 400px | centre]]

[[Songcast_Sender|<big>Click here for Songcast Sender page</big>]] 

== Tidal ==
[[file:795px-Konfig-Tidal.jpg‎ |298px | centre]]

This allows you to control the quality of the next Tidal radio stream tracks.
This tell tell Tidal that the music stream will now be in the Low, High or top level - FLAC quality audio. That is, the next Tidal track will be played in the newly set quality of audio.

The change in Tidal audio quality will also control the amount of broadband capacity you are using.
* "Low (AAC 96kbps)" will use the least amount of broadband
* "High (AAC 320kbps)" will use a resonable amount of broadband
* "FLAC (lossless)" will use the most amount of broadband.

== Space Optimisation and Space Optimisation+ ==

'''An Internet connection is required when using Exakt Systems'''

If you have selected an Exakt compatible device, you will see two new configuration tabs.

[[File:KonfigExaktTabs.png|740px|Exakt Tabs]]

'''Exakt''' allows you to assign an audio channel (i.e. Left or Right) to an Exakt speaker.

'''Space Optimisation+''' provides a listener focused way of applying room optimisation.

For help with this, please see the [[Exakt Optimsation]] article.

== Updates ==

[[File:Updates.png|740px|Updates Page]]

The Updates tab indicates the number of Linn devices that currently have a newer software version available, as shown in the screenshot above.

Each device that has an update available will be in the list of updatable devices. Each device has information about the update version available as well as a link to the release notes.

To update a device click the 'Update' button. If you have more than one devices to update you can click the 'Update All' button to update all the devices at the same time.

If you updated a device to beta software and then decide you want to go back to the latest stable release you just need to un-click the [[#Participate_in_beta_program_2| Participate in beta program]] option, return to the Updates page and update the desired device.

== Diagnostics ==

[[File:Diagnostics.png|740px|Diagnostics Page]]

The Diagnostics tab indicates the number of Linn devices that currently have crash data available to send to Linn, as shown in the screenshot above.

To send the crash data from a device to Linn click the 'Send' button. If you have more than one device with crash data you can click the 'Send All' button.

If you do not wish to send the crash data for a device you can click the 'Ignore' button and you will not be notified about crash data until the device crashes again. If you want to ignore crash data from all the listed devices you can click the 'Ignore All' button.

'''NOTE: No personal information is sent to Linn as a result of sending crash data to Linn.'''

== Advanced ==

[[File:Advanced.png|740px|Advanced Page]]

The Advanced page allows a user to restore a Linn device back to the original factory settings. It also allows a user to manually updating a Linn device's firmware to a locally stored firmware bundle.

=== Restore Factory Settings ===

Click the 'Restore' button associated with the desired Linn device to start the process of restoring the Linn device to its factory default settings.

=== Updating Linn Device Firmware ===

First download the desired firmware from [http://products.linn.co.uk/VersionInfo/Downloads/Releases/ here].

[[File:992px-Advanced-update.jpg|740px|Advanced Page]]

Next enter the firmware's downloaded location into the text field associated with the desired Linn device, e.g. On Windows, C:\Users\<username>\Desktop\KlimaxDsm_4.7.5.zip and on Mac, /Users/<username>/Desktop/S08500116.

'''NOTE: On Mac the downloaded firmware is automatically unzipped by the OS and so the location is a directory unlike on Windows where the location is the downloaded zip file.'''

After entering the firmware's location click the 'Update' button to start the process of updating the Linn device's firmware.

=== Device Recovery ===

This option should only be used if your are having problems updating your Linn DS through the standard methods, i.e. automatically through the Update page or manually as described in the previous section.

After a 'Device Recovery' update has been performed any Linn device settings changed by the user will be set back to factory defaults.

== Settings ==

[[File:Settings.png|740px|Settings Page]]

=== Application Updates ===
==== Automatic update checks ====
Whether Konfig automatically checks for newer versions of Konfig.
==== Participate in beta program ====
Whether Konfig automatically checks for beta releases of Konfig.
==== Check For Updates ====
Force Konfig to check for newer versions of Konfig, taking into account whether 'Participate in beta program' is checked.

=== Device Updates ===
==== Participate in beta program ====
Whether Konfig automatically checks for beta releases of firmware for available Linn devices.

=== Diagnostics ===
==== Automatically send DS crash information to Linn ====
Whether to automatically send Linn device crash information to Linn for analysis (recommended to be checked).

'''NOTE: No personal information is sent to Linn as a result of this option being checked.'''

=== Privacy ===
==== Send anonymous usage data to Linn ====

Whether to allow Konfig to send anonymous usage data to Linn for analysis (recommended to be checked).

'''NOTE: No personal information is sent to Linn as a result of this option being checked.'''

=== Network ===

Which network to use to locate Linn DSs.

= Troubleshooting =
=== Konfig cannot see any of my DS ===

Check within Settings that the Network connection is correct. 
In older versions of Konfig you only had to select the network card, (wired, wireless etc). Now Konfig asks you for the Network IP range, this is to simplify the connection as this can use BOTH the wired and wireless connections if they are connected to the same Network. 
If your PC/MAC has changed Ethernet networks (for installation, Home-Work etc), the Konfig may be setup for a different address range and not see any DS products. So if your Konfig cannot see your Linn DS products, go into Settings and check that the correct Network address has been selected (click on the drop down box to see what is available)

Some Anti-virus Suites also have additional Firewalls that will block a lot of communications. If Konfig used to work and now does not find any products then check if your Anti-Virus suite has recently had a major update. This update may require the Konfig for have "firewall exceptions".

=== After the software update the Linn DS is not working correctly or losing settings ===

This can be due to a configuration conflict with the last software version:
* From Konfig, under the Advanced page, select your DS
* Select the '''RESTORE''' button, this will reset the Linn DS back its factory defaults
* Reconfigure your DS to your preferred setting. (As this is configuration is performed in the same software version this should remove any previous conflicts).

=== Where is the manual for the previous releases of Konfig? ===

The old Konfig manual has moved to [[Konfig_Manual_Old| here]]
 
=== Konfig just doesn't run on my Mac. The icon bounces in the dock and then goes away.===
* Open Finder
* From the Menu bar at the top select 'Go' the 'Go to Folder'
* Type in ~/Library/Konfig and click Go
* Select 'Options.xml' file and delete

=== What if I have problems updating? ===

'''Don't panic, the update process is safe, so you should always be able to recover your device'''

* Restart Konfig. If your device reports the expected version, the update was successful and you are done
* If your device does not report the expected version, retry the update process (if you were updating over wireless, try updating over a wired connection)
* If this fails, power cycle your device and try again
* If this fails, download the latest version of software from [http://products.linn.co.uk/VersionInfo/Downloads/Releases/ here]
* Save this zip file to a known location on your hard drive, preferably in C:\
* Open Linn Konfig
* Go to the ‘Advanced’ tab
* Press the fallback button on the DS
* The DS should appear in Konfig with a lightning symbol beside it
* Enter the full location of the .zip file that you saved in the text box for the DS (e.g. “C:\MajikDs_4.12.357.zip”)
* Select the ‘Device Recovery’ option below the text box
* Click on ‘Update’
* The unit should update successfully
* If the update fails then contact your retailer for further support
'''NOTE: If there is no text box to enter the file location, ensure that you have the latest version of Internet Explorer installed. If there is still no text box, ensure that the security settings for Local Intranet are set to medium-low.

=== What if I want to revert to older versions of firmware? ===

We only support the latest firmware release and do not recommend running old firmware on any Linn DS.

We only archive released versions of firmware.

* Put your device into fallback mode from the button on the back of the device
* Download and install the compatible version of Konfig from the release download site (i.e. Cara Konfig if you are reverting to Cara firmware, Davaar for Davaar, etc)
* Download the version of firmware (zip file) you wish to use from the release download site (only firmware for your device model will work)
* From Konfig, under the Advanced page, enter the downloaded firmware location for your Linn device

Keep in mind, only compatible control points will work with your device (i.e. Cara with Cara, Davaar with Davaar, etc)

=== What if I have problems updating my Exakt devices? ===

'''Don't panic, the update process is safe, so you will always be able to recover your device'''

* Normally your Exakt devices will update seemlessly as part of the standard DS/DSM update process.
* Restart Konfig. If your Exakt device appears under Exakt Setup and there is no Update button, the update was successful and you are done.
* Restart Konfig. If your Exakt device appears under Exakt Setup and there IS an Update button, the update was unsuccessful, click Update to try again.
* If this fails, power cycle your Exakt device and the connected DS/DSM device and try again.
* If this fails, follow the device recovery process below:
* Put both your Exakt device and connected DS/DSM into fallback (from the buttons on the back of the devices).
* Find the connected DS/DSM in the Update tab and click Update.
* If you have an integrated Exakt speaker, this will fully update your Exakt device as well.
* If you have an Exakt tunebox, you will be prompted at the end of the update to enter your speaker serial number from the Exakt Setup tab to complete the update.

If you have difficulty programming an Exakt speaker or Tunebox, but the Exakt DSM is OK (require Konfig 4.12.2 onwards)

* Put the speaker or Tunebox into FALLBACK
:* Make sure the Exakt DSM is Out of Standby
:* Press the Fallback button on the Exakt Speaker/Exakt Tunboks
* In Konfig in the DS - "Exakt setup" tab, this speaker should now show up with a RESTORE button, press the RESTORE button and wait for this to complete. If this is a Exakt Tunebox then enter the serial number of the speaker then do the UPDATE button
* Complete

=== Why does Konfig not show Space Optimisation for my DS? ===

Space Optimisation for DS was introduced in Davaar 25.

To enable Space Optimisation on your DS you will need to install Davaar 25 or later firmware on your DS.

== Known Issues ==
If you start Konfig and only get a white screen or only shows toolbar with no "Show devices" button:
:1. Go into Internet Explorer - ''Tools'' - ''Internet options''
:2. Select Security
::a) If '''"Internet"''' Security is High, reduce this to Medium High
::b) now select '''"Local Internet"''' icon
::c) If '''"Local Internet"''' Security is High, reduce this to Medium High
:3. OK out of this & restart Konfig

If this does not cure the issue then
:1. Run Konfig
:2. Open Internet Explorer
:3. Type in [http://localhost:5000 http://localhost:5000] into the IE address bar
::(If Songbox is running then type [http://localhost:5001 http://localhost:5001]
:4. What appears in the window?
:5. If Internet Explorer shown the Konfig windows OK then retry steps 3/4/5 using Chrome or another web browser.

;After the update some PC/MAC cannot find any Linn DS/DSM products:
Do the following procedure:
:1. If you are using Norton Anti-virus, make sure that the new Konfig is added an exception
:2. Restart your PC/MAC and retry Konfig 10
::a) Press the '''SHOW DEVICES''' button
::b) If a number appears beside the Updates tab (top of Konfig screen,
:::i) Press the Updates tab and press '''UPDATE''' beside your Linn DS/DSM name
:::ii) Wait until he update is finished and Press the '''SHOW DEVICES''' button. Your DS should now appear.
If your Linn DS/DSM is not listed
:3. Press the '''ADVANCED''' tab and see if your Linn DS/DSM is listed here
 
;If neither of these two options work:Follow the [http://docs.linn.co.uk/wiki/index.php/Troubleshooting#Konfig_diagnostics Konfig 10 diagnostics]

;If doing a Advanced download Konfig reports "cannot find directory..";
:Check that
:1. You can typed the correct file location and file name in to the download field
:2. Konfig 4.10.5-4.11.2 needs internet access before doing the file update. Make sure that you have an Internet link BEFORE opening Konfig

Konfig Manual

2015-03-17T11:23:49Z

Davidd: /* Exakt Optimisation */

= Introduction =

Konfig provides advanced configuration of a Linn DS, notification and updating of a Linn DS to the latest firmware, restoring Linn DS settings back to factory defaults and manual updating of a Linn DS firmware.

Konfig can also be run from a web-browser with all functions except the software update. Get the IP address of the Linn DS/DSM from the front panel using either the: 
:[http://docs.linn.co.uk/wiki/index.php/REM_020 REM 020 Remote control] by pressing and holding the # button or with the 
:[http://docs.linn.co.uk/wiki/index.php/DS_%26_REM_019 REM 019 Remote control] by pressing DVD then the INFO buttons.

When you are in DS web page select Control, this will give you the same options (except Software update) as below

= Installation =
== System Requirements ==
=== Windows ===
* Windows Vista or later version of Windows
* IE9 or later
* 32 or 64-bit hardware
* Internet connection when using Exakt Systems

=== Mac ===
* Mac OS X Snow Leopard 10.6.8 or later
* 32 or 64-bit hardware
* Internet connection when using Exakt Systems

== Installing ==
=== Windows ===
* Download the installer from the [http://www.linn.co.uk/support/software#konfig download] page
* Double click the downloaded .exe file
* Follow the on screen instructions in the installer program

=== Mac ===
* Download the .pkg file from the [http://www.linn.co.uk/support/software#konfig download] page
* Double click the downloaded .pkg file
* Follow the on screen instructions in the installer program

== Uninstalling ==
=== Windows ===
* Open the Windows Control Panel and double click "Programs and Features"
* Select "Konfig" in the list of programs and click the "Uninstall" button
* Follow the on screen instructions in the uninstall window

=== Mac ===
* Using Finder drag the Konfig icon from Applications/Konfig to the waste bin

== Updating ==

Konfig for Mac and Windows will automatically check for new software updates. Checking for available updates can also be performed manually as described below. Alternatively, Konfig can be updated by manually downloading the installation packages from the [http://www.linn.co.uk/support/software#konfig download] page and installing them using the method described in the [[#Installing| Installing]] section above.

= Operation =

Konfig has four main views, [[#Configuration| Configuration]], [[#Updates| Updates]], [[#Diagnostics| Diagnostics]], and [[#Advanced| Advanced]]

[[File:Header.png|740px|Header]]

== Configuration ==

[[File:Configuration.png|740px|Configuration Page]]

Click the '''Show Devices''' button to slide a list of available devices in from the left. Selecting a device from the list will show it's configuration page in the right hand pane.

A Linn device's configuration page will only show in the right hand pane if the device is running firmware version Davaar 9 (4.9.4) or later. If your Linn device is running firmware version less that Davaar 9 (4.9.4), Konfig will provide a link to allow you to open the configuration page in your default browser.





=== Linn Preamplifier, Volume, Delay modes, Songcast, Net-Aux and HDMI settings ===
[[file:771px-DS_Name_10.jpg|300px|center]]

== DS Volume control & Proxy RS232 control ==
There are two way to control the Volume on a Linn DS system:

* '''Internal Volume''' control that will directly control the analogue audio level coming out of the Linn DS. This is good for directly connecting to a Power amplifier on your speakers.
[[file:635px-Internal_Vol_ctrl_10.jpg|400px|center]]

===Proxy RS232 control ===
* Or use an external preamplifier, this means that the Linn DS will always output Line-level audio.
:If you have a Linn Pre-amplifier this can be set to be controlled by the Kinsky control software.

[[file:771px-DS_Name_10.jpg|300px|right]]
: ''1.'' Wire up the Linn DS and Linn preamplifiers/CD players '''RS232''' and audio connections as shown [http://docs.linn.co.uk/wiki/index.php/Systems Here] '''(Ignore this if you are using an Akurate Kontrol/1)'''
:''2.'' Select the Linn DS and go into the Linn DS '''Device'' screen
:''3.'' Take note of the text in '''Name''' field
:''4.'' Go into the Linn DS '''RS232 connections'' screen
:''5.'' Under Linn Preamplifier/CD player select the Linn product and Linn DS com port it is wired to.
:''6.'' Press the Circle arrow to Reboot the Linn DS

[[file:824px-DS_Ktrl_Name_10.jpg|300px|right|thumb|DS Name in Kontrol - click to enlarge]]
:''7.'' Click on "Show Devices" and
:''8.'' Select the Linn Kontrol (preamplifier) and go into the Linn Kontrol '''Sources''' screen
:''9.'' Select the Input that the Linn DS is connected to and enter the '''Name''' of the Linn DS that was take from the Linn DS - Devices screen Name field (taken in point 3)
:''10.'' If a Linn CD player was also enabled enter the '''Name''' of the Linn CD device that was take from the Linn CD player - Devices screen

===Ethernet controlled Linn Pre-Amplifier (Akurate Kontrol/1)===
:''1.'' Select the Linn DS and go into the Linn DS '''Device'' screen
:''2.'' Take note of the text in '''Name''' and the '''Room''' fields
:''3.'' Click on "Show Devices" and
:''4.'' Select the Linn Kontrol (preamplifier) and go into the Linn Kontrol '''Sources''' screen
:''5.'' Change the Akurate Kontrol '''Device - Room''' name matches the Linn DS Room field taken in point 2.
:''6.'' Select the Input that the Linn DS is connected to and enter the '''Name''' of the Linn DS that was take from the Linn DS Name field taken in point 2.

I would suggest a "cut and paste" of the Room field and DS name field as this is case-senative ("lounge" is not the same as "Lounge")

==Sources==

===Name===
This is the source name that will appear in the DS user control software (Kinksy, Kazoo etc) 

===Visible===
This allows you to hide sources.
If you set Visible-NO, then this input is hidden from selection in the Front panel and the user control software selection list. 
This does not mean that you have disabled the input, it only means that you cannot see it.

===Delay Mode===
[[file:584px-DSM_delays.jpg|400px|right|thumb|Source delays - click to enlarge]]

There are 3 different delays modes with the Linn DSI/DSM/Exakt for external sources (Analogue, Toslink, SPDIF & HDMI)
:'''Direct''' - This will feed the audio in real-time to the local Linn DSI/DSM, but the audio fed to the other Linn DS products will be delayed by 150mS. If this is setup and the other Linn DS products are fairly close, the music will sound like an echo 
:'''Fixed''' - This will delay the audio to ALL Linn DS/DSI/DSM products (including Exakt products) to keep the audio in perfect sync. This common delay is 150mS 
:'''Variable''' - This is a lipsync delay from 20ms-1999ms on this local DS. However the Songcast listening rooms will ONLY be in perfect sync for Lip-sync delays of =>150mS.
:If the lip-sync is less than 150ms, the listening rooms will always have a 150mS from original source, this means that the audio will be out of sync by 150ms minus the lip sync value. (eg Lipsync delay 90mS, then the delay from the sender DS audio to the listening room DS is 60mS)
:Lipsync delay time is variable from from 20mS-2S either from the Konfig app or the IR handset. 
For operation detail check [[DSM Audio Latencies Explained]] 

===Input level, Unity Gain, Volume offset===
[[file:808px-Sources-setup.jpg|404px|right|thumb|Source settings - click to enlarge]]
:'''Input level (Vrms)''' - This is to allow you to change that input profile for the specific sources. This may be due to input adapters, such as RCA-XLR, XLR-RCA etc, being used giving different output levels.

:'''Transformer''' - This is only on some of the Linn DSM's and enables the input to electrically isolated via an audio transformer on this input. This should '''NOT''' be enabled if you are connecting to another product with an audio transformer on it output, such as a '''URIKA''' or '''Klimax DS/1'''.

:'''Unity Gain''' -This will turn off the DSM volume control whenever that input/source is selected. This is a pass-through state

:'''Volume Offset''' - this is an trim adjustment. Some audio sources have a higher or lower output than normal. This trim/offset will allow you to you to switch between source and keep the same DSM volume.

==Songcast / Net Aux inputs==
[[file:669px-Net_Aux_10.jpg|300px|right|thumb|Sources - click to enlarge]]
* To show the Linn DS sources you need to make these visible. This allows you to hide source that you are not going to use, such as UpnpAV that is only used with some media controllers.
* '''Songcast''' listen to Music playing on your [http://oss.linn.co.uk/trac/wiki/SongcastWindowsDavaarManual#KnownIssues PC SONGCAST] software or listen to another DS,
** '''Visible'''
*** Set Visible to '''NO''' will hide this on the inputs listing within the control software Kinsky.
*** Set Visible to '''YES''' will make this a visible source in Kinsky
 
* '''Net-Aux''' To have 3rd party Media streamers to play on your Linn DS
** '''Visible'''
*** Set Visible to '''NO''' will hide this on the inputs listing within the control software Kinsky.
*** Set Visible to '''YES''' will make this a visible source in Kinsky
** '''Auto Select'''
*** Set Auto Select to '''ON''' will get have the Linn DS to automatically switch to the Net-Aux input on receipt of a third party media stream.
*** Set Auto Select to '''OFF''' if you do '''NOT''' want the Linn DS to automatically switch to the Net-Aux input on receipt of a third party media stream

== HDMI ==
[[file:764px-HDMI_Konfig_10.jpg|400px|right|thumb| HDMI - click to enlarge]]
* The HDMI connection can be shutdown whilst the product is in Sleep mode
* Usage of the Audio mode etc are explained [http://docs.linn.co.uk/wiki/index.php/HDMI_Setup#Audio_Mode here]
 

 

== Songcast Sender ==

[[File:809px-Songcast_sender.jpg‎| 400px | centre]]

[[Songcast_Sender|<big>Click here for Songcast Sender page</big>]] 

== Tidal ==
[[file:795px-Konfig-Tidal.jpg‎ |298px | centre]]

This allows you to control the quality of the next Tidal radio stream tracks.
This tell tell Tidal that the music stream will now be in the Low, High or top level - FLAC quality audio. That is, the next Tidal track will be played in the newly set quality of audio.

The change in Tidal audio quality will also control the amount of broadband capacity you are using.
* "Low (AAC 96kbps)" will use the least amount of broadband
* "High (AAC 320kbps)" will use a resonable amount of broadband
* "FLAC (lossless)" will use the most amount of broadband.

== Space Optimisation and Space Optimisation+ ==

'''An Internet connection is required when using Exakt Systems'''

If you have selected an Exakt compatible device, you will see two new configuration tabs.

[[File:KonfigExaktTabs.png|740px|Exakt Tabs]]

'''Exakt''' allows you to assign an audio channel (i.e. Left or Right) to an Exakt speaker.

'''Space Optimisation+''' provides a listener focused way of applying room optimisation.

For help with this, please see the [[Exakt Optimsation]] article.

== Updates ==

[[File:Updates.png|740px|Updates Page]]

The Updates tab indicates the number of Linn devices that currently have a newer software version available, as shown in the screenshot above.

Each device that has an update available will be in the list of updatable devices. Each device has information about the update version available as well as a link to the release notes.

To update a device click the 'Update' button. If you have more than one devices to update you can click the 'Update All' button to update all the devices at the same time.

If you updated a device to beta software and then decide you want to go back to the latest stable release you just need to un-click the [[#Participate_in_beta_program_2| Participate in beta program]] option, return to the Updates page and update the desired device.

== Diagnostics ==

[[File:Diagnostics.png|740px|Diagnostics Page]]

The Diagnostics tab indicates the number of Linn devices that currently have crash data available to send to Linn, as shown in the screenshot above.

To send the crash data from a device to Linn click the 'Send' button. If you have more than one device with crash data you can click the 'Send All' button.

If you do not wish to send the crash data for a device you can click the 'Ignore' button and you will not be notified about crash data until the device crashes again. If you want to ignore crash data from all the listed devices you can click the 'Ignore All' button.

'''NOTE: No personal information is sent to Linn as a result of sending crash data to Linn.'''

== Advanced ==

[[File:Advanced.png|740px|Advanced Page]]

The Advanced page allows a user to restore a Linn device back to the original factory settings. It also allows a user to manually updating a Linn device's firmware to a locally stored firmware bundle.

=== Restore Factory Settings ===

Click the 'Restore' button associated with the desired Linn device to start the process of restoring the Linn device to its factory default settings.

=== Updating Linn Device Firmware ===

First download the desired firmware from [http://products.linn.co.uk/VersionInfo/Downloads/Releases/ here].

[[File:992px-Advanced-update.jpg|740px|Advanced Page]]

Next enter the firmware's downloaded location into the text field associated with the desired Linn device, e.g. On Windows, C:\Users\<username>\Desktop\KlimaxDsm_4.7.5.zip and on Mac, /Users/<username>/Desktop/S08500116.

'''NOTE: On Mac the downloaded firmware is automatically unzipped by the OS and so the location is a directory unlike on Windows where the location is the downloaded zip file.'''

After entering the firmware's location click the 'Update' button to start the process of updating the Linn device's firmware.

=== Device Recovery ===

This option should only be used if your are having problems updating your Linn DS through the standard methods, i.e. automatically through the Update page or manually as described in the previous section.

After a 'Device Recovery' update has been performed any Linn device settings changed by the user will be set back to factory defaults.

== Settings ==

[[File:Settings.png|740px|Settings Page]]

=== Application Updates ===
==== Automatic update checks ====
Whether Konfig automatically checks for newer versions of Konfig.
==== Participate in beta program ====
Whether Konfig automatically checks for beta releases of Konfig.
==== Check For Updates ====
Force Konfig to check for newer versions of Konfig, taking into account whether 'Participate in beta program' is checked.

=== Device Updates ===
==== Participate in beta program ====
Whether Konfig automatically checks for beta releases of firmware for available Linn devices.

=== Diagnostics ===
==== Automatically send DS crash information to Linn ====
Whether to automatically send Linn device crash information to Linn for analysis (recommended to be checked).

'''NOTE: No personal information is sent to Linn as a result of this option being checked.'''

=== Privacy ===
==== Send anonymous usage data to Linn ====

Whether to allow Konfig to send anonymous usage data to Linn for analysis (recommended to be checked).

'''NOTE: No personal information is sent to Linn as a result of this option being checked.'''

=== Network ===

Which network to use to locate Linn DSs.

= Troubleshooting =
=== Konfig cannot see any of my DS ===

Check within Settings that the Network connection is correct. 
In older versions of Konfig you only had to select the network card, (wired, wireless etc). Now Konfig asks you for the Network IP range, this is to simplify the connection as this can use BOTH the wired and wireless connections if they are connected to the same Network. 
If your PC/MAC has changed Ethernet networks (for installation, Home-Work etc), the Konfig may be setup for a different address range and not see any DS products. So if your Konfig cannot see your Linn DS products, go into Settings and check that the correct Network address has been selected (click on the drop down box to see what is available)

Some Anti-virus Suites also have additional Firewalls that will block a lot of communications. If Konfig used to work and now does not find any products then check if your Anti-Virus suite has recently had a major update. This update may require the Konfig for have "firewall exceptions".

=== After the software update the Linn DS is not working correctly or losing settings ===

This can be due to a configuration conflict with the last software version:
* From Konfig, under the Advanced page, select your DS
* Select the '''RESTORE''' button, this will reset the Linn DS back its factory defaults
* Reconfigure your DS to your preferred setting. (As this is configuration is performed in the same software version this should remove any previous conflicts).

=== Where is the manual for the previous releases of Konfig? ===

The old Konfig manual has moved to [[Konfig_Manual_Old| here]]
 
=== Konfig just doesn't run on my Mac. The icon bounces in the dock and then goes away.===
* Open Finder
* From the Menu bar at the top select 'Go' the 'Go to Folder'
* Type in ~/Library/Konfig and click Go
* Select 'Options.xml' file and delete

=== What if I have problems updating? ===

'''Don't panic, the update process is safe, so you should always be able to recover your device'''

* Restart Konfig. If your device reports the expected version, the update was successful and you are done
* If your device does not report the expected version, retry the update process (if you were updating over wireless, try updating over a wired connection)
* If this fails, power cycle your device and try again
* If this fails, download the latest version of software from [http://products.linn.co.uk/VersionInfo/Downloads/Releases/ here]
* Save this zip file to a known location on your hard drive, preferably in C:\
* Open Linn Konfig
* Go to the ‘Advanced’ tab
* Press the fallback button on the DS
* The DS should appear in Konfig with a lightning symbol beside it
* Enter the full location of the .zip file that you saved in the text box for the DS (e.g. “C:\MajikDs_4.12.357.zip”)
* Select the ‘Device Recovery’ option below the text box
* Click on ‘Update’
* The unit should update successfully
* If the update fails then contact your retailer for further support
'''NOTE: If there is no text box to enter the file location, ensure that you have the latest version of Internet Explorer installed. If there is still no text box, ensure that the security settings for Local Intranet are set to medium-low.

=== What if I want to revert to older versions of firmware? ===

We only support the latest firmware release and do not recommend running old firmware on any Linn DS.

We only archive released versions of firmware.

* Put your device into fallback mode from the button on the back of the device
* Download and install the compatible version of Konfig from the release download site (i.e. Cara Konfig if you are reverting to Cara firmware, Davaar for Davaar, etc)
* Download the version of firmware (zip file) you wish to use from the release download site (only firmware for your device model will work)
* From Konfig, under the Advanced page, enter the downloaded firmware location for your Linn device

Keep in mind, only compatible control points will work with your device (i.e. Cara with Cara, Davaar with Davaar, etc)

=== What if I have problems updating my Exakt devices? ===

'''Don't panic, the update process is safe, so you will always be able to recover your device'''

* Normally your Exakt devices will update seemlessly as part of the standard DS/DSM update process.
* Restart Konfig. If your Exakt device appears under Exakt Setup and there is no Update button, the update was successful and you are done.
* Restart Konfig. If your Exakt device appears under Exakt Setup and there IS an Update button, the update was unsuccessful, click Update to try again.
* If this fails, power cycle your Exakt device and the connected DS/DSM device and try again.
* If this fails, follow the device recovery process below:
* Put both your Exakt device and connected DS/DSM into fallback (from the buttons on the back of the devices).
* Find the connected DS/DSM in the Update tab and click Update.
* If you have an integrated Exakt speaker, this will fully update your Exakt device as well.
* If you have an Exakt tunebox, you will be prompted at the end of the update to enter your speaker serial number from the Exakt Setup tab to complete the update.

If you have difficulty programming an Exakt speaker or Tunebox, but the Exakt DSM is OK (require Konfig 4.12.2 onwards)

* Put the speaker or Tunebox into FALLBACK
:* Make sure the Exakt DSM is Out of Standby
:* Press the Fallback button on the Exakt Speaker/Exakt Tunboks
* In Konfig in the DS - "Exakt setup" tab, this speaker should now show up with a RESTORE button, press the RESTORE button and wait for this to complete. If this is a Exakt Tunebox then enter the serial number of the speaker then do the UPDATE button
* Complete

== Known Issues ==
If you start Konfig and only get a white screen or only shows toolbar with no "Show devices" button:
:1. Go into Internet Explorer - ''Tools'' - ''Internet options''
:2. Select Security
::a) If '''"Internet"''' Security is High, reduce this to Medium High
::b) now select '''"Local Internet"''' icon
::c) If '''"Local Internet"''' Security is High, reduce this to Medium High
:3. OK out of this & restart Konfig

If this does not cure the issue then
:1. Run Konfig
:2. Open Internet Explorer
:3. Type in [http://localhost:5000 http://localhost:5000] into the IE address bar
::(If Songbox is running then type [http://localhost:5001 http://localhost:5001]
:4. What appears in the window?
:5. If Internet Explorer shown the Konfig windows OK then retry steps 3/4/5 using Chrome or another web browser.

;After the update some PC/MAC cannot find any Linn DS/DSM products:
Do the following procedure:
:1. If you are using Norton Anti-virus, make sure that the new Konfig is added an exception
:2. Restart your PC/MAC and retry Konfig 10
::a) Press the '''SHOW DEVICES''' button
::b) If a number appears beside the Updates tab (top of Konfig screen,
:::i) Press the Updates tab and press '''UPDATE''' beside your Linn DS/DSM name
:::ii) Wait until he update is finished and Press the '''SHOW DEVICES''' button. Your DS should now appear.
If your Linn DS/DSM is not listed
:3. Press the '''ADVANCED''' tab and see if your Linn DS/DSM is listed here
 
;If neither of these two options work:Follow the [http://docs.linn.co.uk/wiki/index.php/Troubleshooting#Konfig_diagnostics Konfig 10 diagnostics]

;If doing a Advanced download Konfig reports "cannot find directory..";
:Check that
:1. You can typed the correct file location and file name in to the download field
:2. Konfig 4.10.5-4.11.2 needs internet access before doing the file update. Make sure that you have an Internet link BEFORE opening Konfig

Developer:Media Server Extensions

2015-03-17T10:51:22Z

Davidd: /* Introduction */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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.

Compliant media servers should include a '''size''' element in their artwork URIs, where the size is the image's largest dimension. This allows a control point to ask for an image at a specified size.

The size requested by a control point is a hint for the media server and it does not imply that the media server will satisfy the request. For example a control point might request size=160 but the media server returns size=256 as it is the closest match in its cache.

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

# the media server implements the image scaling extension
# 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.

== Group Information ==

Classical music has the concept of a "work" or "composition" consisting of a group of tracks. This concept is not easily represented in a control point using DidlLite.

A new property has been added to the musicTrack item called '''group'''.

A media server would set the the group property of a musicTrack with the value defined by the GROUP tag contained in the metadata of the audio file.

== Disc Information ==

A new property has been added to the musicTrack item called '''originalDiscNumber'''.

A new property has been added to the musicAlbum item called '''originalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''replayGainAlbum''', '''replayGainAlbumPeak''', '''replayGainTrack''', and '''replayGainTrackPeak'''.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

Developer:Media Server Extensions

2015-03-16T11:34:02Z

Davidd: /* Image Resolution */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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.

Compliant media servers should include a '''size''' element in their artwork URIs, where the size is the image's largest dimension. This allows a control point to ask for an image at a specified size.

The size requested by a control point is a hint for the media server and it does not imply that the media server will satisfy the request. For example a control point might request size=160 but the media server returns size=256 as it is the closest match in its cache.

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

# the media server implements the image scaling extension
# 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.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T11:33:31Z

Davidd: /* Image Resolution */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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.

Compliant media servers should include a '''size''' element in their artwork URIs, where the size is the image's largest dimension. This allows a control point to ask for an image at a specified size.

The size requested by a control point is a hint for the media server and it does not imply that the media server will satisfy the requested size. For example a control point might request size=160 but the media server returns size=256 as it is the closest match in its cache.

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

# the media server implements the image scaling extension
# 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.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T11:29:23Z

Davidd: /* Image Resolution */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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, compliant media servers should include a '''size''' element in their artwork URIs, 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:

# the media server implements the image scaling extension
# 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.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T11:28:41Z

Davidd: /* albumArtURI */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:35:48Z

Davidd: /* albumArtURI */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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.

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:35:34Z

Davidd: /* Dynamic IP Addresses */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

If a user wants to ensure a URI provided by the media server is long lived the host machine running the media server must be assigned a static or dynamic reserved IP address.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:34:13Z

Davidd: /* Dynamic IP Addresses */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

The host machine for a media server must be assign a static or dynamic reserved IP address if a user wishes to ensure that URIs will remain valid.

== Disc Information ==

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:25:13Z

Davidd: /* Disc Information */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

A new property has been added to the musicTrack item called '''OriginalDiscNumber'''.

A new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:24:57Z

Davidd: /* Disc Information */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

A new property has been added to the musicTrack item called '''OriginalDiscNumber''' and a new property has been added to the musicAlbum item called '''OriginalDiscCount'''.

== Replay Gain Information ==

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-16T10:23:47Z

Davidd: /* Replay Gain Information */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Four new properties have been added to the musicTrack item called '''ReplayGainAlbum''', '''ReplayGainAlbumPeak''', '''ReplayGainTrack''', and '''ReplayGainTrackPeak'''.

Developer:Media Server Extensions

2015-03-13T16:14:36Z

Davidd: /* webURI */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:57:30Z

Davidd: /* Low */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:57:19Z

Davidd: /* Medium */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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.

Developer:Media Server Extensions

2015-02-20T17:57:11Z

Davidd: /* High */

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

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:56:49Z

Davidd: /* Introduction */

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

= High =

== Container map ==

The current ContentDirectory specification makes it tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:55:44Z

Davidd: /* Index maps */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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 media server can optionally return an index map for container that are in alphabetical order. This implemented through a OpenHome vendor extension of the DIDL-Lite XML. Below shows an 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>0 10 10 10 10 10 0 0 0 0 10 12 1 10 10 10 12 17 18 1 0 20 0 20 20 2 2 24</indexmap>
</desc>
</DIDL-Lite>

The index map contains a space separated list of 28 number representing the total number of items that begin with that letter. #, represents everything below A, largely digits and punctuation and + represents everything above Z, largely international characters not collatable within the roman alphabet.

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:43:33Z

Davidd: /* Index maps */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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>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</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,

# 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 +

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

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:43:07Z

Davidd: /* Index maps */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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>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</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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:39:29Z

Davidd: /* Search map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of search. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_SEARCH_ENTRY for each type of search offered by the media server.

For example:

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:36:59Z

Davidd: /* Search map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string that is a prefix for a UPnP container id. The search results can be found by browsing to the container whose id is the result of appending the search string to this prefix. For instance, if the prefix for an "album" search is defined as db/search/album/, and the search string is "blue", then the search results container will have an id of db/search/album/blue.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:34:14Z

Davidd: /* Search map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string that can be used by a control point to label a tab containing these search results.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:33:11Z

Davidd: /* Types */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries. It is not a valid type for the X_MAP_LINK_ENTRY_TAG element.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:31:01Z

Davidd: /* Link map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE represents the type of browse hierarchy returned when taking this type of link. See X_MAP_BROWSE_ENTRY_TYPE for details.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

For example:

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:28:30Z

Davidd: /* Link map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string that defines which type of metadata is the target for this link. e.g. "artist", "genre", "composer", etc. See the type section below.

X_MAP_LINK_ENTRY_ID_PREFIX is a string that is prefix for a UPnP container id. The link can be taken by browsing to the container whose id is the result of appending the associated metadata value to this prefix. For instance, if the prefix for an "artist" link is defined as db/link/artist/, and a track returned anywhere in the media server's library has "Pink Floyd" as its artist. Then the linked container will have an id of db/link/artist/Pink Floyd.

X_MAP_LINK_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_LINK_ENTRY is shown below,

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

X_MAP_LINK_ENTRY_TAG contains the piece of metadata that can be linked to "artist". Valid types are listed in the Types section below.

X_MAP_LINK_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of albums. The browse ID is constructed by appending the text in the artist metadata to the prefix, i.e. "db/link/artist/<artist name>"

X_MAP_LINK_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks.

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.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:19:18Z

Davidd: /* Container map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI. The browse map is expressed within the X_MAP_BROWSE element of X_MAP.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc. The link map is expressed within the X_MAP_LINK element of X_MAP.

The search map defines the different kinds of search containers and the type of results that they produce. The search map is expressed within the X_MAP_SEARCH element of X_MAP.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string that can be used by a control point to label a tab containing this browse hierarchy.

X_MAP_BROWSE_ENTRY_ID is the UPnP container id that contains the root of this browse hierarchy. This id is then submitted to the ContentDirectory service using the Browse action as usual. The returned contents are navigated using subsequent Browse request as usual. The difference is that the control point knows in advance what kind of results to expect at each level.

X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings that maps out the kind of containers that are to be found at each level of this browse hierarchy. For instance, "artist album" represents a browse hierarchy giving a container containing only artist containers, each of which contains only album containers, each of which contains only tracks.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

For example:

<X_MAP_BROWSE_ENTRY>
<X_MAP_BROWSE_ENTRY_NAME>Genre</X_MAP_BROWSE_ENTRY_NAME>
<X_MAP_BROWSE_ENTRY_ID>db/browse/genre</X_MAP_BROWSE_ENTRY_ID>
<X_MAP_BROWSE_ENTRY_TYPE>genre artist album</X_MAP_BROWSE_ENTRY_TYPE>
</X_MAP_BROWSE_ENTRY>

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string and used by a control point determine which piece of metadata is valid to show as a link.

X_MAP_LINK_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a link.

X_MAP_LINK_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_LINK_ENTRY is shown below,

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

X_MAP_LINK_ENTRY_TAG contains the piece of metadata that can be linked to "artist". Valid types are listed in the Types section below.

X_MAP_LINK_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of albums. The browse ID is constructed by appending the text in the artist metadata to the prefix, i.e. "db/link/artist/<artist name>"

X_MAP_LINK_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks.

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.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T17:06:04Z

Davidd: /* Container map */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The container map extension allows a media server to express its container hierarchy in advance of the control point navigating it. This is done using an OpenHome vendor extension to the device XML.

Three types of mapped container are defined: browse, link, and search.

The browse map defines named top level containers that represent significant starting points for browsing that can meaningfully be presented in top level tabs of a control point UI.

The link map defines containers that can be meaningfully linked to from track or album details. For instance a track will typically have an artist defined. If an entry for "artist" is defined in the link map then it will be possible for the user of a control point to quickly access this artist-related container by clicking on the track's artist text. Similar links might be offered for "genre", "composer", "conductor", etc.

A media media server may implement any subset of these. A media server will be able to indicate to a control point which mapped containers it supports by including the relevant openhome XML extensions in its device XML.

For a media server to indicate it supports browse mapped containers the device XML must contain entries within an X_MAP_BROWSE element, see the example device XML below.

For a media server to indicate it supports link mapped containers the device XML must contain entries within an X_MAP_LINK element, see the example device XML below.

For a media server to indicate it supports browse mapped containers the device XML must contain entries within an X_MAP_SEARCH element, see the example device XML below.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string and used by a control point to label the root of the browse hierarchy.
X_MAP_BROWSE_ENTRY_ID is a string and used by a control point to start the browse of the browse hierarchy.
X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

Any example of an X_MAP_BROWSE_ENTRY is shown below,

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

The example above defines a root browse hierarchy that provides a list of albums which in turn provide a list of tracks.

X_MAP_BROWSE_ENTRY contains the text for a label in the UI of "Albums".

X_MAP_BROWSE_ENTRY_ID contains the ID to use in the ContentDirectory Browse action to obtain the list of albums.

X_MAP_BROWSE_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks. If for example the hierarchy was a list of genres, then a list of artists, then a list of albums, and finally a list of tracks the type would be "genre artist album".

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string and used by a control point determine which piece of metadata is valid to show as a link.

X_MAP_LINK_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a link.

X_MAP_LINK_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_LINK_ENTRY is shown below,

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

X_MAP_LINK_ENTRY_TAG contains the piece of metadata that can be linked to "artist". Valid types are listed in the Types section below.

X_MAP_LINK_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of albums. The browse ID is constructed by appending the text in the artist metadata to the prefix, i.e. "db/link/artist/<artist name>"

X_MAP_LINK_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks.

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.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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

Developer:Media Server Extensions

2015-02-20T14:11:33Z

Davidd: /* Types */

= 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 tricky for a control point to display the returned contents in an appropriate, aesthetically pleasing, manner for the content being viewed. This is because the ContentDirectory specification does not allow for a control point to know in advanced what content to expect when browsing through any particular hierarchy.

An example of this might be, at a particular point in the browse hierarchy the ContentDirectory will return a list of albums which in turn will contain a list of tracks. A UI might wish to represent this list of albums as a grid and the album's tracks as a header and a list of the tracks. Currently it is not possible for the UI to know when it gets to a point in a hierarchy where the hierarchy represents a list of albums followed by a list of tracks.

The proposal is to add the idea of mapped containers. These containers will have a type that states ahead of time what a control point can expect in terms of contents as it browses down the hierarchy.

The proposal is to have three types of mapped containers, browse, link, and search. A media server will be able to indicate to a control point which mapped containers it supports by including the relevant openhome XML extensions in its device XML.

For a media server to indicate it supports browse mapped containers the device XML must contain entries within an X_MAP_BROWSE element, see the example device XML below.

For a media server to indicate it supports link mapped containers the device XML must contain entries within an X_MAP_LINK element, see the example device XML below.

For a media server to indicate it supports browse mapped containers the device XML must contain entries within an X_MAP_SEARCH element, see the example device XML below.

=== Browse map ===

The X_MAP_BROWSE element must contain 1 or more X_MAP_BROWSE_ENTRY elements.

The X_MAP_BROWSE_ENTRY has three child elements.

X_MAP_BROWSE_ENTRY_NAME is a string and used by a control point to label the root of the browse hierarchy.
X_MAP_BROWSE_ENTRY_ID is a string and used by a control point to start the browse of the browse hierarchy.
X_MAP_BROWSE_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_BROWSE_ENTRY for each root browse hierarchy defined by the media server.

Any example of an X_MAP_BROWSE_ENTRY is shown below,

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

The example above defines a root browse hierarchy that provides a list of albums which in turn provide a list of tracks.

X_MAP_BROWSE_ENTRY contains the text for a label in the UI of "Albums".

X_MAP_BROWSE_ENTRY_ID contains the ID to use in the ContentDirectory Browse action to obtain the list of albums.

X_MAP_BROWSE_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks. If for example the hierarchy was a list of genres, then a list of artists, then a list of albums, and finally a list of tracks the type would be "genre artist album".

=== Link map ===

The X_MAP_LINK element must contain 1 or more X_MAP_LINK_ENTRY elements.

The X_MAP_LINK_ENTRY has three child elements.

X_MAP_LINK_ENTRY_TAG is a string and used by a control point determine which piece of metadata is valid to show as a link.

X_MAP_LINK_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a link.

X_MAP_LINK_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_LINK_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_LINK_ENTRY is shown below,

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

The example above defines a browse hierarchy that is created when linking from an artist name. The hierarchy created provides a list of linked artist albums which in turn provide a list of tracks.

X_MAP_LINK_ENTRY_TAG contains the piece of metadata that can be linked to "artist". Valid types are listed in the Types section below.

X_MAP_LINK_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of albums. The browse ID is constructed by appending the text in the artist metadata to the prefix, i.e. "db/link/artist/<artist name>"

X_MAP_LINK_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent albums and the next level will contain tracks.

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.

=== Search map ===

The X_MAP_SEARCH element must contain 1 or more X_MAP_SEARCH_ENTRY elements.

The X_MAP_SEARCH_ENTRY has three child elements.

X_MAP_SEARCH_ENTRY_NAME is a string and used by a control point to label the browse hierarchy.

X_MAP_SEARCH_ENTRY_ID_PREFIX is a string and used by a control point to start the browse of a search.

X_MAP_SEARCH_ENTRY_TYPE is a space separated list of strings used by a control point to decide how to represent the browse hierarchy in the UI. The list of valid types is described in the Types section below.

There should be an X_MAP_SEARCH_ENTRY for each piece of metadata that the media server allows to be linked.

Any example of an X_MAP_SEARCH_ENTRY is shown below,

<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>artist album</X_MAP_SEARCH_ENTRY_TYPE>
</X_MAP_SEARCH_ENTRY>

The example above defines a browse hierarchy that is created when searching for an artist. The hierarchy created provides a list of artists, which in turn provide a list of albums, which in turn provide a list of tracks.

X_MAP_SEARCH_ENTRY_NAME contains the text for a label in the UI of "Artists"

X_MAP_SEARCH_ENTRY_ID_PREFIX contains the ID prefix to use in the ContentDirectory Browse action to obtain the list of artists. The browse ID is constructed by appending the search text to the prefix, i.e. "db/link/artist/<search text>"

X_MAP_SEARCH_ENTRY_TYPE contains a single entry indicating that the first level contains items that represent artists, the next level will contain albums, and the next level will contain tracks.

=== Types ===

The list of allowed types for X_BROWSE_ENTRY_TYPE, X_MAP_LINK_ENTRY_TAG, X_LINK_ENTRY_TYPE, and X_SEARCH_ENTRY_TYPE

genre
artist
composer
conductor
album
year
mixed

mixed is a special value that represents a container that has mixed entries.

=== 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>artist 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:

# A configurable parameter that scales all artwork to a user defined size
# 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:

# the media server implements the image scaling extension
# 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. 

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