This is an old revision of the document!
Table of Contents
Sonos
The XTension Sonos plugin is currently in an Alpha state. Mostly untested and not feature complete. The commands listed below are implemented for control of Sonos devices but there is currently no way to get events or information back from the Sonos. I do plan to flesh all that out given time and some feedback from people that actually own a sonos device but there is no schedule for that. Let me know if you have information or testing results to share.
This plugin makes use of the https://github.com/SoCo/SoCo library to provide the actual connection to the Sonos devices.
XTension Setup:
XTension setup is simple. There are actually no options to set at the moment at all. Only a single instance of the plugin running is needed for any number of sonos devices on the network. When the plugin starts up it will discover any visible sonos devices on the network and create a unit for them in XTension. That unit will not receive any ON/OFF events, but can be used in a tell block to send any of the control commands to it. This interface will probably change for some things, and when events from the sonos units are implemented I may move some of these commands out to separate units, but for now this is the interface to limited control of your sonos devices.
If you have multiple Soni configured as stereo pairs they will show up as a single unit. If you have surround sound devices or sub woofer devices, they will also all show up together as a single unit. Normally a single unit will be created for any configured Sonos “Zone”
The Units in Xtension will be created with the name you have set for your Sonos zone. Once the unit is created you can change the name to something more descriptive or user friendly when scripting.
Note that the plugin libraries will attempt to take over the standard UPNP port and may block other plugins that try to use that. I can convert to a shared port in the future if anybody runs into this problem.
Sonos Commands:
Once a Unit has been created for your Sonos Zone you can send it commands via scripts as below. The Unit must be referenced in a tell block similar to:
tell xUnit “name of your Sonos unit” to mute()
or
tell xUnit “name of your Sonos unit” to setVolume( 75)
Note that all commands in AppleScript require the parens at the end of them even if there are no parameters to pass. They must end like unMute()
mute() | Mutes the targeted Sonos Device |
---|---|
unMute() | Un mutes the targeted Sonos Device |
setVolume( integer) | Pass an integer from 0 to 100 |
setRelativeVolume( integer) | adjust the current volume by this amount, integer from -100 to 100 |
play() | restart playing whatever was last selected |
stop() | stop playing |
pause() | pause the currently playing source |
next() | Skip to the next track |
Previous() | Backup to the previous track |
clearQueue() | Clear the current playback queue |
enableSub() | Enable the subwoofer if available |
disableSub() | Disable the subwoofer |
setTreble( integer) | integer from -10 to 10 |
setBass( integer) | integer from -10 to 10 |
setBalance( integer, integer) | pass 2 volume levels from 0 to 100 for the left and right channels |
enableLoudness() | Enable loudness processing |
disableLoudness() | Disable Loudness on the device |
enableNightMode() | Enables Night Mode |
disableNightMode() | Disables Night Mode |
enableSurround() | If supported will enable surround sound mode |
disableSurround() | If supported will disable surround sound mode |
enableAmbient() | If supported will enable surround ambient mode |
disableAmbient() | If supported will disable surround ambient mode |
setTvSurroundVolume( integer) | 0-100 sets the volume of the surround channels when playing TV |
setMusicSurroundVolume( integer) | 0-100 sets the volume of the surround channels when playing music |
enableTruePlay() | If supported will enable True Play processing |
disableTruePlay() | If supported will disable True Play processing |
switchToLineIn() | changes the input source to Line In |
switchToTV() | Changes the input source to TV |
setSleepTimer( integer) | pass the number of seconds before the speaker sleeps, or pass 0 to cancel a sleep timer |
enableCrossFade() | Enables cross fading while playing music |
disableCrossFade() | Disables cross fading while playing music |
More commands and events are coming in future versions