SoCo (Sonos Controller) is a simple Python class that allows you to programmatically control Sonos speakers.
Switch branches/tags
Nothing to show
Pull request Compare This branch is 103 commits behind rahims:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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

Since this was created at a weekend hackathon, I didn't have time to code up dynamic discovery of Sonos devices (done through SSDP). In order to use this class, you'll need to pass in the IP address of the Sonos speaker you'd like to control. A simple way to determine the IP address of your Sonos speaker is to launch the official Sonos application and click on "About My Sonos System" from the menu. From there, you'll see an output similar to the one below:

Associated ZP:
Serial Number: 00-0E-58-4F-87-AC:F
Version: 3.7 (build 17551200)
Hardware Version:
IP Address:
Serial Number: 00-0E-58-5D-15-32:E
Version: 3.7 (build 17551200e)
Hardware Version:
IP Address:
OTP: 1.1.1(1-16-4-zp5s-0.5)

To be clear, you only need the official Sonos application to get the IP address of the speaker. This class does not depend on the official Sonos application in any way.

Basic Usage

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

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

    track = sonos.get_current_track_info()

    print track['title']

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.

Screenshot of web app


SoCo currently supports the following basic controls:

  • Play
  • Pause
  • Stop
  • Next track
  • Previous track
  • Get information about the currently playing track
    • Track title
    • Artist
    • Album
    • Track length
    • Duration played (for example, 30 seconds into a 3 minute song)
    • Playlist position (for example, item 5 in the playlist)
  • Mute (or unmute) the speaker
  • Set the speaker volume
  • Turn on (or off) the white status light on the unit


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

  • SSDP for dynamic discovery of Sonos devices
  • playlist management
  • specify a song to play
  • better error checking


Copyright (C) 2012 Rahim Sonawalla ( / @rahims).

Released under the MIT license.