Alarm configuration (#171)
>>> from soco.alarms import Alarm, get_alarms >>> # create an alarm with default properties >>> # my_device is the SoCo instance on which the alarm will be played >>> alarm = Alarm(my_device) >>> print alarm.volume 20 >>> print get_alarms() set() >>> # save the alarm to the Sonos system >>> alarm.save() >>> print get_alarms() set([<Alarm id:88@15:26:15 at 0x107abb090>]) >>> # update the alarm >>> alarm.recurrence = "ONCE" >>> # Save it again for the change to take effect >>> alarm.save() >>> # Remove it >>> alarm.remove() >>> print get_alarms() set()
import soco soc = soco.SoCo('...ipaddress..') some_album = soc.get_albums()['item_list'] tracks_in_that_album = soc.browse(some_album)
Support for full Album Art URIs (#207)
Support for music queues (#214)
queue = soco.get_queue() for item in queue: print item.title print queue.number_returned print queue.total_matches print queue.update_id
Support for processing of LastChange events (#194)
Support for write operations on Playlists (#198)
- Improved test coverage (#159, #184 <https://github.com/SoCo/SoCo/pull/184>)
- Fixes for Python 2.6 support (#175)
- Event-subscriptions can be auto-renewed (#179)
- The SoCo class can replaced by a custom implementation (#180 <https://github.com/SoCo/SoCo/pull/180>)
- The cache can be globally disabled (#180 <https://github.com/SoCo/SoCo/pull/180>)
- Music Library data structures are constructed for DIDL XML content (#191).
- Added previously removed support for PyPy (#205)
- All music library methods (browse, get_tracks etc. #203 and get_queue #214) now returns container objects instead of dicts or lists. The metadata is now available from these container objects as named attributes, so e.g. on a queue object you can access the size with queue.total_matches.
- Music library methods return container objects instead of dicts and lists (see above). The old way of accessing that metadata (by dictionary type indexing), has been deprecated and is planned to be removed 3 releases after 0.9.
- Re-added support for Python 2.6 (#154)
- Added SoCo.get_sonos_playlists() (#114)
- Added methods for working with speaker topology
soco.SoCo.group retrieves the soco.groups.ZoneGroup to which the speaker belongs (#132). The group itself has a soco.groups.ZoneGroup.member attribute returning all of its members. Iterating directly over the group is possible as well.
- z1 = SoCo('192.168.1.101') z2 = SoCo('192.168.1.102') z1.join(z2)
soco.SoCo.is_bridge indicates if the SoCo instance represents a bridge.
A new soco.plugins.spotify.Spotify plugin allows querying and playing the Spotify music catalogue (#119):
from soco.plugins.spotify import Spotify from soco.plugins.spotify import SpotifyTrack # create a new plugin, pass the soco instance to it myplugin = Spotify(device) print 'index: ' + str(myplugin.add_track_to_queue(SpotifyTrack(' spotify:track:20DfkHC5grnKNJCzZQB6KC'))) print 'index: ' + str(myplugin.add_album_to_queue(SpotifyAlbum(' spotify:album:6a50SaJpvdWDp13t0wUcPU')))
A soco.data_structures.URI item can be passed to add_to_queue which allows playing music from arbitrary URIs (#147)
import soco from soco.data_structures import URI soc = soco.SoCo('...ip_address...') uri = URI('http://www.noiseaddicts.com/samples/17.mp3') soc.add_to_queue(uri)
Network requests can be cached for better performance (#131).
It is now possible to subscribe to events of a service using its subscribe method, which returns a Subscription object. To unsubscribe, call the unsubscribe method on the returned object. (#121, #130)
Support for reading and setting crossfade (#165)
All information about queue and music library items, like e.g. the title and album of a track, are now included in data structure classes instead of dictionaries (the classes are available in the The data_structures sub module sub-module ). This advantages of this approach are:
- The type of the item is identifiable by its class name
- They have useful __str__ representations and an __equals__ method
- Information is available as named attributes
- They have the ability to produce their own UPnP meta-data (which is used by the add_to_queue method).
See the Backwards Compatibility notice below.
A webservice analyzer has been added in dev_tools/analyse_ws.py (#46).
The commandline interface has been split into a separate project socos. It provides an command line interface on top of the SoCo library, and allows users to control their Sonos speakers from scripts and from an interactive shell.
Python 3.2 and later is now supported in addition to 2.7.
A simple version of the first plugin for the Wimp service has been added (#93).
The new soco.discover() method provides an easier interface for discovering speakers in your network. SonosDiscovery has been deprecated in favour of it (see Backwards Compatability below).
SoCo instances are now singletons per IP address. For any given IP address, there is only one SoCo instance.
The code for generating the XML to be sent to Sonos devices has been completely rewritten, and it is now much easier to add new functionality. All services exposed by Sonos zones are now available if you need them (#48).
Please read the section below carefully when upgrading to SoCo 0.7.
The move to using data structure classes for music item information instead of dictionaries introduces some backwards incompatible changes in the library (see #83). The get_queue and get_library_information functions (and all methods derived from the latter) are affected. In the data structure classes, information like e.g. the title is now available as named attributes. This means that by the update to 0.7 it will also be necessary to update your code like e.g:
# Version < 0.7 for item in soco.get_queue(): print item['title'] # Version >=0.7 for item in soco.get_queue(): print item.title
Instead of the following
>>> import soco >>> d = soco.SonosDiscovery() >>> ips = d.get_speaker_ips() >>> for i in ips: ... s = soco.SoCo(i) ... print s.player_name
you should now write
>>> import soco >>> for s in soco.discover(): ... print s.player_name
- Music library information: Several methods has been added to get information about the music library. It is now possible to get e.g. lists of tracks, albums and artists.
- Raise exceptions on errors: Several SoCo specific exceptions has been added. These exceptions are now raised e.g. when SoCo encounters communications errors instead of returning an error codes. This introduces a backwards incompatible change in SoCo that all users should be aware of.
For SoCo developers¶
- Added plugin framework: A plugin framework has been added to SoCo. The primary purpose of this framework is to provide a natural partition of the code, in which code that is specific to the individual music services is separated out into its own class as a plugin. Read more about the plugin framework in the docs.
- Added unit testing framework: A unit testing framework has been added to SoCo and unit tests has been written for 30% of the methods in the SoCo class. Please consider supplementing any new functionality with the appropriate unit tests and fell free to write unit tests for any of the methods that are still missing.
- Data structure change: For the next version of SoCo it is planned to change the way SoCo handles data. It is planned to use classes for all the data structures, both internally and for in- and output. This will introduce a backwards incompatible change and therefore users of SoCo should be aware that extra work will be needed upon upgrading from version 0.6 to 0.7. The data structure changes will be described in more detail in the release notes for version 0.7.