skip to navigation
skip to content

soco 0.7

SoCo (Sonos Controller) is a simple library to control Sonos speakers

Latest Version: 0.14

SoCo (Sonos Controller) is a simple Python class 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.


SoCo requires Python 2.7, or 3.2 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('')
>>> my_zone.player_name
>>> 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 iterable containing them:

>>> import soco
>>> for zones in
...        print zone.player_name
Living Room

If you prefer a list to an iterable:

>>> zone_list = list(
>>> zone_list
SoCo(""), SoCo("")]
>>> zone_list[0].mute()

Of course, you can also play music!

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

if __name__ == '__main__':
    sonos = SoCo('') # 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

    track = sonos.get_current_track_info()

    print track['title']


    # Play a stopped or paused track

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


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
  • 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

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

Google Group

There is a Soco group over at Google Groups. Feel free to drop in.


SoCo is released under the MIT license.

File Type Py Version Uploaded on Size
soco-0.7.tar.gz (md5) Source 2014-05-05 47KB