User Tools

Site Tools



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 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()


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

supported_hardware/sonos.txt · Last modified: 2023/02/13 14:52 by