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
<http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/>`_.
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 <https://github.com/SoCo/SoCo/blob/master/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 <https://gitter.im/SoCo/SoCo>`_.
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 <https://github.com/SoCo/socos>`_.
**SoCo-CLI** (`soco-cli <https://github.com/avantrec/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 <https://gitter.im/SoCo/SoCo>`_. 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/
Raw data
{
"_id": null,
"home_page": null,
"name": "soco",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "The SoCo-Team <python-soco@googlegroups.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/29/7018a559b465c302548b58aefdd6d0ea296c232638e9e1fd2c3210105296/soco-0.30.4.tar.gz",
"platform": null,
"description": "SoCo\n====\n\nSoCo (Sonos Controller) is a Python library that allows you to\ncontrol `Sonos speakers`_ programmatically. It was originally created at `Music\nHack Day Sydney`_ by `Rahim Sonawalla`_ and is now developed by a `team of\npeople`_ at its `GitHub repository`_\n\nFor more background on the project, please see Rahim's `blog post\n<http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/>`_.\n\nVisit the `SoCo documentation`_ for a more detailed overview of the functionailty.\n\n.. image:: https://badges.gitter.im/SoCo/SoCo.svg\n :alt: Join the chat at https://gitter.im/SoCo/SoCo\n :target: https://gitter.im/SoCo/SoCo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\n.. image:: https://travis-ci.com/SoCo/SoCo.svg?branch=master\n :target: https://travis-ci.com/SoCo/SoCo\n :alt: Build Status\n\n.. image:: https://img.shields.io/requires/github/SoCo/SoCo/master.svg?style=flat\n :target: https://requires.io/github/SoCo/SoCo/requirements/?branch=master\n :alt: Requirements Status\n\n.. image:: https://img.shields.io/pypi/v/soco.svg?style=flat\n :target: https://pypi.python.org/pypi/soco/\n :alt: Latest PyPI version\n\nWARNING\n-------\n\nSonos 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.\n\nIssue #557 is a meta issue for this problem and you can use that to track progress on solving the issues, but\n*please refrain from posting \"me too\" comments* in there. Also, there is no need to open any more separate issue about this.\nIf you have another music service that should be on the list, comment in #557\n\n**As of v0.26.0, nascent music service support has been reinstated, with some known issues. Testing and issue reporting\nwould be appreciated.**\n\nInstallation\n------------\n\nSoCo requires Python 3.6 or newer.\n\nUse pip:\n\n``pip install soco``\n\n\nSoCo depends on a number of Python packages. If you use pip to install Soco,\nthe dependencies will be installed automatically for you. If not, you can inspect\nthe requirements in the `requirements.txt <https://github.com/SoCo/SoCo/blob/master/requirements.txt>`_\nfile.\n\n\nBasic Usage\n-----------\n\nYou can interact with a Sonos Zone Player through a SoCo object. If you know\nthe IP address of a Zone Player, you can create a SoCo object directly:\n\n.. code:: python\n\n >>> from soco import SoCo\n >>> my_zone = SoCo('192.168.1.101')\n >>> my_zone.player_name\n Kitchen\n >>> my_zone.status_light = True\n >>> my_zone.volume = 6\n\n\nBut perhaps the easiest way is to use the module-level `discover` function.\nThis will find all the Zone Players on your network, and return a python\nset containing them:\n\n.. code:: python\n\n >>> from soco import discover\n >>> for zone in discover():\n ... print(zone.player_name)\n Living Room\n Kitchen\n\n\nIf you prefer a list to a set:\n\n.. code:: python\n\n >>> zone_list = list(discover())\n >>> zone_list\n [SoCo(\"192.168.1.101\"), SoCo(\"192.168.1.102\")]\n >>> zone_list[0].mute = True\n\nOf course, you can also play music!\n\n.. code:: python\n\n #!/usr/bin/env python\n from soco import SoCo\n\n if __name__ == '__main__':\n sonos = SoCo('192.168.1.102') # Pass in the IP of your Sonos speaker\n # You could use the discover function instead, if you don't know the IP\n\n # Pass in a URI to a media file to have it streamed through the Sonos\n # speaker\n sonos.play_uri(\n 'http://ia801402.us.archive.org/20/items/TenD2005-07-16.flac16/TenD2005-07-16t10Wonderboy.mp3')\n\n track = sonos.get_current_track_info()\n\n print(track['title'])\n\n sonos.pause()\n\n # Play a stopped or paused track\n sonos.play()\n\nSupport\n-------\n\nIf you need support for SoCo, feel free to post your question in the `SoCo Gitter Room <https://gitter.im/SoCo/SoCo>`_.\n\nExample Applications\n--------------------\n\nTo show off what can be made with SoCo, a simple web application is included in\nthe ``examples`` folder.\n\n.. figure:: https://github.com/SoCo/SoCo/raw/master/examples/webapp/screenshot.png\n :alt: Screenshot of web app\n\n Screenshot of web app\n\n\nFeatures\n--------\n\nSoCo supports the following controls amongst others:\n\n- Play, Pause, Stop\n- Next track, Previous track\n- Volume get and set\n- Mute (or unmute)\n- Get current transport information (if speaker is\n playing, paused or stopped)\n- Get information about the currently playing track\n\n - Track title\n - Artist\n - Album\n - Album Art (if available)\n - Track length\n - Duration played (for example, 30 seconds into a 3 minute song)\n - Playlist position (for example, item 5 in the playlist)\n - Track URI\n\n- Receive events when the player state changes\n- Search for and play music items:\n\n - Local music library\n - Webradio via TuneIn and music services (still unstable)\n - Saved Sonos favorites, favorite radio stations and shows\n\n- Switch the speaker\u2019s source to line-in or TV input (if the Zone Player\n supports it)\n- Manage the Sonos queue:\n\n - Get the items in the queue\n - Add items to the queue\n - Clear the queue\n - Play a specific song from the queue\n\n- Join or unjoin speakers from a group\n- Put all Sonos speakers in a network into \u201cparty mode\u201d.\n\n- Get or set alarms\n- Get or set sleep timers\n\n- Enable or disable surround speakers or subwoofer\n- Get information regarding a home theater setup:\n\n - If surround speakers or a subwoofer are paired\n - Which audio channel a given speaker handles\n\n- Get or set the speaker\u2019s bass and treble EQ\n- Toggle the speaker\u2019s loudness compensation, night mode and dialog mode\n- Toggle the white status light on the unit\n- Get the speaker\u2019s information\n\n - Zone Name\n - Zone Icon\n - UID (usually something like RINCON\\_XXXXXXXXXXXXXXXXX)\n - Serial Number\n - Software version\n - Hardware version\n - MAC Address\n\n- Set the speaker\u2019s Zone Name\n- Start a music library update and determine if one is in progress\n\nSoCo also supports lower level access from Python to all Sonos services\n(e.g. ContentDirectory or RenderingControl).\n\n\nRelated Projects\n----------------\n\n**Socos** is a command line tool for controlling Sonos devices. It is developed\nin conjunction with Soco, but in a `separate repository <https://github.com/SoCo/socos>`_.\n\n**SoCo-CLI** (`soco-cli <https://github.com/avantrec/soco-cli>`_) is a powerful and\nfully-featured command line tool suitable for use in scripts, scheduled tasks, etc. It\nsupports time-based and state-based actions, and repeated commands using loops. Audio\nfiles on the local filesystem can be played back directly on Sonos from the command line.\nMulti-household Sonos systems are supported.\n\nOlder Projects\n^^^^^^^^^^^^^^\n\nMore of a Ruby fan? Not a problem, `Sam Soffes`_ is building out an\nawesome `Ruby gem`_.\n\nLooking for a GUI that\u2019s more than just a sample project? `Joel\nBj\u00f6rkman`_ is building a Sonos Controller GUI\u2013great for folks on Linux\nwhere there isn\u2019t an official Sonos Controller application! Find, fork,\nand contribute to it here: https://github.com/labero/SoCo-Tk.\n\n\nSoCo Gitter Room\n----------------\n\nThere is a `SoCo Gitter discussion room <https://gitter.im/SoCo/SoCo>`_. Feel free to drop by for support, ideas or casual conversation related to SoCo.\n\n\nLicense\n-------\n\nSoCo is released under the `MIT license`_.\n\n\n.. _Sonos speakers: http://www.sonos.com/system/\n.. _Music Hack Day Sydney: http://sydney.musichackday.org/2012/\n.. _blog post: http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/\n.. _Sam Soffes: https://github.com/soffes\n.. _Ruby gem: https://github.com/soffes/sonos\n.. _Joel Bj\u00f6rkman: https://github.com/labero\n.. _MIT license: http://www.opensource.org/licenses/mit-license.php\n.. _Rahim Sonawalla: https://github.com/rahims/SoCo\n.. _GitHub repository: https://github.com/SoCo/SoCo\n.. _team of people: https://github.com/SoCo/SoCo/blob/master/AUTHORS.rst\n.. _SoCo documentation: https://soco.readthedocs.org/en/latest/\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "SoCo (Sonos Controller) is a simple library to control Sonos speakers.",
"version": "0.30.4",
"project_urls": {
"Homepage": "https://github.com/SoCo/SoCo"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e2666ffdd289a526900dafe73dd1c85ec6570d3d6f828b0f58a1acab39ac6a6",
"md5": "e6c6ae3d3bea8993b523499b7711c98a",
"sha256": "b1406cbfd7d42bceeb5f46a32d272dbf240029495b7aad41200a6bb77fc4bd99"
},
"downloads": -1,
"filename": "soco-0.30.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6c6ae3d3bea8993b523499b7711c98a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 162613,
"upload_time": "2024-05-04T16:56:06",
"upload_time_iso_8601": "2024-05-04T16:56:06.835169Z",
"url": "https://files.pythonhosted.org/packages/3e/26/66ffdd289a526900dafe73dd1c85ec6570d3d6f828b0f58a1acab39ac6a6/soco-0.30.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb297018a559b465c302548b58aefdd6d0ea296c232638e9e1fd2c3210105296",
"md5": "12eed173bcb94e08d10379fe14cdbef1",
"sha256": "97c77ad353f8233117659250c71113419d288bc5447148c6bd4a2486e9cfd3be"
},
"downloads": -1,
"filename": "soco-0.30.4.tar.gz",
"has_sig": false,
"md5_digest": "12eed173bcb94e08d10379fe14cdbef1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 732359,
"upload_time": "2024-05-04T16:56:09",
"upload_time_iso_8601": "2024-05-04T16:56:09.497314Z",
"url": "https://files.pythonhosted.org/packages/bb/29/7018a559b465c302548b58aefdd6d0ea296c232638e9e1fd2c3210105296/soco-0.30.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-04 16:56:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SoCo",
"github_project": "SoCo",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "xmltodict",
"specs": []
},
{
"name": "ifaddr",
"specs": []
},
{
"name": "appdirs",
"specs": []
},
{
"name": "lxml",
"specs": []
}
],
"lcname": "soco"
}
JSON
