Content on Sonos

The following sections describe how to display your service's content metadata in the Sonos app.

Provide content metadata

In addition to providing content, your service should also supply metadata about artists, albums, playlists, tracks, and other items. This table shows a sampling of the metadata you can offer. See itemType for the full list of metadata item types.

Metadata itemType

An item type defines the type of metadata. SMAPI provides the itemType XML element that a service uses to define the type of metadata. Item type values are divided into two categories: single media items and collections of media items. For example, a single media item type is a track. The album item type is a collection of tracks, and includes metadata such as the album name among other metadata.

mediaMetadata identifies a single item

A single metadata item type can be track, stream, or show. SMAPI provides the mediaMetadata XML element that a service uses to hold the metadata for a single playable item. The itemType is a sub-element of mediaMetadata. See mediaMetadata for details.

mediaCollection identifies a collection of items

A collection identifies a list of metadata items. A collection can identify a list of albums, artists, tracks, and even other collections. SMAPI provides a mediaCollection XML element that a service uses for a collection. The itemType is a sub-element of mediaMetadata. See mediaCollection for details.

Playable items and canPlay

A playable item can be selected by the listener for playback if the item has canPlay set to true.

• The mediaMetadata items are by default playable items (canPlay = true). The canPlay policy is a sub-element of trackMetadata.
• The mediaCollection items are by default non-playable items (canPlay = false). The canPlay policy is a sub-element of mediaCollection.

📘

Playable item vs. playable content audio

The actual playable audio content is an audio file on a server and is identified in SMAPI with a URL to the audio file.

Containers hold mediaMetadata and mediaCollection elements

When a user browses into a service with the Sonos app, a service might look similar to the following. Each icon and title identify more content for the service. The listener selects one of the icons to browse into the service's catalog.

Containers hold lists of metadata items. A container typically holds a list of mediaMetadata elements or a list of mediaCollection elements, but a container can hold a combination of the two. The browsable catalog consists of a hierarchy of containers. The first container a user sees when they browse into a service from the Sonos app is the root container. This is like a service’s homepage for a SMAPI integration. The following diagram represents containers and media items within the containers in the Sonos app.

Note that a mediaCollection is not a container, but is a metadata item that identifies another container. For example, in the service above, the Music Service container holds a list of mediaCollection elements, where each identifies a container titled Artists, Albums, Composers, and so on.

1. If the listener selects Albums (identified by a mediaCollection) from the Music Service container, the Sonos app requests that list of items from the music service. The service returns a list of mediaCollection items.
2. The Sonos app then displays the list as the Albums container, where each mediaCollection identifies an album. If the listener then selects a specific album (identified by a mediaCollection) from the Albums container, the Sonos app requests a new list of items from the music service. In this case, the service returns a list of mediaMetadata playable items.
3. The Sonos app displays the list as a new container, where the mediaMetadata elements represent the album's tracks.

The following table shows one example of how a listener might browse the hierarchy of containers to reach a mediaMetadata element representing a playable track.

👍

Arrange your catalog into a hierarchy of containers as it is organized for your app and website. This way, your SMAPI integration can implement browsing in the Sonos app to work the way users are familiar with in your app or on your website.

Listeners save and play favorites in My Sonos

Listeners save content from your service to My Sonos. My Sonos is organized by content type. For example, the My Sonos screen has a row for podcasts, a row for playlists, and an area for radio stations. If a user hasn’t saved any of a type of content, for example podcasts, then the podcasts row won’t show up on the My Sonos screen.

You don't need to do anything special to enable My Sonos. It is available by default for Sonos apps for iOS and Android. It is not available for Sonos apps for Mac and PC. Most of the time, when a user saves content to My Sonos on a mobile app, it will appear in Sonos Favorites in the Sonos app for Mac or PC. However, users on a mobile app can save non-playable containers such as a recommendations container to My Sonos. These containers aren’t available from Sonos Favorites in the Sonos app for Mac or PC.

If your service offers temporary content, such as a holiday-themed playlist or radio station, use the isEphemeral element to prevent users from saving it to My Sonos. Otherwise, they would see a blank item in My Sonos if they saved it and it expired. See SMAPI object types for details.

Display

The Sonos app displays each container in different ways, depending on its itemType and displayType. Each itemType has a different default display mode, see SMAPI object types for details. See Customize display for more information about display modes.

Content IDs

Sonos uses a variety of identifiers (IDs) to represent different elements of the system. Some IDs represent physical locations or hardware, some represent users or user activity, and some represent items within your music service.

Your service assigns every metadata item in the browse hierarchy its own unique content ID. Content IDs must obey certain rules so that your service can map them to real content and Sonos apps can browse or cache the hierarchy. Content IDs must not change once they are established. For example, if track IDs are renumbered, playlists that the listener has created within their client application will be irreparably broken.

Content IDs should be alphanumeric strings of a reasonable length up to 256 characters maximum. Use short content ID values where a code represents the item type, followed by a separator, followed by a value that represents the specific catalog item. This makes it easy to see the type of item returned while debugging issues. Sonos does not care what code or separator you use. For example, ID formats for an album 1234 could be album:1234, alb-1234, a::1234, or ALB__1234.

In our example, we could use content IDs such as the following:

Note, the following content IDs are reserved for specific use:

• root: The Sonos app requires this well-known content ID to make the first content request to any service.
• playlists: See Add playlists for details.
• search: See Add search for information about search.

All content IDs are URL-encoded in our firmware. Take this into account if your IDs are approaching the 256-character limit. For example, this is a contrived content ID:

my_service:track:track_id_with_umläut_goes_here

This will be URL-encoded in firmware and stored as the following:

my_service%3Atrack%3Atrack_id_with_uml%C3%A4ut_goes_here

The total length of that string including the NULL terminator will be 57 characters as opposed to the 47 characters originally passed in the SOAP Envelope.

Respond to getMetadata to provide content

Listeners browse your catalog with the Sonos app. When the listener selects a collection from a container, they browse into another container holding more metadata items. Each time the listener browses into a container, the Sonos app sends a getMetadata request. Your service uses the content ID in the id element (among other information) to respond to these requests by returning a list of mediaCollection or mediaMetadata objects. The following diagram shows the sequence.

The following describes an example of the listener browsing into some containers:

1. The listener selects the Music Service collection from the Sonos app.
   1. The Sonos app makes a getMetadata request using the id value root.
   2. The service returns a list of mediaCollection elements.
   3. The Sonos app displays the list in the Music Service container. (Artist, Albums, Composers, and so on.)
2. The listener selects the Albums collection from the Music Service container.
   1. The Sonos app makes a getMetadata request using the id value albums.
   2. The service returns a list of mediaCollection elements.
   3. The Sonos app displays the list in the Albums container. (Each item is an album.)
3. The listener selects The Rocks 1st Album collection from the albums container.
   1. The Sonos app makes a getMetadata request using the id value al_8657.
   2. The service returns a list of mediaMetadata elements.
   3. The Sonos app displays the list in the The Rocks 1st Album container. (Each item is a track of the album.)

Use caching in your integration for content that is unlikely to change or that is likely to be requested repeatedly over a short period of time.

Return mediaCollection elements for a container

When the listener browses into the Music Service from the Sonos app's Browse menu, the Sonos app sends the service a getMetadata request for the top-level container by using the id value root:

getMetadata request for the root container

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope"  
  <soap:Body>  
    <getMetadata xmlns="http://www.sonos.com/Services/1.1"  
      <id>root</id>  
      <index>0</index>  
      <count>100</count>  
    </getMetadata>  
  </soap:Body>  
</soap:Envelope>

The index identifies the beginning of the container's list of items. The Sonos app uses 100 for the default count value.

The service responds to a request for the root ID with metadata for the service's root (top-level) container.

getMetadata response for the root container

<Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <Body>
    <getMetadataResponse>
      <getMetadataResult>
        <index>0</index>
        <count>5</count>
        <total>5</total>
        <mediaCollection>
          <id>artists</id>
          <itemType>container</itemType>
          <title>Artists</title>
          <summary>Choose music based on your preferred artist.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/artists.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>albums</id>
          <itemType>albumList</itemType>
          <title>Albums</title>
          <summary>Choose an album to play.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/albums.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>composers</id>
          <itemType>container</itemType>
          <title>Composers</title>
          <summary>Choose music based on your preferred composer.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/composers.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>genres</id>
          <itemType>container</itemType>
          <title>Genres</title>
          <summary>Choose a musical genre.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/genres.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>songs</id>
          <itemType>trackList</itemType>
          <title>Songs</title>
          <summary>Choose a song.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/songs.jpg</albumArtURI>
        </mediaCollection>
      </getMetadataResult>
    </getMetadataResponse>
  </Body>
</Envelope>

The Sonos app displays items in the order that your service returns them in the getMetadata response. For this example, the Artists mediaCollection is before the Albums mediaCollection. Organize content in a way that is consistent with your other apps or website and understandable to your users.

The following elements have to do with the number of items in the list. See Add pagination for details.

• The index indicates where the returned list starts with respect to the total list of possible items in your catalog for this container. A value of 0 indicates the beginning of the list.
• The count indicates the number of items returned in this list.
• The total indicates the total possible in the list of items.

The following are required elements for a mediaCollection:

• id: This is your content ID that identifies the specific metadata item.
• itemType: Each mediaCollection requires you specify the collection's item type.
  • The container item type identifies another container.
  • The albumList item type identifies another container that holds a list of albums.
  • The trackList item type identifies another container that holds a list of songs. This trackList container would hold mediaMetadata elements, one for each song.
• title: The title is the label the Sonos app displays for the specific metadata item and the associated container.

The mediaCollection element can include many options. Provide as many as appropriate so that Sonos can provide your users with the best experience possible.

We recommend you include the following options so the Sonos app displays more details to the listener:

• summary: The summary text displays for certain display modes. Each itemType has a default display mode. For example, the albumList item type displays as a grid by default, whereas the container and trackList item types display as a list. See Customize display for details.
• albumArtURI: Use albumArtURI to supply an image as an icon for the item in the Sonos app. More is described in Add album art.

Return mediaCollection elements with playback policies

Your getMetadata responses to requests for most containers would look similar to the example above. However, some mediaCollection item types can include playback policies, such as canPlay. In the following example, if the listener clicks the Albums collection, the Sonos app sends the service a getMetadata request with the id value albums, which identifies an albumList type of container.

getMetadata request for an albumList container type

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">  
  <soap:Body>  
   <getMetadata xmlns="http://www.sonos.com/Services/1.1">  
     <id>albums</id>  
     <index>0</index>  
     <count>100</count>  
   </getMetadata>  
  </soap:Body>  
</soap:Envelope>

The service responds to the request with mediaCollection elements that identify a list of albums for the Albums container.

getMetadata for the Albums container

<Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <Body>
    <getMetadataResponse>
      <getMetadataResult>
        <index>0</index>
        <count>24</count>
        <total>24</total>
        <mediaCollection>
          <id>al_5864</id>
          <itemType>album</itemType>
          <title>Floating in the Ocean</title>
          <artist>Verkaelak</ns:artist>
          <artistId>ar_4598</ns:artistId>
          <summary>Possibly the greatest album by this new age group.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/al_5864.jpg</albumArtURI>
          <canAddToFavorites>true</canAddToFavorites>
          <canPlay>true</canPlay>
        </mediaCollection>
        <mediaCollection>
          <id>al_8657</id>
          <itemType>album</itemType>
          <title>The Rocks 1st Album</title>
          <artist>The Rocks</ns:artist>
          <artistId>ar_2654</ns:artistId>
          <summary>The first album by the new group, The Rocks.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/al_8657.jpg</albumArtURI>
          <canAddToFavorites>true</canAddToFavorites>
          <canPlay>true</canPlay>
        </mediaCollection>
       .
       .
       .
      </getMetadataResult>
    </getMetadataResponse>
  </Body>
</Envelope>

Use optional playback policies in mediaCollection sub-elements to provide information about behavior for the collection. The following are examples of some settings for mediaCollection items:

• canAddToFavorites: When this is true, the listener can add the album to their service-specific favorites. Implementing service-specific favorites is an added feature described in Add favorites. This does not affect whether a user can save the album to My Sonos.
• canPlay: You can set some metadata items such as album or trackList item types to be playable items using canPlay. Note, if canPlay = true for a mediaCollection, its container must hold only playable items, where the canPlay values are all true. The container cannot hold any non-playable items, where a canPlay value is false.

If canPlay = true for a mediaCollection, then when the user browses into the container the Sonos app shows playback actions such as the following:

• Play Now
• Play Next
• Add to Queue
• Replace Queue

See Set playback policies for details.

Return mediaMetadata elements for single items

If the listener browses into a container holding tracks (such as the album, The Rocks 1st Album), the request would look something like the following. In this example, the getMetadata request would include the id value al_8657, which identifies the album The Rocks 1st Album.

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/">  
  <soap:Body>  
   <getMetadata xmlns="http://www.sonos.com/Services/1.1">  
     <id>al_8657</id>  
     <index>0</index>  
     <count>100</count>  
   </getMetadata>  
  </soap:Body>  
</soap:Envelope>

The service responds with metadata for the album. The getMetadata response would contain a list of songs, where each song is represented by a mediaMetadata element.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">  
  <soap:Body>  
    <getMetadataResponse xmlns="http://www.sonos.com/Services/1.1">  
      <getMetadataResult>  
        <index>0</index>  
        <count>12</count>  
        <total>12</total>  
        <mediaMetadata>  
          <id>t_85787</id>  
          <title>Satisfy</title>  
          <mimeType>audio/x-ms-wma</mimeType>  
          <itemType>track</itemType>  
          <trackMetadata>  
            <albumId>al_8657</albumId>  
            <duration>253</duration>  
            <artistId>ar_2654</artistId>  
            <artist>The Rocks</artist>  
            <album>The Rocks 1st Album</album>  
            <albumArtURI><http://example.com/al_8657.jpg></albumArtURI>  
          </trackMetadata>  
        </mediaMetadata>  
        <mediaMetadata>  
          <id>t_85745</id>  
          <title>Artificial Sugar</title>  
          <mimeType>audio/x-ms-wma</mimeType>  
          <itemType>track</itemType>  
          <trackMetadata>  
            <albumId>al_8657</albumId>  
            <duration>209</duration>  
            <artistId>ar_2654</artistId>  
            <artist>The Rocks</artist>  
            <album>The Rocks 1st Album</album>  
            <albumArtURI><http://example.com/al_8657.jpg></albumArtURI>  
          </trackMetadata>  
        </mediaMetadata>  
       .  
       .  
       .  
      </getMetadataResult>  
    </getMetadataResponse>  
  </soap:Body>  
</soap:Envelope>

Required elements for the mediaMetadata include the following:

• id: This is your content ID that identifies the specific metadata item. (song)
• title: The title is the label the Sonos app displays for the specific item. (song title)
• itemType: Each mediaMetadata requires you specify the item type, which for a song is track.
• mimeType: The media type for this track.
• trackMetadata: This contains details about the specific track to play.

The trackMetadata element can include many options. Provide as many as appropriate so that Sonos can provide your users with the best experience possible. For example, the Sonos app uses the following sub-elements to display track details to the listener:

• albumId
• duration
• artistId
• artist
• album
• albumArtURI

Use trackMetadata sub-elements to provide information about playback behavior and about which controls the listener can use during playback. The following playback policies are true by default for the track item type:

• canPlay
• canSeek
• canSkip
• canAddToFavorites

See Set playback policies for details.

Respond to getExtendedMetadata to provide the Info View

To do more with an item (track, album, and so on), the listener can select the ellipsis (...), which displays the Info View. The Info View is a dialog/popup with actions listeners can select to apply to the current item type. For example, one action is Play Now. The following diagram shows an album Info View and a song Info View.

The following diagram shows the basic process sequence.

The following example shows a request for the Info View of the track whose id is t_85745. Sonos obtained this ID from an earlier getMetadata response when the album container was requested.

getExtendedMetadata request

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/">>  
  <soap:Body>  
   <getExtendedMetadata xmlns="http://www.sonos.com/Services/1.1">  
     <id>t_85745</id>  
   </getExtendedMetadata>  
  </soap:Body>  
</soap:Envelope>

Your service should return either a mediaMetadata or a mediaCollection in your getExtendedMetadata response. Return a mediaMetadata if describing a single item such as a track, stream, or show. Return a mediaCollection if describing a collection of items, such as an album or artist. The information you return in the mediaMetadata or mediaCollection for a specific content ID is typically the same for your getExtendedMetadata and getMetadata responses.

The following is an example of how a service supplies more information about a track.

getExtendedMetadata response

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body>  
   <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">  
     <getExtendedMetadataResult>  
       <mediaMetadata>  
         <id>t_85745</id>  
         <title>Artificial Sugar</title>  
         <mimeType>audio/x-ms-wma</mimeType>  
         <itemType>track</itemType>  
         <trackMetadata>  
           <albumId>al_8657</albumId>  
           <duration>209</duration>  
           <artistId>ar_2654</artistId>  
           <artist>The Rocks</artist>  
           <album>The Rocks 1st Album</album>  
           <albumArtURI><http://example.com/al_8657.jpg></albumArtURI>  
         </trackMetadata>  
       </mediaMetadata>  
     </getExtendedMetadataResult>  
   </getExtendedMetadataResponse>  
  </soap:Body>  
</soap:Envelope>

This is a basic response that would cause the Sonos app to display only the default actions for a track in the Info View.

You can use getExtendedMetadata responses to add custom actions to the Sonos app's Info View so that users can perform specific actions for your service. For example, you can provide more album and artist information. You provide custom actions by adding a element in the response with one or more sub-elements. These are described later as added features in Add actions.

Add alphabetic scrolling to simplify browsing

Alphabetical scrolling uses getScrollIndices to optimize content enumeration for large collections of metadata. Alphabetical scrolling allows a listener to scroll through the alphabet and select a letter. This initiates a getMetadata request on a collection at a particular index.