Adding your playlists to Sonos

You can have two types of playlists for your listeners: Sonos playlists and your playlists.

  • Sonos playlists: Sonos playlists are user-named lists built into the Sonos app for saving songs, albums, and shows in various collections. Listeners manage the Sonos playlists by selecting My Sonos in the lower left of the Sonos app. Listeners add content to their Sonos playlists from the Info View by selecting default actions such as Add Song to Sonos Playlist. Sonos playlists are implemented for you in the Sonos app.
  • Your playlists:  You can implement your own service-specific playlists so that your listeners can create and edit playlists saved on your service, just like they do in your app or on your website. Listeners add or remove items from playlists from the Info View by selecting Add to Playlist or Remove from Playlist.

Be sure to configure playlist capability by checking User Content Playlists in your Sonos Labs application, as described in SMAPI capabilities. Playlist enabling provides the listener control to add a track to a playlist. When the listener selects the elipse (...) to display the Info View, the Add to Playlist action is provided automatically for tracks. 

This document describes how to set up containers for playlist editing. In addition to setup, your service should handle the following requests for playlist editing.  See each request for details.

SMAPI Request Description
addToContainer Adds content to a user's playlist.
createContainer Creates a user content playlist on your service.
deleteContainer Deletes a user content playlist from your service.
removeFromContainer Removes content from a user's playlist.
renameContainer Renames a user content playlist.
reorderContainer Edits the order of a user content playlist.

 

Set up a playlists container in the root container

To enable playlist editing, your service should include a container with an <id> of “playlists” in your root browse menu. Include this container in your responses to any getMetadata requests for “root”. Sonos apps look for a top-level container that has an ID of “playlists”. This container must have two attributes, userContent=true and readonly=false. The <itemType> must be “playlist”.

<soap:Body>
  <getMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
    <getMetadataResult>
      <index>0</index>
      <count>5</count>
      <total>5</total>
      <mediaCollection readOnly="false" userContent="true" renameable="false">
        <id>playlists</id>
        <itemType>playlist</itemType>
        <title>Playlists</title>
        <canScroll>false</canScroll>
        <canPlay>false</canPlay>
        <canEnumerate>true</canEnumerate>
        <albumArtURI>http://icons.com/playlists-icon.png</albumArtURI>
      ...    
      </mediaCollection>
    <getMetadataResult>
  <getMetadataResponse>
<soap:Body>     

 

Allow listeners to organize their playlists with sub-folders

Your service can add sub-folders to the top-level playlist container to give users more sorting options with their playlists. For example, you could set up a Working Out sub-folder or a House Party sub-folder to allow listeners to organize their playlists accordingly. Listeners can add playlists to sub-folders, but can't create them. This means that your service must set up playlist sub-folders in the hierarchy.

Place playlist sub-folders under the parent playlist container in the hierarchy. These folders must have the userContent attribute set to true and the readOnly attribute set to false. The <itemType> should be container. 

A playlist sub-folder looks like this in a getMetadata response:

<mediaCollection readOnly="false" userContent="true" renameable="false">
  <id>playlists:folder:17938252772312961878</id>
  <itemType>container</itemType>
  <title>Playlist Folder</title>
  <canScroll>false</canScroll>
  <canPlay>false</canPlay>
  <canEnumerate>true</canEnumerate>
  <albumArtURI>http://example.com/folder-icon.png</albumArtURI>
</mediaCollection>

Use getLastUpdate to report any changes in user content playlists

Sonos uses the getLastUpdate request to check your implementation for changes to your catalog, user-specific content, or content that frequently changes. For example, the Sonos app sends a getLastUpdate request after a user updates any user-specific content, such as playlists. Your service updates the <favorites> token in your getLastUpdate response to report any changes in a user's stored playlists. This tells Sonos apps to refresh any user-specific content such as playlists or favorites. Sonos apps will call getMetadata to refresh their cached data.  Sonos apps won't see any changes if your service doesn't make this change. See getLastUpdate for details. 

Once you have set up the playlists container, you are ready to implement the Playlist editing SMAPI requests

Implement createContainer to allow playlist creation

Sonos apps send the createContainer request when a user creates a playlist on your service using SMAPI. Implement this method and ensure your service responds to the getLastUpdate request in a timely manner to ensure a good experience. Be sure to implement proper error handling in the naming of a container. The Sonos app limits playlist names to 128 characters but doesn't enforce the validity of those characters. For example, if your system doesn't allow for blank playlist names, you must enforce that in your implementation. Optionally, you can use our custom error mechanism to produce specific error messages that describe the naming error to the listener.

Set attributes on playlists to allow for editing and renaming

If playlists are editable, they must have the readOnly attribute set to false. If listeners can rename a playlist, set the renameable attribute to true.

Note that the userContent attribute is set to false because users can’t add a playlist container within a playlist. They can only add or remove tracks from a playlist and edit the name. Set the userContent attribute to true for playlist containers, not playlists themselves.

<mediaCollection readOnly="false" userContent="false" renameable="true">
  <id>music:username:playlist: 7EybrVkX5IeFfwQoBRg1LW </id>
  <itemType>playlist</itemType>
  <title>My Playlist</title>
  <canScroll>false</canScroll>
  <canPlay>true</canPlay>
  <canEnumerate>true</canEnumerate>
  <albumArtURI>http://example.com/playlist-icon.png</albumArtURI>
</mediaCollection>

Playlists can be editable and not able to be renamed. For example, collaborative playlists could have readOnly set to false and renamable set to false. In this example, a user could edit the playlist, but not be able to change the title.

<mediaCollection readOnly="false" userContent="false" renameable="false">
  <id>music:username:playlist:7EybrVkX5IeFfwQoBRg1LW</id>
  <itemType>playlist</itemType>
  <title>My Playlist</title>
  <canScroll>false</canScroll>
  <canPlay>true</canPlay>
  <canEnumerate>true</canEnumerate>
  <albumArtURI>http://example.com/playlist-icon.png</albumArtURI>
</mediaCollection>

Enable listener actions in the playlist Info View

When listeners select the ellipse (…) to display the Info View for a playlist there are some standard options that Sonos displays. These include choices like Add Playlist to My Sonos, Add to Sonos Playlist, and Play Now

Your service can add custom actions to the Info View for playlists as well. You can add a related browse option to point users to an artist or genre that's relevant to the playlist they are listening to. You can provide more information about a playlist with the related text action. See Customizing listener actions in the Info View for details.

Listener actions are available for both user-content playlists and any playlists that your service provides for your listeners. You need to contact your developer advocate to enable this capability in production, but you can develop and test by using customSD. See Test your service on Sonos for details.

updateId is reserved for future implementation

The <updateId> element in the playlist editing methods is not yet implemented.  In the future, we may use <updatedId> to detect data collisions. For example, if two users in the same household both edit a playlist in the same transaction window.