Sonos Music API - Reference

getExtendedMetadata

Sonos uses the getExtendedMetadata request to display more information about the content in the Sonos app. See Customizing listener actions in the Info View for usage.

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

Name

Type

Description

mediaMetadata

<mediaMetadata>

A complex type describing a track or stream.

mediaCollection

<mediaCollection>

A complex type describing an album, artist, program, container, etc.

relatedBrowse

<relatedBrowse>[0..n]

(Optional) Array of relatedBrowse elements. See SMAPI object types for details.

relatedText

<relatedText>[0..n]

(Optional) Array of relatedText elements. See SMAPI object types for details.

relatedPlay

<relatedPlay>[0..n]

(Optional) Array of relatedPlay elements. See SMAPI object types for details.

relatedActions

<action>[0..1]

(Optional) Array of <action> elements. See SMAPI object types for details.

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 Dynamic 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 SMAPI 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 on Sonos 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>

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>

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>

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>

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>

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>