Sonos allows users to construct their personal playlists containing individual tracks offered by your on-demand music service. Users may have multiple playlists and may organize their playlists into folders. SMAPI provides API calls to create, delete, rename, and reorder playlists. All playlists must be organized underneath a main playlists container at the root level of your hierarchy. Playlists must be retrievable using getMetadata ("playlists") and subsequent getMetadata calls following the hierarchy as desired from there.

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 Add capabilities. Playlist enabling provides the listener control to add a track to a playlist. When the listener selects the ellipsis (...) 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.

Set up playlists container in the root

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>

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

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

Use createContainer to create playlists

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. See Error handling for details.

Allow playlist editing & renaming

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

Set the userContent attribute 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.

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

Set the userContent attribute to true for playlist containers, not playlists themselves. See Set up playlists container in the root above for details.

Playlists can be editable but not renameable. For example, collaborative playlists could have readOnly set to false and renameable set to false. In this example, a user could edit the playlist, but not 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>

See mediaCollection for details about other attributes you can set.

Enable listener actions

Contact your developer advocate to enable listener actions in production.

When listeners select the ellipsis (…) to display the Info View for a playlist, Sonos displays some standard options. 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 Add actions for details.

Listener actions are available for both user-content playlists and any playlists that your service provides for your listeners. Select the Enable Extended Metadata for playlists capability to do so. See Add capabilities and Test your service for details.

⚠️

updateId not used

The updateId element in the playlist editing methods is not implemented.