1SoCo 2==== 3 4SoCo (Sonos Controller) is a Python library that allows you to 5control `Sonos speakers`_ programmatically. It was originally created at `Music 6Hack Day Sydney`_ by `Rahim Sonawalla`_ and is now developed by a `team of 7people`_ at its `GitHub repository`_ 8 9For more background on the project, please see Rahim's `blog post 10<http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/>`_. 11 12Visit the `SoCo documentation`_ for a more detailed overview of the functionailty. 13 14.. image:: https://badges.gitter.im/SoCo/SoCo.svg 15 :alt: Join the chat at https://gitter.im/SoCo/SoCo 16 :target: https://gitter.im/SoCo/SoCo?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 17 18.. image:: https://travis-ci.com/SoCo/SoCo.svg?branch=master 19 :target: https://travis-ci.com/SoCo/SoCo 20 :alt: Build Status 21 22.. image:: https://img.shields.io/requires/github/SoCo/SoCo/master.svg?style=flat 23 :target: https://requires.io/github/SoCo/SoCo/requirements/?branch=master 24 :alt: Requirements Status 25 26.. image:: https://img.shields.io/pypi/v/soco.svg?style=flat 27 :target: https://pypi.python.org/pypi/soco/ 28 :alt: Latest PyPI version 29 30WARNING 31------- 32 33Sonos 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. 34 35Issue #557 is a meta issue for this problem and you can use that to track progress on solving the issues, but 36*please refrain from posting "me too" comments* in there. Also, there is no need to open any more separate issue about this. 37 38If you have another music service that should be on the list, comment in #557 39 40Installation 41------------ 42 43SoCo requires Python 3.5 or newer. 44 45Use pip: 46 47``pip install soco`` 48 49 50SoCo depends on a number of Python packages. If you use pip to install Soco, 51the dependencies will be installed automatically for you. If not, you can inspect 52the requirements in the `requirements.txt <https://github.com/SoCo/SoCo/blob/master/requirements.txt>`_ 53file. 54 55 56Basic Usage 57----------- 58 59You can interact with a Sonos Zone Player through a SoCo object. If you know 60the IP address of a Zone Player, you can create a SoCo object directly: 61 62.. code:: python 63 64 >>> from soco import SoCo 65 >>> my_zone = SoCo('192.168.1.101') 66 >>> my_zone.player_name 67 Kitchen 68 >>> my_zone.status_light = True 69 >>> my_zone.volume = 6 70 71 72But perhaps the easiest way is to use the module-level `discover` function. 73This will find all the Zone Players on your network, and return a python 74set containing them: 75 76.. code:: python 77 78 >>> from soco import discover 79 >>> for zone in discover(): 80 ... print(zone.player_name) 81 Living Room 82 Kitchen 83 84 85If you prefer a list to a set: 86 87.. code:: python 88 89 >>> zone_list = list(discover()) 90 >>> zone_list 91 [SoCo("192.168.1.101"), SoCo("192.168.1.102")] 92 >>> zone_list[0].mute = True 93 94Of course, you can also play music! 95 96.. code:: python 97 98 #!/usr/bin/env python 99 from soco import SoCo 100 101 if __name__ == '__main__': 102 sonos = SoCo('192.168.1.102') # Pass in the IP of your Sonos speaker 103 # You could use the discover function instead, if you don't know the IP 104 105 # Pass in a URI to a media file to have it streamed through the Sonos 106 # speaker 107 sonos.play_uri( 108 'http://ia801402.us.archive.org/20/items/TenD2005-07-16.flac16/TenD2005-07-16t10Wonderboy.mp3') 109 110 track = sonos.get_current_track_info() 111 112 print(track['title']) 113 114 sonos.pause() 115 116 # Play a stopped or paused track 117 sonos.play() 118 119Support 120------- 121 122If you need support for SoCo, feel free to post your question in the `SoCo Gitter Room <https://gitter.im/SoCo/SoCo>`_. 123 124Example Applications 125-------------------- 126 127To show off what can be made with SoCo, a simple web application is included in 128the ``examples`` folder. 129 130.. figure:: https://github.com/SoCo/SoCo/raw/master/examples/webapp/screenshot.png 131 :alt: Screenshot of web app 132 133 Screenshot of web app 134 135 136Features 137-------- 138 139SoCo supports the following controls amongst others: 140 141- Play, Pause, Stop 142- Next track, Previous track 143- Volume get and set 144- Mute (or unmute) 145- Get current transport information (if speaker is 146 playing, paused or stopped) 147- Get information about the currently playing track 148 149 - Track title 150 - Artist 151 - Album 152 - Album Art (if available) 153 - Track length 154 - Duration played (for example, 30 seconds into a 3 minute song) 155 - Playlist position (for example, item 5 in the playlist) 156 - Track URI 157 158- Receive events when the player state changes 159- Search for and play music items: 160 161 - Local music library 162 - Webradio via TuneIn and music services (still unstable) 163 - Saved Sonos favorites, favorite radio stations and shows 164 165- Switch the speaker’s source to line-in or TV input (if the Zone Player 166 supports it) 167- Manage the Sonos queue: 168 169 - Get the items in the queue 170 - Add items to the queue 171 - Clear the queue 172 - Play a specific song from the queue 173 174- Join or unjoin speakers from a group 175- Put all Sonos speakers in a network into “party mode”. 176 177- Get or set alarms 178- Get or set sleep timers 179 180- Enable or disable surround speakers or subwoofer 181- Get information regarding a home theater setup: 182 183 - If surround speakers or a subwoofer are paired 184 - Which audio channel a given speaker handles 185 186- Get or set the speaker’s bass and treble EQ 187- Toggle the speaker’s loudness compensation, night mode and dialog mode 188- Toggle the white status light on the unit 189- Get the speaker’s information 190 191 - Zone Name 192 - Zone Icon 193 - UID (usually something like RINCON\_XXXXXXXXXXXXXXXXX) 194 - Serial Number 195 - Software version 196 - Hardware version 197 - MAC Address 198 199- Set the speaker’s Zone Name 200- Start a music library update and determine if one is in progress 201 202SoCo also supports lower level access from Python to all Sonos services 203(e.g. ContentDirectory or RenderingControl). 204 205 206Related Projects 207---------------- 208 209**Socos** is a command line tool for controlling Sonos devices. It is developed 210in conjunction with Soco, but in a `separate repository <https://github.com/SoCo/socos>`_. 211 212**SoCo-CLI** (`soco-cli <https://github.com/avantrec/soco-cli>`_) is a powerful and 213fully-featured command line tool suitable for use in scripts, scheduled tasks, etc. It 214supports time-based and state-based actions, and repeated commands using loops. Audio 215files on the local filesystem can be played back directly on Sonos from the command line. 216Multi-household Sonos systems are supported. 217 218Older Projects 219^^^^^^^^^^^^^^ 220 221More of a Ruby fan? Not a problem, `Sam Soffes`_ is building out an 222awesome `Ruby gem`_. 223 224Looking for a GUI that’s more than just a sample project? `Joel 225Björkman`_ is building a Sonos Controller GUI–great for folks on Linux 226where there isn’t an official Sonos Controller application! Find, fork, 227and contribute to it here: https://github.com/labero/SoCo-Tk. 228 229 230SoCo Gitter Room 231---------------- 232 233There 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. 234 235 236License 237------- 238 239SoCo is released under the `MIT license`_. 240 241 242.. _Sonos speakers: http://www.sonos.com/system/ 243.. _Music Hack Day Sydney: http://sydney.musichackday.org/2012/ 244.. _blog post: http://www.hirahim.com/blog/2012/04/29/dissecting-the-sonos-controller/ 245.. _Sam Soffes: https://github.com/soffes 246.. _Ruby gem: https://github.com/soffes/sonos 247.. _Joel Björkman: https://github.com/labero 248.. _MIT license: http://www.opensource.org/licenses/mit-license.php 249.. _Rahim Sonawalla: https://github.com/rahims/SoCo 250.. _GitHub repository: https://github.com/SoCo/SoCo 251.. _team of people: https://github.com/SoCo/SoCo/blob/master/AUTHORS.rst 252.. _SoCo documentation: https://soco.readthedocs.org/en/latest/ 253