The loadStreamUrl command in the playbackSession namespace loads a streaming (live) radio station URL and optionally starts playback. Upon successful completion, the player sends a playbackStatus event to your app or hardware integration. Your app should subscribe to the playback namespace before sending the loadStreamUrl command to avoid race conditions in receiving playbackStatus or playbackError events.
This command requires that your app has an open playback session with a cloud queue, created or joined using the createSession, joinSession, or joinOrCreateSession command.
If you want to immediately start playing the stream, set the playOnCompletion parameter to true. This bypasses the need to send a play command after the player loads the stream.
Note: Use this command to load a live stream that does not end. Use loadCloudQueue to load a set list of tracks or a playlist.
Endpoint
POST
|
1 |
/playbackSessions/{sessionId}/playbackSession/loadStreamUrl |
Request Parameters
This command requires a sessionId to determine the target of the command. See the Control documentation for details.
See the table below for descriptions of parameters in the body.
| Parameter | Type | Value |
|---|---|---|
itemId |
string | (Optional) If provided, the player includes this itemId in subsequent playbackStatus and playbackError events corresponding to this stream. |
streamUrl |
string | HTTP URL for the radio station stream. See the supported content types below. Note that you cannot use this command to send an on-demand track for playback. |
playOnCompletion |
boolean | (Optional) If true, the player will start playback after loading the stream URL. If false or not provided, the player remains in the PLAYBACK_IDLE state. |
stationMetadata |
container | (Optional) Metadata about the radio station. See below for details. |
Response
Returns an empty body with a success value of true if successful.
The player generates a metadataStatus event for the loaded stream. Your app receives this event notification if subscribed to the playbackMetadata namespace.
The player also generates a playbackStatus event if the playback state was changed. Your app also receives this notification if it is subscribed to the playback namespace.
If the player can’t load the streamUrl, it will send an asynchronous playbackError event.
Supported Content Types
You can send any HTTP URL as a custom radio station that you can add using the Add Radio Station feature on the Sonos app.
This includes playlist files containing URLs pointing to encoded audio streams. For example, .m3u, .m3u8, .pls, .wpl and .asx files with URLs to streams encoded using mp3 or ADTS/ALAC AAC or HLS AAC.
The stream URL may be a direct URL to an mp3 or HLS (AAC) stream. The URL may also be an MMS and RTSP URL for WMA-encoded audio. You cannot use this command to send an on-demand track for playback.
See Supported audio formats for more details about file formats supported by Sonos players.
Example
Request
|
1 2 3 4 5 6 7 8 |
{ "streamUrl": "http://www.example.com/a/f/3/acme_104.pls", "playOnCompletion": true, "stationMetadata": { "name": "Acme 104 Rockin' Radio" }, "itemId" : "StreamItemId" } |
Error
|
1 2 3 4 |
{ "itemId" : "StreamItemId" "errorCode": "ERROR_INVALID_OBJECT_ID" } |
Metadata Status Event
|
1 2 3 4 5 6 |
{ "container": { "type": "station", "name": "Acme 104 Rockin' Radio" } } |