SoCo

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.

Warning

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

Installation

SoCo requires Python 2.7, or 3.3 or newer.

Use pip:

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

Basic Usage

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[0].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()

Support

If you need support for SoCo, feel free to post your question either on our Google Group or on the #soco IRC channel on freenode.

Example Applications

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

Screenshot of web app

Features

SoCo supports the following controls amongst others:

• 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
• Toggle the speaker's night mode
• Toggle the speaker's dialog mode
• Turn on (or off) the white status light on the unit
• Switch the speaker’s source to line-in or TV input (if the Zone Player supports it)
• 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.
• Put all Sonos speakers in a network into “party mode”.
• “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)
• Search for and play item from your music library
• Start a music library update and determine if one is in progress

SoCo also supports lower level access from Python to all Sonos services (eg Alarms)

Related Projects

Socos is a command line tool for controlling Sonos devices. It is developed in conjunction with Soco, but in a separate repository.

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.

Google Group

There is a Soco group over at Google Groups. Feel free to drop by for support, ideas or casual conversation related to SoCo.

License

SoCo is released under the MIT license.