SoCo

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.

Set up

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

pip install requests

Basic Usage

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

Example Applications

To show off what can be made with SoCo, a basic commandline application and a simple web application are included in the examples folder.

Features

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)

To-Do

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

Contributors

IRC

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.

Related Projects

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.

License

Released under the MIT license.

ren/SoCo