getMetadata

The getMetadata message is the core message for content enumeration. Sonos makes each request on a “collection” that represents a list of music metadata.

Because these lists can contain many items, for example the “all tracks” list, the message allows for paginated enumeration. A Sonos player can only hold a few hundred items in memory, so it requires that a collection servicing the getMetadata message return a partial list. See Add pagination for details.

Request parameters

Name	Type	Description
`count`	int	The number of items requested.
`id`	string(128)	Unique ID of the item.
`index`	int	The zero-based index at which to start retrieving metadata items (for example, start with the 101st item).
`recursive`	boolean	If `true`, your service should return a flat collection of track metadata.

Response

Name	Type	Description
`count`	int	The number of items in the result list.
`index`	int	The index in the collection where the result list begins.
`mediaCollection`	complex	Array of `mediaCollection` items. See SMAPI object types for details. See sample response (collections) for an example.
`mediaMetadata`	complex	Array of `mediaMetadata`. See SMAPI object types for details. See sample response (tracks) and sample response (streams) for examples.
`positionInformation`	complex	(Optional) Position information identifies the play position to resume when a user selects an audiobook to resume listening. See SMAPI object types and Save & resume playback for details.
`total`	int	The total number of items in the collection.

Details

Specify the root mediaCollection using a special ID of root.
If your service supports search, you must implement it for Sonos apps for mobile devices, Windows, and Mac OS. Implement search for mobile devices by sending a list of categories in the SearchCategories element in the presentation map. Implement it for Windows and Mac OS by returning a list of category IDs and names, such as “artists”, “tracks” or “albums” in the getMetadata response. The itemType of each element in this list should be search. See Add search for details.
Use the canPlay flag in mediaMetadata to indicate that the collection can be queued for playback in its entirety. In order to accomplish this, Sonos calls getMetadata and passes the recursive parameter set to true. Your service should return a flattened list of all media item elements in the collection. For example, canPlay might be true for a collection that represents a playlist of tracks. But the flag could also be implemented for a collection of collections like all the albums for a given artist. In this case, if you support canPlay, when Sonos calls getMetadata with recursive=true, you should return a flat list of tracks from each of the albums for the selected artist.

Sample request

<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>99</count>
    </getMetadata>
  </soap:Body>
</soap:Envelope>

Sample response (collections)

<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>4</ns:count>
            <ns:total>4</ns:total>
            <ns:mediaCollection>
               <ns:id>genre_mood:1</ns:id>
               <ns:itemType>container</ns:itemType>
               <ns:displayType>genreMood</ns:displayType>
               <ns:title>Entering Beast Mode</ns:title>
               <ns:summary>Level up and enter beast mode with some loud, aggressive music. Just pick a style.</ns:summary>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI>https://acmemusic.example.com/assets/images/beast.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>genre_mood:2</ns:id>
               <ns:itemType>container</ns:itemType>
               <ns:displayType>genreMood</ns:displayType>
               <ns:title>Brand New Music</ns:title>
               <ns:summary>Listen to all the new music worth hearing, all in one place. Just pick a genre.</ns:summary>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI>https://acmemusic.example.com/assets/images/brandNew.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>genre_mood:3</ns:id>
               <ns:itemType>container</ns:itemType>
               <ns:displayType>genreMood</ns:displayType>
               <ns:title>Boosting Your Energy</ns:title>
               <ns:summary>We’ll play you some fun, energetic music. Just pick a genre.</ns:summary>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI>https://acmemusic.example.com/assets/images/boost.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>genre_mood:4</ns:id>
               <ns:itemType>container</ns:itemType>
               <ns:displayType>genreMood</ns:displayType>
               <ns:title>Keeping Calm and Mellow</ns:title>
               <ns:summary>We’ll play you something to keep you calm and mellow. Just pick a genre.</ns:summary>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI>https://acmemusic.example.com/assets/images/calm.jpg</ns:albumArtURI>
            </ns:mediaCollection>
         </ns:getMetadataResult>
      </ns:getMetadataResponse>
   </s:Body>
</s:Envelope>

Sample response (tracks)

<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>3</count>
        <total>100</total>
        <mediaMetadata>
          <id>track0001</id>
          <title>Kiss Kiss (single)</title>
          <mimeType>audio/x-ms-wma</mimeType>
          <itemType>track</itemType>
          <trackMetadata>
            <albumId>album0001</albumId>
            <duration>253</duration>
            <artistId>artist0001</artistId>
            <artist>Chris Brown</artist>
            <album>Kiss Kiss [featuring T-Pain]</album>
            <albumArtURI>http://example.com/track0001.jpg</albumArtURI>
          </trackMetadata>
        </mediaMetadata>
        <mediaMetadata>
          <id>track0002</id>
          <title>Falling On</title>
          <mimeType>audio/x-ms-wma</mimeType>
          <itemType>track</itemType>
          <trackMetadata>
              <albumId>album0002</albumId>
              <duration>209</duration>
              <artistId>artist:11621038</artistId>
              <genre>Unknown</genre>
              <artist>Finger Eleven</artist>
              <album>Them vs. You vs. Me</album>
              <albumArtURI>http://example.com/track0002.jpg</albumArtURI>
            </trackMetadata>
          </mediaMetadata>
          <mediaMetadata>
            <id>track0003</id>
            <title>My Moon My Man</title>
            <mimeType>audio/x-ms-wma</mimeType>
            <itemType>track</itemType>
              <trackmetadata>
                <albumId>album0003</albumId>
                <duration>184</duration>
                <artistId>artist0003</artistId>
                <artist>Feist</artist>
                <album>The Reminder</album>
                <albumArtURI>http://example.com/track0003.jpg</albumArtURI>
              </trackMetadata>
            </mediaMetadata>
      </getMetadataResult>
    </getMetadataResponse>
  </soap:Body>
</soap:Envelope>

Sample response (streams)

<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>3</count>
        <total>3</total>
        <mediaMetadata>
          <id>sta00001</id>
          <title>LIVE!!!! In NYC!!!!!!!!</title>
          <mimeType>audio/x-scpls</mimeType>
          <itemType>stream</itemType>
          <streamMetadata>
            <logo>http://example.com/sta00003.png</logo>
            <currentHost>Donna Summer</currentHost>
            <currentShow>Advanced D&D</currentShow>
          </streamMetadata>
        </mediaMetadata>
        <mediaMetadata>
          <id>sta00002</id>
          <title>The Cheap Seats</title>
          <mimeType>audio/x-mpegurl </mimeType>
          <itemType>stream</itemType>
          <streamMetadata>
            <currentShow>The New Afternoon Show</currentShow>
          </streamMetadata>
        </mediaMetadata>
        <mediaMetadata>
          <id>sta00003</id>
          <title>Carol Burnett: The 'Fresh Air' Interview</title>
          <mimeType>audio/x-ms-wma</mimeType>
          <itemType>stream</itemType>
          <streamMetadata>
            <currentHost>Terry Gross</currentHost>
              <currentShow>Fresh Air</currentShow>
              <logo>http://example.com/sta00003.png</logo>
          </streamMetadata>
        </mediaMetadata>
      </getMetadataResult>
    </getMetadataResponse>
  </soap:Body>
</soap:Envelope>