Skip to main content

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

Project description

SoCo (Sonos Controller) is a Python library that allows you to control Sonos speakers programmatically. 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 the functionailty.

Join the chat at https://gitter.im/SoCo/SoCo Build Status Requirements Status Latest PyPI version

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

As of v0.26.0, nascent music service support has been reinstated, with some known issues. Testing and issue reporting would be appreciated.

Installation

SoCo requires Python 3.6 or newer.

Use pip:

pip install soco

SoCo depends on a number of Python packages. If you use pip to install Soco, the dependencies will be installed automatically for you. If not, you can inspect the requirements in the requirements.txt file.

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:

>>> from soco import discover
>>> for zone in discover():
...        print(zone.player_name)
Living Room
Kitchen

If you prefer a list to a set:

>>> zone_list = list(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 in the SoCo Gitter Room.

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

Screenshot of web app

Features

SoCo supports the following controls amongst others:

  • Play, Pause, Stop

  • Next track, Previous track

  • Volume get and set

  • Mute (or unmute)

  • Get current transport information (if speaker is playing, paused or 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

  • Receive events when the player state changes

  • Search for and play music items:

    • Local music library

    • Webradio via TuneIn and music services (still unstable)

    • Saved Sonos favorites, favorite radio stations and shows

  • Switch the speaker’s source to line-in or TV input (if the Zone Player supports it)

  • Manage the Sonos queue:

    • Get the items in the queue

    • Add items to the queue

    • Clear the queue

    • Play a specific song from the queue

  • Join or unjoin speakers from a group

  • Put all Sonos speakers in a network into “party mode”.

  • Get or set alarms

  • Get or set sleep timers

  • Enable or disable surround speakers or subwoofer

  • Get information regarding a home theater setup:

    • If surround speakers or a subwoofer are paired

    • Which audio channel a given speaker handles

  • Get or set the speaker’s bass and treble EQ

  • Toggle the speaker’s loudness compensation, night mode and dialog mode

  • Toggle the white status light on the unit

  • 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

  • Start a music library update and determine if one is in progress

SoCo also supports lower level access from Python to all Sonos services (e.g. ContentDirectory or RenderingControl).

SoCo Gitter Room

There is a SoCo Gitter discussion room. Feel free to drop by for support, ideas or casual conversation related to SoCo.

License

SoCo is released under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

soco-0.30.2.tar.gz (732.3 kB view details)

Uploaded Source

Built Distribution

soco-0.30.2-py2.py3-none-any.whl (162.6 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file soco-0.30.2.tar.gz.

File metadata

  • Download URL: soco-0.30.2.tar.gz
  • Upload date:
  • Size: 732.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for soco-0.30.2.tar.gz
Algorithm Hash digest
SHA256 328a6fc0653d9f9e4883fd59674fb73feb61dc273f7c1f0a8212e91103112cb5
MD5 f844ccf1db4a4532ef7a9433ad19fa01
BLAKE2b-256 a2b61c4d30c9e15a85660a5ff2fdd8bc07b2b3b5f5c77933a8657ceb525c2261

See more details on using hashes here.

File details

Details for the file soco-0.30.2-py2.py3-none-any.whl.

File metadata

  • Download URL: soco-0.30.2-py2.py3-none-any.whl
  • Upload date:
  • Size: 162.6 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for soco-0.30.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 aaf462c55d6f8eeb2405ddf4bded915d816a4edf79556720796b1abfbfde3568
MD5 a003afb3c5a83d814c2a103a2b6a120c
BLAKE2b-256 cd6366a5d93da82a51e9f6c54f7337fb74ed2d7a07e1a0e8c128c9bd31e4c408

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page