Sonos Developer

You can add a single custom stream or programmed radio station to the Info View using a related play action. For example, you can provide to your listeners a programmed radio station seeded by a specific artist, album, song, or genre.

The following steps describe how to implement a related play action:

Enable the Extended Metadata for Radio capability.
To use the related play action, ensure you enable the Extended Metadata for Radio capability when you submit your service. This indicates that you want to support this capability on all Sonos players that use your service. See Add capabilities and Submit your service for details. For testing, enable it on the custom SD page for a player when you’re developing your service integration. See Test your service for details.
When the listener selects the ellipsis (…) to see the Info View, Sonos sends your service a getExtendedMetadata request. This example is for a track item.

<s:Envelope
  xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
  ...
  </s:Header>
  <s:Body>
    <getExtendedMetadata xmlns="http://www.sonos.com/Services/1.1">
      <id>tr:15</id>
    </getExtendedMetadata>
  </s:Body>
</s:Envelope>

<s:Envelope

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

<s:Header>

...

</s:Header>

<s:Body>

</getExtendedMetadata>

</s:Body>

</s:Envelope>

Include all the custom actions for the Info View in your getExtendedMetadata response. To simplify this example we’ll show only the related play action.

<s:Envelope
        xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:ns="http://www.sonos.com/Services/1.1">
  <s:Body>
    <ns:getExtendedMetadataResponse>
      <ns:getExtendedMetadataResult>
        <ns:mediaMetadata>
          <ns:id>tr:15</ns:id>
          <ns:itemType>track</ns:itemType>
          <ns:title>Generations of Skipping Heartbeats</ns:title>
          <ns:isFavorite>false</ns:isFavorite>
          <ns:mimeType>audio/mp3</ns:mimeType>
          <ns:trackMetadata>
            <ns:artist>The Agrarians</ns:artist>
            <ns:album>Love Songs from 2011</ns:album>
            <ns:duration>138</ns:duration>
            <ns:albumArtURI>https://example.com/assets/images/love_songs2011.jpg</ns:albumArtURI>
            <ns:canPlay>true</ns:canPlay>
            <ns:canAddToFavorites>true</ns:canAddToFavorites>
          </ns:trackMetadata>
        </ns:mediaMetadata>
        . . . Details for other custom actions in the Info View are not shown . .
        <ns:relatedPlay>
          <ns:id>pradio:2</ns:id>
          <ns:itemType>program</ns:itemType>
          <ns:title>Radio Blues Program Radio</ns:title>
          <ns:canPlay>true</ns:canPlay>
        </ns:relatedPlay>
      </ns:getExtendedMetadataResult>
    </ns:getExtendedMetadataResponse>
  </s:Body>
</s:Envelope>

<s:Envelope

xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ns="http://www.sonos.com/Services/1.1">

<s:Body>

<ns:getExtendedMetadataResponse>

<ns:getExtendedMetadataResult>

<ns:mediaMetadata>

<ns:id>tr:15</ns:id>

<ns:itemType>track</ns:itemType>

<ns:title>Generations of Skipping Heartbeats</ns:title>

<ns:isFavorite>false</ns:isFavorite>

<ns:mimeType>audio/mp3</ns:mimeType>

<ns:trackMetadata>

<ns:artist>The Agrarians</ns:artist>

<ns:album>Love Songs from 2011</ns:album>

<ns:duration>138</ns:duration>

<ns:albumArtURI>https://example.com/assets/images/love_songs2011.jpg</ns:albumArtURI>

<ns:canPlay>true</ns:canPlay>

<ns:canAddToFavorites>true</ns:canAddToFavorites>

</ns:trackMetadata>

</ns:mediaMetadata>

. . . Details for other custom actions in the Info View are not shown . .

<ns:relatedPlay>

<ns:id>pradio:2</ns:id>

<ns:itemType>program</ns:itemType>

<ns:title>Radio Blues Program Radio</ns:title>

<ns:canPlay>true</ns:canPlay>

</ns:relatedPlay>

</ns:getExtendedMetadataResult>

</ns:getExtendedMetadataResponse>

</s:Body>

</s:Envelope>

For details about the relatedPlay sub-elements, see SMAPI Object Types.
(Optional) Customize the “Start Radio” text string.
The related play displays in the Info View as “Start Radio” by default, but you can replace this text. The following example replaces the string with “Go to Radio”.
- In your presentation map, add a RelatedPlay MenuItem to the MenuItemOverrides element. See Customize display for details about presentation maps.

<PresentationMap type="InfoView">
 <Match>
  <MenuItemOverrides>
    ...
    <MenuItem MenuItem="RelatedPlay" StringId="RELATED_RADIO"/>
    ...
  </MenuItemOverrides>
   ...
 </Match>
</PresentationMap>

<Match>

...

...

</MenuItemOverrides>

...

</Match>

</PresentationMap>

In your strings.xml file, add the following string entry, where the stringId value matches the stringId value in the presentation map. See Strings and Localization for details

<string stringId="RELATED_RADIO">Go to Radio</string>

1	<string stringId="RELATED_RADIO">Go to Radio</string>

If the listener chooses the related play action, the following occurs:
1. Sonos sends your service a getMetadata request using the given related play id (pradio:2).
2. Your service would provide the getMetadata response with mediaMetadata for the programmed radio station.
3. Sonos sends your service a getMediaURI request to get the station URI.
4. Your service would provide the getMediaURI response with the audio data so that Sonos can begin playing it.
  
  Note: The now-playing screen will show the title of the custom radio station, which for this example would be “Radio Blues Program Radio”.