v0.6 (2015-04-11)

--  bug fix: error while restoring a playlist
--  fixed a resource leak (thx @hoggle)
--  commands added: set_wifi_state, get_wifi_state
    --  now you can activate or deactivate the speakers wireless network interface 
        (e.g. if you use the speaker with an ethernet connection)
    --  commands integrated in sonos command line client 
--  some changes handling event subscriptions
--  increased event subscription period to 240 sec
--  new command: RefreshMediaLibrary (updates / refreshs the media library)
    --  RefreshMediaLibrary added to sonos command line client
--  bug: parsing error while playing some radio stations
--  added radio parser for Alsterradio 106.8
--  some minor bugfixes in Sonos Broker
--  some minor bugfixes in Cmd client

v0.5.2 (2015-02-01)

--  set new auto-renew timer for event subscription, more debug logs 
--  set scan interval to 180 sec as default value

v0.5.1 (2015-01-23)

--  Hotfix: error while handling a DIDL item (in SoCo framework)

v0.5 (2015-01-18)

--  interactive command shell added to interact with the speakers directly (see docu)
--  commands added: get_playlist, set_playlist (see documentation). Its now possible to
    save and set the playlist for a speaker / zone.
--  commands added: 'is_coordinator'[readonly], 'tts_local_mode'[readonly]: please 
    read the documentation
--  changed some strings to clarify, that a non-existing or broken GoogleTTS 
    configuration disables only the 'local mode'; the 'streaming mode' is always 
    available
--  changed the 'client_list'command: only the uids will be shown
--  bugfix: error during processing a Spotify track
--  bugfix: an error occurred, if the Broker was started with the '-l' parameter and a 
    previous online speaker went offline
--  changed logging handler in daemon.py to global logging handler specified in the 
    config file
--  new SoCo version     
--  new start option "-l"
    --  this options lists all available Sonos speaker in the network. 
        This is helpful to get the speakers UIDs.

The shSonos project is Sonos control server, mainly based on the brilliant SoCo project (https://github.com/SoCo/SoCo). It implements a lightweight http server, which is controlled by simple HTTP json commands. It sends all available Sonos speaker data to all subscribed clients and notifies them of all changes.

The Sonos Broker implements some nice additional features like GoogleTTS, saving/restoring the playlist, maximum volume settings for each Sonos speaker and much more.

In addition , i decided to write a plugin for the fantastic "Smarthome.py Project" to control Sonos speakers in a smart home environment (https://github.com/mknx/smarthome/).

Server: python3 (with library 'requests')

Client-side: nothing special, just send your commands over http (JSON format) or use the Smarthome.py plugin to control the speakers within Smarthome.py.

Under the github folder "server.sonos/dist/" you'll find the actual release as a tar.gz file. Unzip this file with:

tar -xvf sonos_broker_release.tar.gz

(adjust the filename to your needs)

Go to the unpacked folder and run setup.py with:

sudo python3 setup.py install

This command will install all the python packages and places the start script to the python folder "/user/local/bin"

Make the file executable and run the sonos_broker with:

chmod +x sonos_broker
./sonos_broker

Normally, the script finds the internal ip address of your computer. If not, you have to edit your sonos_broker.cfg.

[sonos_broker]
server_ip = x.x.x.x

(x.x.x.x means your ip: run ifconfig - a to find it out)

You can edit the settings of Sonos Broker. Open 'sonos_broker.cfg' with your favorite editor and edit the file. All values within the config file should be self-explaining. For Google-TTS options, see the appropriate section in this Readme.

If you start the sonos broker with

sonos_broker

the server will be automatically daemonized.

You can add the -d (--debug) parameter to hold the process in the foreground.

sonos_broker -d

You can stop the server with

sonos_broker -s

To get a short overview of your speakers in the network start the server with

sonos_broker -l

To get an overview of all parameters type

sonos_broker -h

To autostart the service on system boot, please follow the instruction for your linux distribution and put this script in the right place.

To get some debug output, please edit the sonos_broker.cfg and uncomment this line in the logging section (or use the -d start parameter):

loglevel = debug

You can set the debug level to debug, info, warning, error, critical. Additionally, you can specify a file to pipe the debug log to this file.

logfile = log.txt

You can control the Broker and your speakers without implementing your own client. To start the interactive command line (the Broker must be running) type

./sonos_cmd

in the root folder of the Sonos Broker.

With the

help

command you can show up all options.

Within the shell type

update

to get all the speakers in the network.

Type

list

or

speaker

to show all available speakers.

To interact with one of these speakers type

speaker [number of the speaker]

Now you should see the uid of the speaker as the command line prompt. Type

help

for all available commands. All of them are interactive and self-explaining.

An

exit

redirects you to the first command line level.

Sonos broker features the Google Text-To-Speech API. You can play any text limited to 100 chars.

• local / remote mounted folder or share with read/write access
• http access to this local folder (e.g. /var/www)
• settings configured in sonos_broker.conf

If a text is given to the google tts function, sonos broker makes a http request to the Google API. The response can be 1. stored as a mp3-file to the local / remote folder. 2. or handled like a radio stream without saving the file locally.

The first option should always be the preferred one. The "radio stream" option has some big disadvantages (time delay, no snippet length and therefor inaccurate track resuming). If Google TTS is disabled (either by disabling Google TTS in the sonos_broker.cfg or other failures), the stream mode is assumed. You can force this behaviour by setting the command parameter 'force_stream_mode' to 1 (see play_tts command).

Before the request is made ('local mode'), the broker checks whether a file exists with the same name. The file name of a tts-file is always: BASE64(<tts_txt>_<tts_language>).mp3 You can set a file quota in the config file. This limits the amount of disk space the broker can use to save tts files. If the quota exceeds, you will receive a message. By default the quota is set to 100 mb.

sonos_broker.cfg:

[google_tts]
quota = 200

By default, Google TTS support is disabled. To enable the service, add following line to sonos_broker.cfg:

sonos_broker.cfg:

[google_tts]
enable = true

You have to set the local save path (where the mp3 is stored) and the accessible local url:

sonos_broker.cfg

[google_tts]
save_path =/your/path/here
server_url = http://192.168.0.2/tts

This is an example of a google_tts section in the sonos_broker.cfg file:

[google_tts]
enable=true
quota=200
save_path =/your/path/here
server_url = http://192.168.0.2/tts

For raspberry pi user, please follow these instruction prior the Broker installation:

sudo apt-get update
sudo apt-get upgrade
sudo easy_install3 requests

Because of the server-client design, you're not bound to Python to communicate with the Sonos broker instance. You just have to implement a client which is listening on an open UDP port to receive Sonos speaker status changes. To control the server your client has to send JSON commands. At this moment there is no dedicated web interface. (maybe this is your contribution :-) ). You can find a sonos widget for smartVISU / Smarthome.py here:

https://github.com/pfischi/shSonos/tree/develop/widget.smartvisu

To subscribe your client to the Broker, simply send the appropriate JSON command(this step is not necessary for smarthome.py-plugin user, it's done automatically). Use this command to unsubscribe.

After subscription, your client will receive all status updates of all sonos speakers in the network, whether they were triggered by you or other clients (iPad, Android). The received data comes in a JSON format and looks like this:

In almost any cases, you'll get the appropriate response in the following JSON format (by udp):

{
    "additional_zone_members": "rincon_112ef9e4892e00001",
    "alarms": {
        "32": {
            "Duration": "02:00:00",
            "Enabled": false,
            "IncludedLinkZones": false,
            "PlayMode": "SHUFFLE_NOREPEAT",
            "Recurrence": "DAILY",
            "StartTime": "07:00:00",
            "Volume": 25
        }
    },
    "bass": 0,
    "hardware_version": "1.8.3.7-2",
    "ip": "192.168.0.4",
    "led": 1,
    "loudness": 1,
    "mac_address": "10:1F:21:C3:77:1A",
    "max_volume": -1,
    "model": "Sonos PLAY:1",
    "mute": "0",
    "pause": 0,
    "play": 0,
    "playlist_position": 0,
    "playmode": "normal",
    "radio_show": "",
    "radio_station": "",
    "serial_number": "00-0E-58-C3-89-2E:7",
    "software_version": "27.2-80271",
    "status": true,
    "stop": 1,
    "streamtype": "music",
    "track_album_art": "http://192.168.0.4:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a3xCk8npVehdV55KuPdjrmZ%3fsid%3d9%26flags%3d32",
    "track_artist": "Feuerwehrmann Sam & Clemens Gerhard",
    "track_duration": "0:10:15",
    "track_position": "00:00:00",
    "track_title": "Das Baby im Schafspelz",
    "track_uri": "x-sonos-spotify:spotify%3atrack%3a3xCk8npVehdV55KuPdjrmZ?sid=9&flags=32",
    "treble": 0,
    "uid": "rincon_000e58c3892e01410",
    "volume": 8,
    "zone_icon": "x-rincon-roomicon:bedroom",
    "zone_name": "Kinderzimmer"
}

Please notice: the Broker sends only new or changed data to the clients. In most case you'll ge only a subset of the data shown above. To force the Broker to send all data, your client have to trigger the current_state command.

To put it in a nutshell: code your own client (Python, Perl, C#...) with an open and listening UDP port and subscribe your client to the Sonos Broker. Send JSON commands to control your Sonos speaker(s).

Most of the commands need a speaker uid. Start the Sonos Broker with the argument '-l to get a short overview of your sonos speakers in the network and to retrieve the uid. You can also perform a sonos client_list command.

Here you can find a client implementation for the Broker. It is a sonos plugin for the Smarthome.py home automation framework.

Click on the links below to get a detailed command descriptions and their usage.

Subscribes a client to the Sonos Broker. After the subscription, the client will receive all status changes from the Sonos speakers in the network.

######Example JSON format: { 'command': 'client_subscribe', 'parameter': { 'ip': '192.168.0.2', 'port': 2333 } }

######HTTP Response HTTP Response: no additional data Response Code: 200 OK or Exception with Code 400 and the specific error message.

Unsubscribes a client from the Broker. After unssubscription the client will not longer receive status changes from the Sonos speakers. If your're running more than one client with the same IP but with different ports, only the client with the specific port will be unsubscribed.

######Example JSON format: { 'command': 'client_unsubscribe', 'parameter': { 'ip': '192.168.0.2', 'port': 2333 } }

######HTTP Response HTTP Response: no additional data Response Code: 200 OK or Exception with Code 400 and the specific error message.

Shows all available Sonos speaker in the network.

No special parameter needed.

######Example JSON format: { 'command': 'client_list' }

######HTTP Response HTTP Response: <title>Sonos Broker</title> rincon_000e58c3892e01410\nrincon_b8e93730d19801410\n ... [uids]

Response Code: 200 OK or Exception with Code 400 and the specific error message.        

Gets the 'play' status for a Sonos speaker. If the speaker has additional zone members, the 'play' status for all members will be sent. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'play'-status changes.

######Example JSON format: { 'command': 'get_play', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "play": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the PLAY status for a Sonos speaker. If the speaker has additional zone members, the 'play' status for all members will be set (this is the Sonos standard behavior).

######Example JSON format: { 'command': 'set_play', 'parameter': { 'play': 1, 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "play": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the 'pause' status for a Sonos speaker. If the speaker has additional zone members, the 'pause' status for all members will be sent. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'pause'-status changes.

######Example JSON format: { 'command': 'get_pause', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "pause": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the 'pause' status for a Sonos speaker. If the speaker has additional zone members, the 'pause' status for all members will be set (this is the Sonos standard behavior).

######Example JSON format: { 'command': 'set_pause', 'parameter': { 'pause': 1, 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "pause": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the 'stop' status for a Sonos speaker. If the speaker has additional zone members, the 'stop' status for all members will be sent. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'stop'-status changes.

######Example JSON format: { 'command': 'get_stop', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "stop": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the 'stop' status for a Sonos speaker. If the speaker has additional zone members, the 'stop' status for all members will be set (this is the Sonos standard behavior).

######Example JSON format: { 'command': 'set_stop', 'parameter': { 'stop': 1, 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "stop": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current volume from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'volume'-status changes.

######Example JSON format: { 'command': 'get_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "volume": [0-100], "uid": "rincon_b8e93730d19801410", ... }

Sets the volume for a Sonos speaker.

######Example JSON format: { 'command': 'set_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'volume': 25, 'group_command': 0 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "volume": [0-100], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the maximum volume value from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'max_volume'-status changes.

######Example JSON format: { 'command': 'get_max_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "max_volume": [-1 - 100], "uid": "rincon_b8e93730d19801410", ... }

Sets the maximum volume for a Sonos speaker. This also affects any volume changes performed on other devices (Android, iPad). If the volume is greater than the maximum volume, the volume is changed to this maximum volume value.

######Example JSON format: { 'command': 'set_max_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'max_volume': -1, 'group_command': 1 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "max_volume": [-1 - 100], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the mute status from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'mute'-status changes.

######Example JSON format: { 'command': 'get_mute', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "mute": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Mutes or unmutes a Sonos speaker.

######Example JSON format: { 'command': 'set_mute', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'mute': 1, 'group_command': 0 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "mute": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Increases the volume of a Sonos speaker by +2.

######Example JSON format: { 'command': 'volume_up', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'group_command': 0 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "volume": [0 - 100], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Decreases the volume of a Sonos speaker by -2.

######Example JSON format: { 'command': 'volume_down', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'group_command': 0 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "volume": [0 - 100], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Go to the next track in the current playlist.

######Example JSON format: { 'command': 'next', 'parameter': { 'uid': 'rincon_b8e93730d19801410', }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "track_album_art": "http://192.168.0.4:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a1AGslpGIhRzXSOYtE52VcB%3fsid%3d9%26flags%3d32", "track_artist": "Willi Röbke", "track_duration": "0:10:16", "track_position": "0:00:10", "track_title": "Steuermann Norman", "track_uri": "x-sonos-spotify:spotify%3atrack%3a1AGslpGIhRzXSOYtE52VcB?sid=9&flags=32", "uid": "rincon_000e58c3892e01410", ... }

All values for a new track will be sent, but only new and/or different values.

Go back to the previous track in the current playlist.

######Example JSON format: { 'command': 'previous', 'parameter': { 'uid': 'rincon_b8e93730d19801410', }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "track_album_art": "http://192.168.0.4:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a1AGslpGIhRzXSOYtE52VcB%3fsid%3d9%26flags%3d32", "track_artist": "Willi Röbke", "track_duration": "0:10:16", "track_position": "0:00:10", "track_title": "Steuermann Norman", "track_uri": "x-sonos-spotify:spotify%3atrack%3a1AGslpGIhRzXSOYtE52VcB?sid=9&flags=32", "uid": "rincon_000e58c3892e01410", ... }

All values for a new track will be sent, but only new and/or different values.

Gets the current bass settings from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'bass'-status changes.

######Example JSON format: { 'command': 'get_bass', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "bass": [-10 - 10], "uid": "rincon_b8e93730d19801410", ... }

Sets the bass for a Sonos speaker.

######Example JSON format: { 'command': 'set_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'bass': 5, 'group_command': 0 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "bass": [-10 -10], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current treble settings from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'treble'-status changes.

######Example JSON format: { 'command': 'get_treble', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "treble": [-10 - 10], "uid": "rincon_b8e93730d19801410", ... }

Sets the treble for a Sonos speaker.

######Example JSON format: { 'command': 'set_volume', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'treble': 1, 'group_command': 1 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "treble": [-10 - 10], "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current loudness settings from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'loudness'-status changes.

######Example JSON format: { 'command': 'get_loudness', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "loudness": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the loudness for a Sonos speaker.

######Example JSON format: { 'command': 'set_loudness', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'loudness': 1, 'group_command': 1 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "loudness": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current led status from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'led'-status changes.

######Example JSON format: { 'command': 'get_led', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "led": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the led for a Sonos speaker.

######Example JSON format: { 'command': 'set_led', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'led': 1, 'group_command': 1 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "led": 0|1, "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current playmode from a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'playmode'-status changes.

######Example JSON format: { 'command': 'get_playmode', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "playmode": 'normal' | 'shuffle_norepeat' | 'shuffle' | 'repeat_all' "uid": "rincon_b8e93730d19801410", ... }

Sets the playmode for a Sonos speaker.

######Example JSON format: { 'command': 'set_playmode', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'playmode': 'shuffle' }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "playmode": 'normal' | 'shuffle_norepeat' | 'shuffle' | 'repeat_all' "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Gets the current track position. To get a real-time track position ( e.g. for a GUI) you have to poll this function manually and frequently with the 'force_refresh = 1' option since there is no automatism from the Sonos API side.

######Example JSON format: { 'command': 'get_track_position', 'parameter': { 'uid': 'rincon_b8e93730d19801410' 'force_refresh': 1 } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "track_position": "00:02:14", "uid": "rincon_b8e93730d19801410", ... }

Moves the currently playing track a given elapsed time.

######Example JSON format: { 'command': 'set_playmode', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'timestamp': '00:01:12' }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "track_position": "00:02:14", "uid": "rincon_b8e93730d19801410", ... }

The response is only sent if the new value is different from the old value.

Returns the title of the currently played track. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'track_title'-status changes.

######Example JSON format: { 'command': 'get_track_title', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "track_title": "Ordinary Love", "uid": "rincon_b8e93730d19801410", ... }

Returns the artist of the currently played track. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'track_artist'-status changes.

######Example JSON format: { 'command': 'get_track_artist', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "track_artist": "U2", "uid": "rincon_b8e93730d19801410", ... }

Returns the album-cover url of the currently played track. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'track_album_art'-status changes.

######Example JSON format: { 'command': 'get_track_album_art', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "track_album_art": "http://192.168.0.23:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a7kCrYUDtWsPldoh\OKPTKPL%3fsid%3d9%26flags%3d32", "uid": "rincon_b8e93730d19801410", ... }

Returns the track url of the currently played track. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'track_uri'-status changes.

######Example JSON format: { 'command': 'get_track_uri', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "track_uri": "x-sonos-spotify:spotify%3atrack%3a7kCrYUDtWsPldohOKPTKPL?sid=9&flags=32", "uid": "rincon_b8e93730d19801410", ... }

All URIs can be passed to the play_uri and play_snippet functions.

Returns the title of the currently played radio station. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'radio_station'-status changes.

######Example JSON format: { 'command': 'get_radio_station', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "radio_station": "radioeins vom rbb", "uid": "rincon_b8e93730d19801410", ... }

Returns the title of the currently played radio show. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'radio_show'-status changes.

######Example JSON format: { 'command': 'get_radio_show', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... "radio_show": "Die Profis", "uid": "rincon_b8e93730d19801410", ... }

Joins a Sonos speaker to another speaker(s).

######Example JSON format: { 'command': 'join', 'parameter': { 'uid': 'rincon_b8e93730d19801410' 'join_uid': 'rincon_00e33110q27811000' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... [many value here, see current_state command] ... }

After a successfully join, the complete metadata for all speakers in the group
wil be sent to all subscribed clients. This is exactly the same behavior for
a single speaker if a current_state command is triggered. 

Unjoins a Sonos speaker from a group.

######Example JSON format: { 'command': 'unjoin', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... [many value here, see current_state command] ... }

After a successfully unjoin, the complete metadata for the speaker wil be sent to 
all subscribed clients. This is exactly the same behavior if a current_state 
command is triggered. 

Joins all Sonos speaker in the network to one group.

######Example JSON format: { 'command': 'partymode', 'parameter': { 'uid': 'rincon_b8e93730d19801410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: {
... [many value here, see current_state command] ... }

After a successfully 'partymode' command, the complete metadata for all speakers 
in the group wil be sent to all subscribed clients. This is exactly the same behavior 
for a single speaker if a current_state command is triggered.

Plays a track or a music stream by URI.

######Example JSON format: { 'command': 'play_uri', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'uri': 'x-sonos-spotify:spotify%3atrack%3a1AGslpGIhRzXSOYtE52VcB?sid=9&flags=32'

        # external url: http://www.tonycuffe.com/mp3/tail%20toddle.mp3
        # internal sonos url: x-sonos-spotify:spotify%3atrack%3a3xCk8npVehdV55KuPdjrmZ?sid=9&flags=32
    }   
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "track_album_art": "http://192.168.0.4:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a1AGslpGIhRzXSOYtE52VcB%3fsid%3d9%26flags%3d32", "track_artist": "Willi Röbke", "track_duration": "0:10:16", "track_position": "0:00:10", "track_title": "Steuermann Norman", "track_uri": "x-sonos-spotify:spotify%3atrack%3a1AGslpGIhRzXSOYtE52VcB?sid=9&flags=32", "uid": "rincon_000e58c3892e01410", ... }

All values for a new track will be sent, but only new and/or different values.

Plays a audio snippet. After the snippet was played (maximum 60 seconds, longer snippets will be truncated) the previous played song will be resumed. You can queue up to 10 snippets. They're played in the order they are called.

######Example JSON format: { 'command': 'play_snippet', 'parameter': { 'uid': 'rincon_000e58c3892e01410', 'uri': 'x-sonos-spotify:spotify%3atrack%3a1AGslpGIhRzXSOYtE52VcB?sid=9&flags=32' 'volume': 8, 'group_command': 0

        # external url: http://www.tonycuffe.com/mp3/tail%20toddle.mp3
        # internal sonos url: x-sonos-spotify:spotify%3atrack%3a3xCk8npVehdV55KuPdjrmZ?sid=9&flags=32
    }   
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { [snippet metadata will be sent. After the snippet was played, the metadata for] [the resumed track will be sent (e.g. see play_uri UDP response)] }

All values for a new track will be sent, but only new and/or different values.

Plays a text-to-speech snippet using the Google TTS API. After the snippet was played (maximum 10 seconds in streaming mode, longer snippets will be truncated) the previous played song will be resumed. You can queue up to 10 snippets. They're played in the order they are called. To setup the Broker for TTS support, please take a deeper look at the dedicated Google TTS section in this document.

######Example JSON format: { 'command': 'play_tts', 'parameter': { 'uid': 'rincon_000e58c3892e01410', 'tts': 'Die Temperatur im Wohnzimmer ist 2 Grad Celsius.' 'language': 'de', 'force_stream_mode': '0' 'volume': 30, 'group_command': 1 }
}

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { [snippet metadata will be sent. After the tts snippet was played, the metadata for] [the resumed track will be sent (e.g. see play_uri UDP response)] }

All values for a new track will be sent, but only new and/or different values.

[readonly] Gets all registered alarms for a Sonos speaker. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'alarms'-status changes.

######Example JSON format: { 'command': 'get_pause', 'parameter': { 'uid': 'rincon_000e58c3892e01410' } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { ... "alarms": { "32": { "Duration": "02:00:00", "Enabled": false, "IncludedLinkZones": false, "PlayMode": "SHUFFLE_NOREPEAT", "Recurrence": "DAILY", "StartTime": "07:00:00", "Volume": 25 } }, "uid": "rincon_000e58c3892e01410", ... }

Sends all available information from a Sonos speaker to the subscribed clients. You should use this command right after your client has been subscribed to the Broker to get the actual Sonos speaker state.

######Example JSON format: { 'command': 'current_state', 'parameter': { 'uid': 'rincon_000e58c3892e01410', 'group_command': 1 } } ######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

######UDP Response sent to subscribed clients: JSON format: { "additional_zone_members": "rincon_112ef9e4892e00001", "alarms": { "32": { "Duration": "02:00:00", "Enabled": false, "IncludedLinkZones": false, "PlayMode": "SHUFFLE_NOREPEAT", "Recurrence": "DAILY", "StartTime": "07:00:00", "Volume": 25 } }, "bass": 0, "hardware_version": "1.8.3.7-2", "ip": "192.168.0.4", "led": 1, "loudness": 1, "mac_address": "10:1F:21:C3:77:1A", "max_volume": -1, "model": "Sonos PLAY:1", "mute": "0", "pause": 0, "play": 0, "playlist_position": 0, "playmode": "normal", "radio_show": "", "radio_station": "", "serial_number": "00-0E-58-C3-89-2E:7", "software_version": "27.2-80271", "status": true, "stop": 1, "streamtype": "music", "track_album_art": "http://192.168.0.4:1400/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a3xCk8npVehdV55KuPdjrmZ%3fsid%3d9%26flags%3d32", "track_artist": "Feuerwehrmann Sam & Clemens Gerhard", "track_duration": "0:10:15", "track_position": "00:00:00", "track_title": "Das Baby im Schafspelz", "track_uri": "x-sonos-spotify:spotify%3atrack%3a3xCk8npVehdV55KuPdjrmZ?sid=9&flags=32", "treble": 0, "uid": "rincon_000e58c3892e01410", "volume": 8, "zone_icon": "x-rincon-roomicon:bedroom", "zone_name": "Kinderzimmer" }

This is a complete status response for a Sonos speaker.

[readonly] Returns the favorite radio stations.

######Example JSON format: { 'command': 'get_favorite_radio_stations', 'parameter': { 'start_item': 0, # optional, default: 0 'max_items': 10, # optional, default: 50 } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

JSON format:
{
    "total": "2",
    "favorites": [
        {
            "title": "Radio TEDDY",
            "uri": "x-sonosapi-stream:s80044?sid=254&flags=32"
        },
        {
            "title": "radioeins vom rbb 95.8 (Pop)",
            "uri": "x-sonosapi-stream:s25111?sid=254&flags=32"
        }
    ],
    "returned": 2
}

Returns a list containing the total number of favorites, the number of favorites returned, 
and the actual list of favorite radio stations, represented as a dictionary with 'title' 
and 'uri' keys.
Depending on what you're building, you'll want to check to see if the total number of 
favorites is greater than the amount you requested (`max_items`), if it is, use `start` 
to page through and get the entire list of favorites.

No UDP response

[readonly] Returns the status whether the specified speaker is a zone coordinator or not.

######Example JSON format: { 'command': 'is_coordinator', 'parameter': { 'uid': 'rincon_000e58c3892e01410', } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

JSON format: 
{
    "is_coordinator": true,
    "uid": "rincon_b8e93730d19801400"
}

[readonly] Returns the status whether Google TTS 'local mode' is available or not. To get the 'local mode' running, you have to configure the Google TTS options correctly. If False, only the 'streaming mode' is available. This has some disadvantages. Please read the Google TTS section in this documentation.

######Example JSON format: { 'command': 'tts_local_mode', 'parameter': { 'uid': 'rincon_000e58c3892e01410', } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

JSON format: 
{
    "is_coordinator": true,
    "uid": "rincon_b8e93730d19801400"
}

[readonly] Returns the the current playlist as a base64 string. You can save this string to use it with the set_playlist command.

######Example JSON format: { 'command': 'get_playlist', 'parameter': { 'uid': 'rincon_000e58c3892e01410', } }

######HTTP Response HTTP 200 OK and a base64 string representing the playlist or Exception with HTTP status 400 and the specific error message.

No UDP response

Sets the playlist for a speaker ( and for the entire zone). You should read a file containing the base64-coded playlist (gathered by the get_playlist command) and assign the json variable 'playlist' with this value.

######Example JSON format: { 'command': 'set_playlist', 'parameter': { 'uid': 'rincon_000e58c3892e01410', 'playlist': '#so_pl#gASVwhsAAAAAAABdlIwUc29jby5kYXRhX3N0cnVjdHVyZX.... , 'play_after_insert': 1 } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

No UDP response

Updates the local media library. This is useful when adding a new music file to your local media library.

######Example JSON format: { 'command': 'refresh_media_library', 'parameter': { 'display_option': display_option } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

No UDP response

Gets the current wifi status. Since there is no sonos event for the wifi state, you have to trigger this command manually to retrieve the value.

######Example JSON format: { 'command': 'get_wifi_state', 'parameter': { 'uid': rincon_000e58c3892e01410, 'force_refresh': 0 }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

No UDP response

Sets the current wifi status. The parameter "persistent" only affects the wifi state "off". Normally, after a reboot the wifi interface is enabled again. With a combination of "wifi_state = 0" and "persistent = 1" the wifi interface will remain deactivated.

######Example JSON format: { 'command': 'set_wifi_state', 'parameter': { 'uid': rincon_000e58c3892e01410, 'wifi_state': 0, 'persistent': 0 } }

######HTTP Response HTTP 200 OK or Exception with HTTP status 400 and the specific error message.

No UDP response