getMediaURI

Sonos players use the getMediaURI message to resolve a URI for the actual audio data from a unique track ID. Players send a single id parameter and expect your server to return a fully qualified URI to the track. The player uses the SOAP header to send credential information. See SOAP requests and responses and Streaming basics for details.

The player then issues an HTTP GET request for the music stream. If your server requires a list of HTTP headers and values, you can include them in the httpHeader object. The player will include these headers as part of the GET request.

Request parameters

Response

Best practices

Here are some best practices when implementing getMediaURI.

Use implicit and explicit actions to track user actions

We added implicit and explicit actions so that you track user actions on Sonos. For example, you can see whether the user chose to play a track, scrub through it (seek), skip forward, or skip back. If the user chose an action, it's called an explicit action. If the Sonos system chose an action, it's an implicit action. The one implicit action Sonos returns is when a player requests the audio stream URI. This happens most often when the player plays the next song in the queue.

You may want to receive these actions if you limit the number of devices that can stream your music at once. A Sonos Household counts as one device. Other devices might include a mobile phone, tablet, or computer. Turn this on with the "Support the ability to receive implicit or explicit actions for getMediaURI requests" capability. See Test your service for details.

Encrypt tracks for Digital Rights Management (DRM)

You can encrypt the tracks that Sonos accesses and provide decryption information to Sonos using fields in the getMediaURI response. See Encrypt content for details.

If you're sending audio using HLS, Sonos players send getContentKey requests for keys to decrypt individual segments. See HTTP Live Streaming (HLS) for details.

URIs should not expire before Sonos can finish playing

If you use expiring URIs (sometimes known as time-bomb URIs), you must ensure that the URI will not expire before Sonos can finish playing the content. Sonos cannot recover gracefully if the URI suddenly expires. Base the URI's expiration time on when your service responds to a getMediaURI request. If you get another getMediaURI request for the same ID, reset the URI's expiration time. This will help to ensure that the player has enough time to buffer and play the content. Do not base a URI's expiration on any other criteria. For example, do not use criteria such as, "the URI must be opened within X amount of time".

📘

Calculate the minimum URI expiration time as follows:

URI-expiration-time > track-duration + 30-minutes-paused + additional-listener-actions

The duration of a track and the Sonos player's buffer are factors when you set a URI expiration time. The Sonos player stores the URI's content in a buffer. The player rarely stores an entire track in the buffer. Since the player will likely need to access the URI's content more than once while the track plays, the URI expiration time must be greater than the track duration.

If the listener pauses for at least 30 minutes, the player will send a new getMediaURI request. A new request obtains a fresh URI from your service with a reset expiration time. To take into account a pause shorter than 30 minutes, the URI expiration time must add at least 30 minutes to the track duration.

Multiple pause and seek actions by the listener require additional expiration time that is impossible to predict. Ensure you add more to the URI expiration time to account for extra pause and seek actions.

Specify the encryption schema for AES-CBC encryption

For AES-CBC, specify the encryption schema using a colon between the key and initialization vector (IV). Both the key and IV should be in hexadecimal format. The number of characters in the key shall define the size of the key, so for example, a 128-bit decryption key will include 32 hex characters. The IV should always be 128-bits (32 hex characters). Valid key lengths are 128-bits (32-chars), 196-bits (48-chars), and 256-bits (64-chars).

Handling multiple getMediaURI requests

Sonos players make multiple getMediaURI requests when playing content, such as after a long pause, seeking position, or changing group coordinators. This does not mean that a new playback session has begun. The getMediaURIResult returned in response to getMediaURI should not change within a user's playback session. Players may behave poorly if the getMediaURIResult changes mid-stream. You can use values in Sonos requests to associate a current getMediaURI request to a previous getMediaURI request so that you can send the same getMediaURIResult. The values are:

• In the getMediaURI request:
  • X-Sonos-Playback-Id HTTP request header.
  • action parameter to indicate why the player is sending the call.
• In the POST /timePlayed request:
  • SMAPI track ID in the objectId.
  • Dereferenced media URL in the mediaUrl.
• SMAPI credentials header (see SOAP requests and responses for details):
  • zonePlayerId.
  • householdId in loginToken.

If you have an implementation that generates a unique getMediaURIResult responses for each request, you should develop an approach to determine if the getMediaURI request was a unique play or triggered by other reasons. For example:

1. Create a database by caching getMediaURI requests sent to Sonos players, using a key for each entry to identify a unique track in a session.
2. You can create the key by hashing the householdId, X-Sonos-Playback-Id, and objectId.
3. In each database entry, include the mediaUrl, zonePlayerId, and any other custom tokens specific to your integration.

Handling seek actions

When the getMediaURI action is EXPLICIT:SEEK, it indicates that the user scrubbed through the track. To handle this, look up the entry in the database and return the same mediaUrl returned in the first call.

When the action is not EXPLICIT:SEEK, return a brand new URL in all cases except when the zonePlayerId in the new getMediaURI request doesn’t match the one from the previous request. This exception handles situations when the music moves from one group coordinator to another.

If the zonePlayerId is different, the key remains the same, but the calling player is different (e.g., getMediaURI/credentials/zonePlayerId is not equal to database[key].zonePlayerId). The zonePlayerId records which player is currently managing the playback session. When Sonos sends the getMediaURI request, you can compare the zonePlayerId in the header with the value in the database entry for the previous getMediaURI request. If the values are different, it indicates that the user must have moved playback to another player. In this case you should record the new zonePlayerId in order to make the same comparison later, if the user moves the session again, as it could move multiple times.

Samples

Here are some sample requests and responses.

Sample request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <soap:Header>
   ...
  </soap:Header>
  <soap:Body>
    <ns:getMediaURI>
      <ns:id>track001</ns:id>
    </ns:getMediaURI>
  </soap:Body>
</soap:Envelope>

Sample request with implicit and explicit actions

<soap:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <soap:Header>
   ...
  </soap:Header>
   <soap:Body>
      <ns:getMediaURI>
         <ns:id>track001</ns:id>
         <ns:action>IMPLICIT</ns:action>
         <ns:secondsSinceExplicit>200</ns:secondsSinceExplicit>
      </ns:getMediaURI>
   </soap:Body>
</soap:Envelope>

Sample response

Your response would be the same for both sample requests above:

<soap:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soap:Body>
      <ns:getMediaURIResponse>
         <ns:getMediaURIResult>http://acme.example.com/music/track001.mp3</ns:getMediaURIResult>
      </ns:getMediaURIResponse>
   </soap:Body>
</soap:Envelope>

Sample response with custom HTTP headers

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://www.sonos.com/Services/1.1">
  <soap:Body>
    <ns:getMediaURIResponse>
      <ns:getMediaURIResult>
         http://acme.example.com/music/track001.mp3
      </ns:getMediaURIResult>
      <ns:httpHeaders>
        <ns:httpHeader>
          <ns:header>Referer</ns:header>
          <ns:value>acme.example.com</ns:value>
        </ns:httpHeader>
        <ns:httpHeader>
          <ns:header>Cookie</ns:header>
          <ns:value>a398mx02348n</ns:value>
        </ns:httpHeader>
      </ns:httpHeaders>
   </ns:getMediaURIResponse>
  </soap:Body>
</soap:Envelope>

Sample request for DRM

<soap:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
    <soap:Header>
        <ns:credentials>
            <ns:deviceId>A8-F9-32-B0-01-23:0</ns:deviceId>
            <ns:deviceCert>....</ns:deviceCert>
            <ns:zonePlayerId>B8-E9-37-C0-01-18:0</ns:zonePlayerId>
            <ns:deviceProvider>Sonos</ns:deviceProvider>
            <ns:loginToken>
              <ns:token>12345678</ns:token>
              <ns:key>123456789</ns:key>
            </ns:loginToken>
        </ns:credentials>
    </soap:Header>
   <soap:Body>
      <ns:getMediaURI>
         <ns:id>track*65220557</ns:id>
         <ns:action>IMPLICIT</ns:action>
         <ns:secondsSinceExplicit>200</ns:secondsSinceExplicit>
         <ns:deviceSessionToken>234567890-90</ns:deviceSessionToken>
      </ns:getMediaURI>
   </soap:Body>
</soap:Envelope>

Sample response for DRM

<soap:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <soap:Body>
    <ns:getMediaURIResponse>
      <ns:getMediaURIResult>https://mediacdn.example.com/1234567890123ABC.128.mp3?1a2b3c4d5e6f</ns:getMediaURIResult>
      <ns:deviceSessionToken>234567890-90</ns:deviceSessionToken>
      <ns:deviceSessionKey type="AES-ECB">FEDBCA9876543210FEDBCA9876543210</ns:deviceSessionKey>
      <ns:contentKey type="AES-CBC">0123456789ABCDEF0123456789ABCDEF:FEDBCA9876543210FEDBCA9876543210</ns:contentKey>
    </ns:getMediaURIResponse>
  </soap:Body>
</soap:Envelope>