This tutorial guides you through creating a display type that displays your albums as a list in the Sonos app.
Some default container itemType objects are already available that display contents in lists. You may want to look at these to see if they suit your needs before customizing display types.
Create a presentation map
Your presentation map determines how certain elements in your service appear in the Sonos app. You should have one presentation map for your service. This tutorial assumes that you have not created a presentation map for your service. See Customize display for details about presentation maps.
Your presentation map always starts with the open <Presentation> tag and ends with the close </Presentation> tag:
|
1 2 3 |
<Presentation> ... </Presentation> |
The ellipsis (…) in the example above indicate other content that exists within the tags.
Create a display type using the “DisplayType” attribute in your presentation map:
|
1 2 3 4 5 |
<?xml version="1.0" encoding="UTF-8"?> <Presentation> <PresentationMap type="DisplayType">...</PresentationMap> ... </Presentation> |
Enter a name for your display type using the “id” parameter of the <DisplayType> sub-element and enter “LIST” as the content of the <DisplayMode> sub-element:
|
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0" encoding="UTF-8"?> <Presentation> <PresentationMap type="DisplayType"> <DisplayType id="listOfAlbums"> <DisplayMode>LIST</DisplayMode> </DisplayType> </PresentationMap> ... </Presentation> |
The XML above indicates that the listOfAlbums display type will be a list.
Configure lines and strings
Unlike the example in the Grid tutorial, this example uses the default album title and artist as the two lines next to the album art, so you do not need to specify lines.
Respond to getMetadata requests
This section goes over the getMetadata requests and responses and how they appear in Sonos apps.
getMetadata request – root
When a user browses into your service, the Sonos app sends a getMetadata request to show the root container.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> ... </s:Header> <s:Body> <getMetadata xmlns="http://www.sonos.com/Services/1.1"> <id>root</id> <index>0</index> <count>100</count> </getMetadata> </s:Body> </s:Envelope> |
getMetadata response – root
You should send back a getMetadata response that includes all top-level containers. The response below only shows the relevant container, the “Listen Now” container using the mediaCollection sub-element for browse:albums_v2, which uses the listOfAlbums display type we created in the presentation map above.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1"> <s:Body> <ns:getMetadataResponse> <ns:getMetadataResult> <ns:index>0</ns:index> <ns:count>10</ns:count> <ns:total>10</ns:total> ... <ns:mediaCollection> <ns:id>browse:albums_v2</ns:id> <ns:itemType>albumList</ns:itemType> <ns:displayType>listOfAlbums</ns:displayType> <ns:title>Listen Now</ns:title> <ns:canPlay>false</ns:canPlay> <ns:containsFavorite>false </ns:containsFavorite> <ns:albumArtURI /> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
Sonos app user interface – root
The getMetadata response populates the user interface as shown below.
getMetadata request – album as list
When the user clicks the “Album as List” container, the app sends a getMetadata request to your service to display its contents.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Header> ... </s:Header> <s:Body> <getMetadata xmlns="http://www.sonos.com/Services/1.1"> <id>browse:albums_v2</id> <index>0</index> <count>100</count> </getMetadata> </s:Body> </s:Envelope> |
getMetadata response – album as list
Your service should send a getMetadata response with the contents of this container. The sample below returned a large number of results, but only a few are shown, for brevity.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
<?xml version="1.0" encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1"> <s:Body> <ns:getMetadataResponse> <ns:getMetadataResult> <ns:index>0</ns:index> <ns:count>35</ns:count> <ns:total>35</ns:total> ... <ns:mediaCollection> <ns:id>al:3</ns:id> <ns:itemType>album</ns:itemType> <ns:title>Feel the Light</ns:title> <ns:isFavorite>false</ns:isFavorite> <ns:artist>Aurora B</ns:artist> <ns:artistId>ar:2</ns:artistId> <ns:canPlay>true</ns:canPlay> <ns:canEnumerate>true</ns:canEnumerate> <ns:canAddToFavorites>true</ns:canAddToFavorites> <ns:albumArtURI>https://example.com/images/album1.jpg </ns:albumArtURI> </ns:mediaCollection> <ns:mediaCollection> <ns:id>al:1</ns:id> <ns:itemType>album</ns:itemType> <ns:title>We Have Respect For Them</ns:title> <ns:isFavorite>false</ns:isFavorite> <ns:artist>Bauer</ns:artist> <ns:artistId>ar:2</ns:artistId> <ns:canPlay>true</ns:canPlay> <ns:canEnumerate>true</ns:canEnumerate> <ns:canAddToFavorites>true</ns:canAddToFavorites> <ns:albumArtURI>https://example.com/images/album2.jpg </ns:albumArtURI> </ns:mediaCollection> <ns:mediaCollection> <ns:id>al:16</ns:id> <ns:itemType>album</ns:itemType> <ns:title>Electric Vibe</ns:title> <ns:isFavorite>false</ns:isFavorite> <ns:artist>K No</ns:artist> <ns:artistId>ar:14</ns:artistId> <ns:canPlay>true</ns:canPlay> <ns:canEnumerate>true</ns:canEnumerate> <ns:canAddToFavorites>true</ns:canAddToFavorites> <ns:albumArtURI>https://example.com/images/album3.png </ns:albumArtURI> </ns:mediaCollection> ... </ns:getMetadataResult> </ns:getMetadataResponse> </s:Body> </s:Envelope> |
Sonos app user interface – album as list
These contents are displayed using the listOfAlbums display type, in this case, as a list.
List display mode without images
If desired, your service can choose not to return any artwork for non-playable browse nodes in a list display mode. To do this, set the ItemThumbnails source attribute to “none” in your presentation map.
The Sonos app will only display a list without an image on a iOS or Android device. The Sonos app on a Mac or PC will use default Sonos browse icons. As noted above, this will only work with non-playable items, such as a list of genres. Anything that a listener can play will still need artwork.
|
1 2 3 4 |
<DisplayType id="playlistGrid"> <DisplayMode>LIST</DisplayMode> <ItemThumbnails source="none"/> </DisplayType> |