SoCo 0.16 release notes

SoCo 0.16 is a new version of the SoCo library. This release adds new features and fixes several bugs.

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

New Features and Improvements

  • Make events server configurable (#602)

  • Allow the user a choice in how the event listener is implemented. The default is for the event listener to use the requests library and run in a thread. This update allows the user to run the event listener using the twisted.internet library, by setting the config.EVENTS_MODULE module to point to the events_twisted module. See the example in events_twisted.

  • Stop the event listener when the last active subscription is unsubscribed.

  • Raise SoCoException on an attempt to subscribe a subscription more than once (use Subscription.renew() instead).

  • Allow an optional strict parameter for Subscription.subscribe(), Subscription.renew() and Subscription.unsubscribe(). If set to False, Exceptions will be logged rather than raised. Default: True

  • Upon autorenewal, call Subscription.renew() with the strict flag set to False, so that any Exception is logged, not raised. This is because there is no calling code to catch an Exception.

  • Provide for calling code to set Subscription.auto_renew_fail to refer to a callback function. If an Exception occurs upon autorenewal, this callback will be called with the Exception as the sole parameter.

  • If an Exception occurs upon Subscription.subscribe() or Subscription.renew(), cancel the subscription, unless the Exception was a SoCoException on Subscription.subscribe(). For example, if an Exception occurs because the network went down, the subscription will be cancelled.

  • Use a threading lock with Subscription.subscribe(), Subscription.renew() and Subscription.unsubscribe(), because autorenewal occurs from a thread.

  • Allow the user to configure the event listener IP address that is sent to the Sonos speakers. The default is to auto detect, but it can now be overridden. This allows for more complex network configurations (e.g. using Docker containers) to be supported. (#604)

  • The play_uri method now accepts title arguments that need XML escaping. (#605)

  • A harmless “Could not handle track info” warning has been removed. (#606)

  • Let from_didl_string throw DIDLMetadataErrors, allowing them to be caught in the event handling code. (#601)

  • Added support for object.item.audioItem.audioBook (#618)

Bugfixes

  • Fix DidlMusicAlbum inheriting fields from DidlAudioItem instead of DidlAlbum (#592)