Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/SoCo/SoCo

SoCo (Sonos Controller) is a Python project that allows you to programmatically control Sonos speakers.
https://github.com/SoCo/SoCo

Last synced: about 2 months ago
JSON representation

SoCo (Sonos Controller) is a Python project that allows you to programmatically control Sonos speakers.

Host: GitHub
URL: https://github.com/SoCo/SoCo
Owner: SoCo
License: mit
Created: 2013-03-13T22:56:39.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2024-01-14T09:38:45.000Z (8 months ago)
Last Synced: 2024-04-11T14:05:25.404Z (6 months ago)
Language: Python
Homepage: http://python-soco.com/
Size: 3.3 MB
Stars: 1,449
Watchers: 62
Forks: 226
Open Issues: 74
Metadata Files:
- Readme: README.rst
- License: LICENSE.rst
- Authors: AUTHORS.rst

Awesome Lists containing this project

README

SoCo
====

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.

.. image:: https://badges.gitter.im/SoCo/SoCo.svg
:alt: Join the chat at https://gitter.im/SoCo/SoCo
:target: https://gitter.im/SoCo/SoCo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

.. image:: https://travis-ci.com/SoCo/SoCo.svg?branch=master
:target: https://travis-ci.com/SoCo/SoCo
:alt: Build Status

.. image:: https://img.shields.io/requires/github/SoCo/SoCo/master.svg?style=flat
:target: https://requires.io/github/SoCo/SoCo/requirements/?branch=master
:alt: Requirements Status

.. image:: https://img.shields.io/pypi/v/soco.svg?style=flat
:target: https://pypi.python.org/pypi/soco/
:alt: 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:

.. code:: python

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

.. code:: python

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

If you prefer a list to a set:

.. code:: python

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

.. code:: python

#!/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.

.. figure:: https://github.com/SoCo/SoCo/raw/master/examples/webapp/screenshot.png
:alt: 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).

Related Projects
----------------

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

**SoCo-CLI** (`soco-cli `_) is a powerful and
fully-featured command line tool suitable for use in scripts, scheduled tasks, etc. It
supports time-based and state-based actions, and repeated commands using loops. Audio
files on the local filesystem can be played back directly on Sonos from the command line.
Multi-household Sonos systems are supported.

Older 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.

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`_.

.. _Sonos speakers: http://www.sonos.com/system/
.. _Music Hack Day Sydney: http://sydney.musichackday.org/2012/
.. _blog post: http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/
.. _Sam Soffes: https://github.com/soffes
.. _Ruby gem: https://github.com/soffes/sonos
.. _Joel Björkman: https://github.com/labero
.. _MIT license: http://www.opensource.org/licenses/mit-license.php
.. _Rahim Sonawalla: https://github.com/rahims/SoCo
.. _GitHub repository: https://github.com/SoCo/SoCo
.. _team of people: https://github.com/SoCo/SoCo/blob/master/AUTHORS.rst
.. _SoCo documentation: https://soco.readthedocs.org/en/latest/