How To Play Soundcloud On Sonos

Your app can use a cloud queue hosted on your server to play a dynamic list of tracks on a group of Sonos players. Players will keep to play and fetch new tracks from the cloud queue even after your app has left the network, and any changes to the list of tracks will still be reflected on Sonos.

The Control API defines the protocol between your app and the thespian, the Cloud Queue API defines the advice between players and your cloud queue server. Meet the Deject Queue API for the latest version number.

Players call the Cloud Queue API to get data to stream content from your media server. And so players stream content over HTTP from your media server using the MusicObjectId. This diagram simplifies the communication. Encounter account matching for details.

What is a cloud queue?

A cloud queue is a listing of audio tracks in the cloud that tin be loaded and played in a playback session on a group of players. Meet Playback Sessions for details.

After your app has created a new playback session or joined an existing playback session on a group, it tin instruct a group to load a cloud queue. Once loaded, players request a window of tracks from the cloud queue. Changes to the queue are sent to players when they request a new window, either explicitly or at ready intervals.

The player gets the kickoff rail and a window of additional tracks and begins playing. Once the player gets close to reaching the end of the window, or after a set amount of fourth dimension, the player requests another window. This continues until the window includes the last track in the cloud queue, or until playback is stopped.

Tracks in the cloud queue

Each track in the deject queue has a unique itemId that identifies that particular track in that particular queue. If the same rails appears twice in a queue, each example has a unlike itemId value. The itemId values should never be re-used. The simplest way to implement an itemId is to generate a new Globally Unique Identifier (GUID) for each rails as information technology is added to a deject queue.

Each rails in the cloud queue has all the standard metadata that is needed to fetch the audio for the track. This may include either a mediaUrl (the URL to the actual audio) or a MusicObjectId. If an particular contains both of these objects, Sonos ignores the mediaUrl. This is because the MusicObjectId resolves to a URL using SMAPI. Run across MusicObjectId and business relationship matching for details.

Each track should also include the contentType (also called the MIME type or media type) for the sound. See the playback object cloud queue inputs for details.

Each track has the standard metadata to display a basic "At present Playing" screen for that rails:

track name
artist proper noun
anthology proper noun
album art image URL
track duration

Run into Supported sound formats for the file formats supported by Sonos Players.

A cloud queue use case

Players employ a sliding window technique to fetch tracks from your cloud queue. This is described in the use case beneath.

Typically, you would map an existing list of tracks on your server, such equally a playlist, to a cloud queue. Let'south say you lot take a playlist of 100 tracks. A user on your app starts playing the playlist from track 65.

Your app start needs to create or join an existing session on a grouping of players with one of the createSession, joinSession or joinOrCreateSession Command API commands. The session grants your app control of what is playing on a group of players. See Playback Sessions for details. If your app is creating a new session, ship the accountId to tell the player which account it should use for playback. The player verifies that the accountId matches a stored account. If the accountId does not match, you'll receive an ERROR_INVALID_PARAMETER error.

One time connected to a session, your app sends a loadCloudQueue Command API command to load the cloud queue on the group, centered on rails 65. Your app can optionally provide metadata for track 65, and instruct the player to beginning playing immediately, earlier it connects to the cloud queue server. This optimization allows for shorter time-to-music for the user.

The player loads metadata for track 65 and starts playing information technology on the group of players. Next, the role player sends a
Become /context request to get the container metadata, playback policies, and reporting options from your cloud queue server. Then, the player fetches a window of xx tracks from the cloud queue with the GET /itemWindow Cloud Queue API, centered around track 65 (tracks 56-75). Information technology uses that information to play the tracks in sequence.

When playback continues without interruption and gets close to the stop of the window, for example, rail 72, the role player fetches a new window of tracks centered around the currently playing rails.

To let for gapless playback, the thespian will always have plenty tracks ahead to buffer the audio.

If your app sends a play command when the deject queue is empty, the player will attempt to resume playback of content that was playing prior to this command. For example, if the user was previously listening to a radio station or had a playlist queued, information technology volition attempt to resume playback of that content.

Your app tin enable users to perform the post-obit deportment on the deject queue using Control API commands:

Navigate forrad and backward using the skipToNextTrack and skipToPreviousTrack commands.
Seek to a position within a rail using the seek command.
Spring directly to a given track in the cloud queue using the skipToItem command.

Cloud queue workflow

The following workflow shows an overview of the cloud queue use case described in a higher place.

Workflow details

Your app uses SSDP to discover Sonos players and groups.
A Sonos player sends a unicast response.
Your app connects to a Sonos histrion using a secure WebSocket.
The thespian sends an HTTP 101 response and provides a WebSocket URL in the WEBSOCK.SMARTSPEAKER.Sound header.
Your app sends a lucifer command to the player to match the account in your app with one already saved on the actor. In this command, your app provides a hashed user ID, a nickname for the business relationship, your service ID, and alinkCode. See Account matching for details.
The player uses the hashed user ID to lucifer the account to one that it has stored. If it doesn't find a match, the actor creates a invitee business relationship. The player sends a response to your app that includes the Sonos account ID and indicates whether or not it's a invitee account.
To control players, start or join a session using thecreateSession,joinSession, or createOrJoinSession command in theplaybackSession namespace. If creating a new session (createSession or createOrJoinSession), your app provides the accountId to indicate which account to apply for playback in the session.
The player sends a sessionStatus object as a response. This object indicates whether the session was newly created or if it already existed.
A user browses your app and chooses a playlist of 100 tracks. The user chooses to play track 65. Your app sends a loadCloudQueue control to the player. This command includestrackMetadata for track 65 and the playOnCompletion parameter is prepare to true. The trackMetadata includes the musicObjectId for this track.
The player returns an empty body with a "success" value of true.
The actor uses the musicObjectId fromtrackMetadata to send getMediaURI to request the URI for rails 65 from your SMAPI server.
Your SMAPI server returns the URI for the runway audio in your getMediaURI response.
The histrion uses the media URI to ship a Get request to your content delivery network (CDN) for the track audio.
Your CDN returns the track audio to the actor.
The player starts playback. The player disables most playback capabilities until it can send Go /context and
GET /itemWindow and process your responses.
The player sends a Go /context asking to your cloud queue server.
Your cloud queue server responds to the GET /context asking. Your response includes container metadata, playback policies, and reporting options.
The histrion sends a GET /itemWindow request to your cloud queue server. The histrion uses the itemId for track 65 to request a window around this rails, specifically tracks 56-75. ThepreviousWindowSize parameter is ready to "9" to request tracks 56-64, and the upcomingWindowSize is set to "10" to asking tracks 66-75.
Your server responds to the Go /itemWindow request with metadata for tracks 56-75.
Playback continues without break. The player sends a GET /itemWindow request to refresh the window as information technology gets shut to the end of the current window. The thespian updates the new window around the track that is currently playing.

Players poll the deject queue on a regular basis

Players poll the cloud queue with Go /version on a regular footing. They practice so to determine if the cloud queue changed the list of tracks or updated the state of container types, metadata, or playback policies. This background polling occurs at regular intervals. Groundwork polling intervals are dissimilar when the group is playing and paused. When paused, players poll the cloud queue every 5 minutes. When playing, players poll the cloud queue every 10 minutes.

Additionally, players fetch new tracks equally needed using GET /itemWindow. The role player requires a version in your response, so it'due south not necessary for the thespian to transportGo /version in this case. After the player gets a new item window, it resets the polling interval to some other ten minutes.

Your app can tell players to immediately poll the cloud queue

Your app tin use the refreshCloudQueue Control API control to tell the player to immediately fetch an updated window of tracks from the server. You may desire to do this if, for example, a user deleted the current track. This avoids the delay the user might feel if the player waited until the next poll interval.

Players retry unsuccessful deject queue requests

Players retry background cloud queue requests such equally GET /context, Go /itemWindow, and GET /version when they receive an unexpected response. Unexpected responses include:

WebSocket request timeouts
aborted WebSockets
players tin can't connect
players can't resolve the Domain Name Arrangement (DNS)
unexpected HTTP response codes

When this happens, players retry the asking up to three times. This results in four total attempts, including the original asking. Players expect ten seconds afterwards the original request to retry and and then another 10 seconds earlier each retry.

If the player uses all the retries without a successful response, it will play what it has left in the current itemWindow and then enter a pause state. The player keeps the playback session valid when this happens.

Players send API requests over HTTPS

All Deject Queue API requests from players to cloud queue servers will be over HTTPS.

SSL connection establishment adds boosted overhead and latency. To reduce this overhead of the SSL handshake, session resumption is used. Players support the Session ID-based resumption machinery, as defined in the TLS 1.0 RFC 2246.

Server certificate verification

Be sure that the root certificate used to sign the server document presented past your cloud queue servers is a well-known trusted CA.

Authority for media and the cloud queue

Access tokens (such as OAuth tokens) can be used as the potency machinery to allow users access to playing sound resources on media servers, and to allow players admission to the rails metadata on the deject queue server. Your app can pass an access token to the player with an "Authorisation" HTTP header in the httpAuthorization parameter of the loadCloudQueue Command API command. The thespian will utilise the access token when playing whatsoever sound tracks on the cloud queue, and when calling the Cloud Queue APIs.

HTTP Request Header	Header Value
Authorization	<long-auth-token-string>

Since access tokens expire, you can return a "10-Updated-Authorization" HTTP header to the player from your cloud queue or media server, which updates the token that the histrion should employ in subsequent requests. This is the mechanism by which your cloud queue server or your media server can car-refresh the access token used past the actor to ensure that playback continues indefinitely if it is not paused past the user. By following this exercise, the user will never take to manually re-authenticate during playback of an arbitrarily long deject queue, as long every bit playback is non interrupted.

HTTP Response Header	Header Value
X-Updated-Potency	<long-auth-token-cord>

If provided, the Sonos players will always include the HTTP "Authorization: httpAuthorization" header whenever they make requests to your Cloud Queue APIs. They volition also send them when they request the resources for cloud queue items from your media servers.

Note that you could utilize the HTTP Authorization data in your cloud queue server to infer the user account or queue identifier in order to render the appropriate deject queue instance information. Run into Communicate user identity in the base URL for another method of doing this.

Unique string for the lifetime of the playback session

Yous may want to differentiate deject queue instances that are simultaneously serving the aforementioned household. For example, in Harry and Sally'southward household, this would enable Harry to use his account on your service in the kitchen and Sally to utilize her account on your service in the den. To enable this, the player provides a unique string for the lifetime of the playback session the "X-Sonos-Playback-Id" HTTP request header.

HTTP Asking Header	Header Value
X-Sonos-Playback-Id	Unique string that is constant for the lifetime of the playback session.

The string may or may non alter later on your app or implementation loads a cloud queue. The value remains constant if the music is moved to a different thespian within the Sonos controller.

Cloud queue base URL and API version

The base URL identifies your deject queue. It should consist of a URL with the version at the end. The version volition allow players to but use newer Cloud Queue API functionality when your service supports it. For example:

https://www.example.com/musicqueue/v2.1/

You can also communicate the user identity in the base URL. See below for details.

Some guidelines around the Cloud Queue API Version:

Following the Semantic Versioning specification, the base URL must finish with "/v<MAJOR>.<Small-scale>[/]".
We increment the MAJOR version when incompatible changes are made.
We increment the Small version when backward compatible changes are made, such as new response information with no new resources.
We practice not utilise a PATCH digit; the player will parse, but ignore the PATCH digit.
The player will parse, but ignore any pre-release and build metadata. For example, the player will consider "1.0.0-blastoff.i" and "1.0.0-beta+exp.sha.5114f85" both every bit version 1.0.
The trailing slash is optional. Information technology is allowed simply non required as part of the base URL.

To tell Sonos which cloud queue to play, your app must pass the base URL and version in thequeueBaseUrl parameter of the loadCloudQueue Control API command. Run into the Cloud Queue API for the latest version number.

The current version of the Deject Queue API is v2.1. Nosotros as well marking the changes to each endpoint in the documentation past calling out features and parameters as "Added in 5#.#". We list the previously supported features below the near recently supported version.

Communicate user identity in the base URL

Other than the version specification described in a higher place, the form of the base of operations URL is upward to you lot. For example, it could exist a different URL with the user account or queue identifier encoded equally a RESTful parameter for each cloud queue instance. For instance:

http://www.example.com/cloudqueue/1243328192349892/v2.0/

Alternatively, information technology could be a fixed URL where you differentiate the actual cloud queue data based on the httpAuthorization.

Employ tombstones for deleted tracks

When a user deletes a track from your cloud queue, you should use a tombstone to flag it as deleted. This will enable you lot to keep track of its position in the cloud queue so that when the player requests a window centered around this deleted track, the cloud queue can then decide the next track and return a window centered effectually that track instead. This enables a smooth user feel during playback.

To gear up a tombstone on a rails, set the deleted item property equally truthful when your deject queue server returns the item as a response to a GET /itemWindow Cloud Queue API request.

Your server should maintain tombstone information for deleted tracks until the player has fourth dimension to fetch a new window with a GET /itemWindow request. The length of this time depends on the length of the tracks in the window and the time it takes for the player to sync upward with your deject queue. We recommend maintaining tombstone information for a few hours. The player will e'er pass the itemId of the track that is currently playing.

At that place is no mechanism for players to mind for notifications from cloud queues when there is a change in the queue. Then, in lodge to ensure players are responsive when the user deletes the currently playing track, your app should send a refreshCloudQueue Control API command to the player to asking that the actor immediately fetch an updated window of tracks. The player will fetch an updated window of tracks containing a tombstone for the track that was deleted. It volition stop playing the current track and go on to play the rails subsequently the deleted track.

Source: https://developer.sonos.com/build/content-service-get-started/play-audio/