Sonos on SmarthomeNG

v1.1 (2017-02-19)

-- bugfix: play_tunein should working now (after some SoCoc changes)
-- SoCo framework update

v1.0 (2017-02-18)

-- Attention: cleaned-up configuration file. Please re-configure your Sonos Broker installation
-- command "transport_actions" to Sonos Broker and Sonos command line tool
    -- this options shows all possible actions for the current track (e.g. Next, Stop, Play ...)
-- command 'nightmode' added (only for supported speakers)
-- bug: Spotify Radio was handled as a normal radio station and should be fixed
-- GoogleTTS improvements
-- GoogleTTS: files now stored with md5 sum of tts_language and tts_string to reduce the filename length
-- GoogleTTS: now works in streaning mode per default, no web service is needed.
-- GoogleTTS: the local ip address for the streaming url will be detected automatically (by default)
-- play_tts: (optional) attribute 'force_stream_mode' (re)-added to Sonos Broker and Command line tool
-- bug: endless loop while trying to play a track from a non-existing url
-- bug: wrong path in systemd script
-- bug: the 'volume' of all zone members will now be restored correctly after playing the snippet
-- command optional parameter 'play' added to command "unjoin"
    -- with 'play' set to true, the prevoiusly played track (before joining a group) will resumed
-- changed executable name from "sonos_broker" to "sonos-broker"
-- changed command line tool from "sonos_cmd" to "sonos-cmd"
-- changed default installation path of sonos_broker.cfg to /etc/default/sonos-broker
-- stopping a running Sonos Broker instance is handled a bit more gracefully
-- updated setup script
-- auto-start scripts for systemd and upstart automatically placed in the appropriate folder by the 
   installation script  
-- 'daemonize' behaviour removed
-- unnecessary parameter 'stop' removed
-- updated documentation
-- added "zone_member" command to Sonos Broker (to retrieve this value actively)
-- added commands 'join' and 'unjoin' to Sonos Broker commandline tool
-- bug: error when trying to decode non-ascii chars and the systems stdout was no set to utf8

v0.9 (2016-11-20)

-- added missing 'track_album' property
-- added missing 'track_album' to Sonos-Broker commandline
-- added "get_playlist_position" command and "playlist_position" property to Sonos Broker and
   Sonos Broker commandline tool
-- added "get_playlist_total_tracks" command and "playlist_total_tracks" property to Sonos Broker and 
   Sonos Broker commandline tool
-- added missing 'track_album_art' property to Sonos Broker commandline tool
-- bug: 'playlist_position' was not handled correctly
-- changed maximum snippet length to 15 seconds
-- bugfixed: Sonos Broker user-specific server port was ignored
-- updated documentation

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/).

If're updating the Broker it may be a good idea to delete old files. Please adapt the paths to your system.

sudo rm -rf /usr/local/bin/sonos*
sudo rm -rf /usr/local/lib/python3.5/site-packages/*sonos*
sudo rm -rf /usr/local/lib/python3.5/site-packages/soco

python3.4 python3 libraries 'requests' and 'xmltodict'

Nothing special, just send your commands over http (JSON format) or use the Smarthome.py plugin to control the speakers within Smarthome.py. You can use the included built-in implementation, the Sonos Broker commandline tool

Under the github folder "server.sonos/dist/" you'll find the actual release as a tar.gz file. Here are two ways to install the Sonos Broker:

If python3-pip is installed, you can simply call

python3 -m pip -v install sonos-broker-{release-version}.tar.gz

Every dependency should be installed automatically.

Untar the file with and install it manually.

tar -xvf sonos-broker-{release}.tar.gz
cd sonos-broker-{release}
sudo python3 setup.py install --force

If an error occurred, you should try to (re)-install all necessary dependencies:

pip3 install requests
pip3 install xmltodict

Both methods will install sonos-broker and sonos-cmd under /usr/local/bin to make both commands system-wide executable. The default config file is installed under ```/etc/default/sonos-broker``.

The internal ip address should be set up automatically. If not, you have to edit /etc/default/sonos-broker

[sonos_broker]
server_ip = x.x.x.x #your ip here

You can edit the settings of Sonos Broker. Open '/etc/default/sonos-broker' (by default) 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.

You can start the sonos broker with

sonos_broker start

You can add the -d (--debug) parameter to get more output

sonos_broker start -d

An user-specified config file can be passed with the '-c' flag. Default: /etc/default/sonos-broker

sonos_broker start -c /your/config/file/path/here

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

sonos_broker list

To get an overview of all parameters type

sonos_broker -h

and / or

sonos_broker {command} -h

After the successful installation with sudo python3 setup.py install --force an autostart script should be placed automatically in your systems autostart directory. The autostart implementations are integrated for systems based on 'SYSTEMD' and 'UPSTART'. 'SYSVINIT' is NOT supported because of there are too many different sysvinit implementations. To control the Broker via the system service control, see the commands below:

SYSTEMD: sudo systemctl [start|stop|restart] sonos-broker

For autostart: sudo systemctl enable sonos-broker

UPSTART: sudo service sonos-broker [start|stop|restart]

For autostart uncomment following line in /etc/init/sonos-broker.conf: #start on runlevel [2345]

To get some more debug output when running the Broker as a service, please edit the Sonos Broker config file (default: /etc/default/sonos-broker) and uncomment this line in the logging section:

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 = /path/to/your/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 integrates an internal webservice to serve audio files for Sonos speakers. You can enable this feature in the [webservice] section of the Sonos Broker configuration. If enabled, you can store audio files in the configurable web root path (valid extensions: aac, mp4, mp3, ogg, wav, web) and they can be played with the play_snippet command. The URL is available via http://SONOS_BROKER_IP:SONOS_BROKER_PORT/. This service is also helpful for the Google TTS functionality.

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

• internet connection
• settings configured in sonos-broker configuration file (default: /etc/default/sonos-broker)

If a text is given to the google tts function, the Sonos Broker makes a http request to the Google API and the tts string will be played by your Sonos loudspeakers. Additionally, you can set-up the Broker to store the request as a mp3 file. This is a kind of local caching: if a tts string is requested which is already stored as a mp3 file, this file will be served to the Sonos speakers. To enable this feature, you have to configure the webservice feature of the Sonos Broker. Have a look at the configuration file for more details [/etc/default/sonos-broker]

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": "1",
    "playlist_total_tracks": "10",
    "playmode": "normal",
    "radio_show": "",
    "radio_station": "",
    "serial_number": "00-0E-58-C3-89-2E:7",
    "software_version": "27.2-80271",
    "sonos_playlists": "DepecheMode,my_fav-list2,my-fav-list2",
    "status": true,
    "stop": 1,
    "streamtype": "music",
    "track_album": "Feuerwehrmann Sam 02",
    "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",
    "transport_actions": "Set,Stop,Pause,Play,Next"
    "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_treble', '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 balance 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 'balance'-status changes.

######Example JSON format: { 'command': 'get_balance', '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: {
... "balance": [-100 - 100], "uid": "rincon_b8e93730d19801410", ... }

Sets the treble for a Sonos speaker.

######Example JSON format: { 'command': 'set_balance', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'treble': , '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: { ... "balance": [-100 - 100], "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 nightmode setting from a Sonos speaker. The nightmode feature is only avaliable for certain Sonos speakers, e.g. the Sonos Playbar. For all other speakers, this value should always be 0. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'nightmode'-status changes.

######Example JSON format: { 'command': 'get_nightmode', '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: {
... "nightmode": 0|1, "uid": "rincon_b8e93730d19801410", ... }

Sets the nightmode option for a Sonos speaker. If the Sonos speaker does not support this feature, an error message is thrown.

######Example JSON format: { 'command': 'set_nightmode', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'nightmode': 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: { ... "nightmode": 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 album 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_album'-status changes.

######Example JSON format: { 'command': 'get_track_album', '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": "Delta Machine", "uid": "rincon_b8e93730d19801410", ... }

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 available transport actions for the current track. This could be useful for a UI to display certain control items (or not). In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'transport_actions'-status changes.

######Example JSON format: { 'command': 'get_transport_actions', '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: {
... "transport_actions": "Set,Stop,Pause,Play,Next", "uid": "rincon_b8e93730d19801410", ... }

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

######Example JSON format: { 'command': 'get_playlist_position', 'parameter': { 'uid': 'rincon_b8e91111d11111400' } }

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

JSON format:
{
    ...
    "uid": "rincon_b8e91111d11111400",
    "playlist_position": "3"
    ...
}

Returns the total number of tracks in the current playlist. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'playlist_total_tracks'-status changes.

######Example JSON format: { 'command': 'get_playlist_total_tracks', 'parameter': { 'uid': 'rincon_b8e91111d11111400' } }

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

JSON format:
{
    ...
    "uid": "rincon_b8e91111d11111400",
    "playlist_total_tracks": "13"
    ...
}

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', 'play': False } }

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

Clears the queue.

######Example JSON format: { 'command': 'clear_queue', '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": "", "uid": "rincon_000e58c3892e01410", ... }

Plays a radio station by a give name.

######Example JSON format: { 'command': 'play_tunein', 'parameter': { 'uid': 'rincon_b8e93730d19801410', 'station_name': '98.8 KISS FM' }
}

######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 BJ Barry Show", "radio_station": "98.8 KISS FM", "track_album_art": "http://192.168.178.21:1400/getaa?s=1&u=x-sonosapi-stream%3as16523%3fsid%3d254%26sn%3d0", "track_artist": "Sia Feat. Kendrick Lamar", "track_title": "Sia Feat. Kendrick Lamar - The Greatest", "uid": "rincon_000e58c3892e01410" ... }

All values for a radio station 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.

######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. 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 beträgt 2 Grad Celsius.' 'language': 'de', 'volume': 30, 'group_command': 1, 'force_stream_mode': 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: { [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": "1", "playlist_total_tracks": "10", "playmode": "normal", "radio_show": "", "radio_station": "", "serial_number": "00-0E-58-C3-89-2E:7", "software_version": "27.2-80271", "sonos_playlists": "DepecheMode,my_fav-list2,my-fav-list2", "status": true, "stop": 1, "streamtype": "music", "track_album": "Feuerwehrmann Sam 02", "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", "transport_actions": "Set,Stop,Pause,Play,Next" "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_b8e91111d11111400', } }

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

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

[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_b8e91111d11111400', } }

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

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

Gets all Sonos playlists separated by ','.

######Example JSON format: { 'command': 'get_sonos_playlists', 'parameter': { 'uid': 'rincon_b8e91111d11111400' } }

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

JSON format:
{
    ...
    "uid": "rincon_b8e91111d11111400",
    "sonos_playlists": "mylist,another_list,Abba'
    ...
}

Loads a Sonos playlist by a given name.

######Example JSON format: { 'command': 'load_sonos_playlist', 'parameter': { 'uid': "rincon_b8e91111d11111400", 'sonos_playlist': "DepecheMode", 'play_after_insert': 1, 'clear_queue': 1 }

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

######UDP Response sent to subscribed clients: No specific 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': "ITUNES" } }

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

No UDP response

Gets all additional zone members of the group the current speaker is part of. If the speaker is the only member of the group, the response is empty. In most cases, you don't have to execute this command, because all subscribed clients will be notified automatically about 'zone_members'-status changes.

######Example JSON format: { 'command': 'zone_members', 'parameter': { 'uid': rincon_b8e91111d11111400 }

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

JSON format: 
{
    ...
    "zone_members": ["rincon_c4441111d11111400", "rincon_d5ee1111d11111400"]
    "uid": "rincon_b8e91111d11111400"
    ...
}

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_b8e91111d11111400, 'force_refresh': 0 }

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

JSON format: 
{
    ...
    "wifi_state": 1,
    "uid": "rincon_b8e91111d11111400"
    ...
}

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

Gets the Sonos Broker version.

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

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

######HTTP Response Sonos Broker version string.

Performs a manual scan for Sonos speaker in the network. This command requires no parameters.

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

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

No UDP response