SoCo (Sonos Controller) is a simple library to control Sonos speakers.
SoCo (Sonos Controller) is a Python project that allows you to programmatically control Sonos speakers. It was originally created at Music Hack Day Sydney by Rahim Sonawalla and is now developed by a team of people at its GitHub repository
For more background on the project, please see Rahim’s blog post.
Visit the SoCo documentation for a more detailed overview of all the functionailty.
Sonos has changed the way music service account information is available. This means that currently a group of music service will give authentication issues and cannot be used at all. Known members of this group are: Google Play Music, Apple Music, Amazon Music, Spotify and Napster.
Issue #557 is a meta issue for this problem and you can use that to track progress on solving the issues, but please refrain from posting “me too” comments in there. Also, there is no need to open any more separate issue about this.
If you have another music service that should be on the list, comment in #557
SoCo requires Python 2.7, or 3.4 or newer.
pip install soco
SoCo depends on the Requests HTTP library. If you use pip to install Soco, Requests will be installed automatically for you. If not, you can use:
pip install requests
You can interact with a Sonos Zone Player through a SoCo object. If you know the IP address of a Zone Player, you can create a SoCo object directly:
>>> from soco import SoCo >>> my_zone = SoCo('192.168.1.101') >>> my_zone.player_name Kitchen >>> my_zone.status_light = True >>> my_zone.volume = 6
But perhaps the easiest way is to use the module-level discover function. This will find all the Zone Players on your network, and return a python set containing them:
>>> import soco >>> for zone in soco.discover(): ... print zone.player_name Living Room Kitchen
If you prefer a list to a set:
>>> zone_list = list(soco.discover()) >>> zone_list [SoCo("192.168.1.101"), SoCo("192.168.1.102")] >>> zone_list.mute = True
Of course, you can also play music!
#!/usr/bin/env python from soco import SoCo if __name__ == '__main__': sonos = SoCo('192.168.1.102') # Pass in the IP of your Sonos speaker # You could use the discover function instead, if you don't know the IP # Pass in a URI to a media file to have it streamed through the Sonos # speaker sonos.play_uri( 'http://ia801402.us.archive.org/20/items/TenD2005-07-16.flac16/TenD2005-07-16t10Wonderboy.mp3') track = sonos.get_current_track_info() print track['title'] sonos.pause() # Play a stopped or paused track sonos.play()
To show off what can be made with SoCo, a simple web application is included in the examples folder.
SoCo supports the following controls amongst others:
Play, Pause, Stop
Next track, Previous track
Volume get and set
Mute (or unmute)
Get current transport information (if speaker is playing, paused or stopped)
Get information about the currently playing track
Album Art (if available)
Duration played (for example, 30 seconds into a 3 minute song)
Playlist position (for example, item 5 in the playlist)
Receive events when the player state changes
Search for and play music items:
Local music library
Webradio via TuneIn and music services (still unstable)
Saved Sonos favorites, favorite radio stations and shows
Switch the speaker’s source to line-in or TV input (if the Zone Player supports it)
Manage the Sonos queue:
Get the items in the queue
Add items to the queue
Clear the queue
Play a specific song from the queue
Join or unjoin speakers from a group
Put all Sonos speakers in a network into “party mode”.
Get or set alarms
Get or set sleep timers
Get or set the speaker’s bass and treble EQ
Toggle the speaker’s loudness compensation, night mode and dialog mode
Toggle the white status light on the unit
Get the speaker’s information
UID (usually something like RINCON_XXXXXXXXXXXXXXXXX)
Set the speaker’s Zone Name
Start a music library update and determine if one is in progress
SoCo also supports lower level access from Python to all Sonos services (e.g. ContentDirectory or RenderingControl).
There is a Soco group over at Google Groups. Feel free to drop by for support, ideas or casual conversation related to SoCo.
SoCo is released under the MIT license.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.