Sonos Developer

Sonos uses the getExtendedMetadata request to display more information about the content in the Sonos app. See Add actions for details.

Request parameters
Response
Details
Sample request
Sample response for a track
Sample response for an artist
Sample response for an album
Sample response for a program
Sample response for a playlist

Request parameters

Name	Type	Description
`id`	string (128)	The unique id of the item about which extended metadata is being requested. This can be any valid `itemType`.

Response

Include the response in a getExtendedMetadataResult inside a getExtendedMetadataResponse element. See SMAPI object types for details about these element.

Name	Type	Description
`mediaCollection`	complex	A complex type describing an `album`, `artist`, `program`, `container`, etc.
`mediaMetadata`	complex	A complex type describing a `track` or `stream`.
`relatedBrowse`	complex	(Optional) Array of `relatedBrowse` elements.
`relatedText`	complex [0..n]	(Optional) Array of `relatedText` elements.
`relatedPlay`	complex [0..n]	(Optional) Array of `relatedPlay` elements.
`relatedActions`	complex [0..1]	(Optional) Array of `action` elements.

Details

Your service should return either a mediaMetadata or a mediaCollection. Return a mediaMetadata if describing an individual item such as a track, stream, or show. Return a mediaCollection if describing a collection of items, such as an album or artist. See SMAPI object types for details of these elements.
The response could optionally include one or more each of relatedBrowse, relatedText, and relatedPlay elements. The response could include one relatedActions element.
The mediaMetadata node may optionally contain a dynamic tag. See the Dynamic ratings section in Develop ratings for details.
By default, Sonos calls getExtendedMetadata for any itemType except playlist, program, and stream. However, you can set Sonos to call getExtendedMetadata for these item types by setting capability flags. See Add capabilities for details.
- For the program and stream item types, enable the “Extended Metadata for radio and streams…” capability flag.
- For the playlist item type, enable the “Extended Metadata for playlists…” capability flag. Note that you can develop and test extended metadata for playlists using customSD, but you need to contact your developer advocate to enable it in production. See Test your service for details about testing with customSD.

Sample request

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

</getExtendedMetadata>

</soap:Body>

</soap:Envelope>

Sample response for a track

<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:123456789</id>
          <itemType>track</itemType>
          <title>Example Track</title>
          <mimeType>audio/mp3</mimeType>
          <trackMetadata>
            <artistId>A:123456</artistId>
            <artist>Dethklok</artist>
            <albumid>M:123456</albumid>
            <album>Dethalbum II</album>
            <duration>343</duration>
            <albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>
            <canSkip>true</canSkip>
            <canAddToFavorites>true</canAddToFavorites>
          </trackMetadata>
        </mediaMetadata>
      </getExtendedMetadataResult>
    </getExtendedMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<itemType>track</itemType>

<title>Example Track</title>

<mimeType>audio/mp3</mimeType>

<artist>Dethklok</artist>

<album>Dethalbum II</album>

<albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>

</trackMetadata>

</mediaMetadata>

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</soap:Body>

</soap:Envelope>

Sample response for an artist

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
      <getExtendedMetadataResult>
        <mediaCollection>
          <id>A:123456</id>
          <itemType>artist</itemType>
          <title>Example Artist</title>
          <canScroll>false</canScroll>
          <canPlay>false</canPlay>
          <canEnumerate>true</canEnumerate>
          <canAddToFavorites>true</canAddToFavorites>
          <albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>
        </mediaCollection>
        <relatedBrowse>
          <id>RPA:123456 </id>
          <type>RELATED_ARTISTS</type>
        </relatedBrowse>
        <relatedText>
          <id>A:123456</id>
          <type>ARTIST_BIO</type>
        </relatedText>
      </getExtendedMetadataResult>
    </getExtendedMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<itemType>artist</itemType>

<title>Example Artist</title>

<canScroll>false</canScroll>

<canPlay>false</canPlay>

<albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>

</mediaCollection>

<type>RELATED_ARTISTS</type>

</relatedBrowse>

<type>ARTIST_BIO</type>

</relatedText>

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</soap:Body>

</soap:Envelope>

Sample response for an album

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
      <getExtendedMetadataResult>
        <mediaCollection readonly="true">
          <id>AL:123456</id>
          <itemType>album</itemType>
          <title>Example Album</title>
          <artist>Example Artist</artist>
          <artistId>A:123456</artistId>
          <canScroll>false</canScroll>
          <canPlay>true</canPlay>
          <canEnumerate>true</canEnumerate>
          <canAddToFavorites>true</canAddToFavorites>
          <albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>
        </mediaCollection>
        <relatedText>
          <id>AL:123456</id>
          <type>ALBUM_NOTES</type>
        </relatedText>
      </getExtendedMetadataResult>
    </getExtendedMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<itemType>album</itemType>

<title>Example Album</title>

<artist>Example Artist</artist>

<canScroll>false</canScroll>

<albumArtURI>http://example.com/images/aa/1.jpg</albumArtURI>

</mediaCollection>

<type>ALBUM_NOTES</type>

</relatedText>

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</soap:Body>

</soap:Envelope>

Sample response for a program

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getExtendedMetadataResponse xmlns="http://www.sonos.com/Services/1.1">
      <getExtendedMetadataResult>
        <mediaCollection>
          <id>P:123456</id>
          <itemType>program</itemType>
          <title>Example Program</title>
          <canScroll>false</canScroll>
          <canPlay>true</canPlay>
          <canEnumerate>false</canEnumerate>
          <canAddToFavorites>true</canAddToFavorites>
          <albumArtURI>http://example.com/images/aa/P12345.jpg</albumArtURI>
        </mediaCollection>
      </getExtendedMetadataResult>
    </getExtendedMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<itemType>program</itemType>

<title>Example Program</title>

<canScroll>false</canScroll>

<canEnumerate>false</canEnumerate>

<albumArtURI>http://example.com/images/aa/P12345.jpg</albumArtURI>

</mediaCollection>

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</soap:Body>

</soap:Envelope>

Sample response for a playlist

<soap:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <soap:Body>
    <getExtendedMetadataResponse>
      <getExtendedMetadataResult>
        <mediaCollection readOnly="false" renameable="true" userContent="true">
          <id>pl:2</id>
          <itemType>playlist</itemType>
          <title>Your New Playlist</title>
          <tags>
            <explicit>1</explicit>
          </tags>
          <canPlay>true</canPlay>
          <canEnumerate>true</canEnumerate>
          <albumArtURI>http://www.example.com/playlistimage.jpg</albumArtURI>
          <canResume>false</canResume>
        </mediaCollection>
        <relatedBrowse>
          <id>ar:2</id>
          <type>RELATED_ARTISTS</type>
        </relatedBrowse>
        <relatedText>
          <id>pl:2</id>
          <type>PLAYLIST_NOTES</type>
        </relatedText>
      </getExtendedMetadataResult>
    </getExtendedMetadataResponse>
  </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">

<soap:Body>

<itemType>playlist</itemType>

<title>Your New Playlist</title>

<tags>

</tags>

<albumArtURI>http://www.example.com/playlistimage.jpg</albumArtURI>

<canResume>false</canResume>

</mediaCollection>

<type>RELATED_ARTISTS</type>

</relatedBrowse>

<type>PLAYLIST_NOTES</type>

</relatedText>

</getExtendedMetadataResult>

</getExtendedMetadataResponse>

</soap:Body>

</soap:Envelope>