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 functionality.
.. image:: https://img.shields.io/pypi/v/soco.svg?style=flat :target: https://pypi.org/project/soco/ :alt: Latest PyPI version
WARNING -------
Sonos has changed the way music service authentication works, and a number of streaming services currently have known issues or cannot be used at all. Known affected services include Apple Music, Amazon Music, Spotify, and Napster.
Support for these services is an ongoing effort. See the project's GitHub Issues _ for current status.
Installation ------------
SoCo requires Python 3.8 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( 'https://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 open an issue or discussion on the SoCo GitHub repository _.
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
- Get information about the currently playing track
- Receive events when the player state changes
- Search for and play music items:
- Switch the speaker’s source to line-in or TV input (if the Zone Player
- Manage the Sonos 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:
- 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
- Set the speaker’s Zone Name
- Start a music library update and determine if one is in progress
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? Sam Soffes_ built a Ruby gem_, though it is no longer maintained.
Joel Björkman_ built SoCo-Tk, a Sonos Controller GUI for Linux, though it is no longer maintained:
https://github.com/labero/SoCo-Tk.
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.io/en/latest/