Important Note: this project originally started out under rahims/SoCo. As activity and interest have grown over the past year, the developers decided it was best to spin it out into its own project under its own Github Organization. Going forward, please fork and star the newly official repo, SoCo/SoCo, as rahims/SoCo will be used by Rahim to manage his fork of the official repo.

SoCo (Sonos Controller) is a simple Python class that allows you to programmatically control Sonos speakers. It was created at Music Hack Day Sydney, so there is still much room for improvement, however the basic control functionality is there and works well. I've tested it with both a Play:3 and a Play:5.

For more background on this project, please see my related blog post.

SoCo depends on the Requests HTTP library. The easiest way to install it is through pip:

pip install requests

Discovery does IP addresses only for now, returning a list IP addresses of players.

#!/usr/bin/env python
from soco import SoCo
from soco import SonosDiscovery

if __name__ == '__main__':
    sonos_devices = SonosDiscovery()

    for ip in sonos_devices.get_speaker_ips():
        device = SoCo(ip)
        zone_name = device.get_speaker_info()['zone_name']
        print "IP of %s is %s" % (zone_name, ip)

#!/usr/bin/env python
from soco import SoCo

if __name__ == '__main__':
    sonos = SoCo('10.0.0.102') # Pass in the IP of your Sonos speaker

    # Pass in a URI to a media file to have it streamed through the Sonos speaker
    sonos.play_uri('http://archive.org/download/TenD2005-07-16.flac16/TenD2005-07-16t10Wonderboy_64kb.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 basic commandline application and a simple web application are included in the examples folder.

SoCo currently supports the following basic controls:

• Play
• Pause
• Stop
• Next track
• Previous track
• Get current transport information(if speaker is playing,paused,stopped)
• Get information about the currently playing track
  • Track title
  • Artist
  • Album
  • Album Art (if available)
  • Track length
  • Duration played (for example, 30 seconds into a 3 minute song)
  • Playlist position (for example, item 5 in the playlist)
  • Track URI
• Mute (or unmute) the speaker
• Get or set the speaker volume
• Get or set the speaker's bass EQ
• Get or set the speaker's treble EQ
• Toggle the speaker's loudness compensation
• Turn on (or off) the white status light on the unit
• Switch the speaker's source to line-in (doesn't work on the Play:3 since it doesn't have a line-in)
• Get the speaker's information
  • Zone Name
  • Zone Icon
  • UID (usually something like RINCON_XXXXXXXXXXXXXXXXX)
  • Serial Number
  • Software version
  • Hardware version
  • MAC Address
• Set the speaker's Zone Name
• Find all the Sonos speakers in a network. Code contributed by Thomas Bartvig.
• Put all Sonos speakers in a network into "party mode". Code contributed by Thomas Bartvig.
• "Unjoin" speakers from a group.
• Manage the Sonos queue (get the items in it, add to it, clear it, play a specific song from it)
• Get the saved favorite radio stations and shows (title and stream URI)

Want to contribute to SoCo? Here's what needs to be done:

• Unit tests. (Currently being worked on by Kenneth Nielsen.)
• Better error checking.
• PEP 8

• Thomas Bartvig [email protected]
• Dave O'Connor [email protected]
• nixscripter
• Joel Björkman
• Stefan Kögl
• Kenneth Nielsen
• Scott G. Waters
• phut

From time to time, folks hang out in #soco on freenode (chat.freenode.net). If you're new to IRC, start with the webchat client. Simply pick a nickname, enter #soco for the channel, and fill in the CAPTCHA.

More of a Ruby fan? Not a problem, Sam Soffes is building out an awesome Ruby gem.

Looking for a GUI that's more than just a sample project? Joel Björkman is building a Sonos Controller GUI--great for folks on Linux where there isn't an official Sonos Controller application! Find, fork, and contribute to it here: https://github.com/labero/SoCo-Tk.

Copyright (C) 2012-2013 Rahim Sonawalla ([email protected] / @rahims).

Released under the MIT license.