Enable playlist editing

In the Sonos app, your listeners can create and edit playlists saved on your service, just like they do in your app or on your website. Configure this capability by checking User Content Playlists in your Sonos Labs application. See SMAPI capabilities for details.

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>

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.