Related play

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:

1. 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. See Test your service for details about testing.

2. 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.

   XML

   <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>
   

3. 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.

   XML

   <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>
   

4. For details about the relatedPlay sub-elements, see SMAPI object types.

5. (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 text with "Go to Radio".
   In your i18next file, add the following entry. See Localization for details.

{
    "en-US":{
      "common":{
          ...
          },
      "integration":{
        "RELATED_RADIO": "Go to Radio"
        ...
      }
    },
}

6. 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.

      📘

      The Now Playing screen will show the title of the custom radio station. For this example, it would show "Radio Blues Program Radio".