soco.services module

Classes representing Sonos UPnP services.

>>> import soco
>>> device = soco.SoCo('192.168.1.102')
>>> print(RenderingControl(device).GetMute([('InstanceID', 0),
...     ('Channel', 'Master')]))
{'CurrentMute': '0'}
>>> r = ContentDirectory(device).Browse([
...    ('ObjectID', 'Q:0'),
...    ('BrowseFlag', 'BrowseDirectChildren'),
...    ('Filter', '*'),
...    ('StartingIndex', '0'),
...    ('RequestedCount', '100'),
...    ('SortCriteria', '')
...    ])
>>> print(r['Result'])
<?xml version="1.0" ?><DIDL-Lite xmlns="urn:schemas-upnp-org:metadata ...
>>> for action, in_args, out_args in AlarmClock(device).iter_actions():
...    print(action, in_args, out_args)
...
SetFormat [Argument(name='DesiredTimeFormat', vartype='string'), Argument(
name='DesiredDateFormat', vartype='string')] []
GetFormat [] [Argument(name='CurrentTimeFormat', vartype='string'),
Argument(name='CurrentDateFormat', vartype='string')] ...
class soco.services.Action[source]

A UPnP Action and its arguments.

Create new instance of ActionBase(name, in_args, out_args)

class soco.services.Argument[source]

A UPnP Argument and its type.

Create new instance of ArgumentBase(name, vartype)

class soco.services.Vartype[source]

An argument type with default value and range.

Create new instance of VartypeBase(datatype, default, list, range)

class soco.services.Service(soco)[source]

A class representing a UPnP service.

This is the base class for all Sonos Service classes. This class has a dynamic method dispatcher. Calls to methods which are not explicitly defined here are dispatched automatically to the service action with the same name.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
soco = None

SoCo – The SoCo instance to which UPnP Actions are sent

service_type = None

str – The UPnP service type.

version = None

str – The UPnP service version.

base_url = None

str – The base URL for sending UPnP Actions.

control_url = None

str – The UPnP Control URL.

scpd_url = None

str – The service control protocol description URL.

event_subscription_url = None

str – The service eventing subscription URL.

cache = None

A cache for storing the result of network calls. By default, this is a TimedCache with a default timeout=0.

static wrap_arguments(args=None)[source]

Wrap a list of tuples in xml ready to pass into a SOAP request.

Parameters:args (list) – a list of (name, value) tuples specifying the name of each argument and its value, eg [('InstanceID', 0), ('Speed', 1)]. The value can be a string or something with a string representation. The arguments are escaped and wrapped in <name> and <value> tags.

Example

>>> from soco import SoCo
>>> device = SoCo('192.168.1.101')
>>> s = Service(device)
>>> print(s.wrap_arguments([('InstanceID', 0), ('Speed', 1)]))
<InstanceID>0</InstanceID><Speed>1</Speed>'
static unwrap_arguments(xml_response)[source]

Extract arguments and their values from a SOAP response.

Parameters:xml_response (str) – SOAP/xml response text (unicode, not utf-8).
Returns:a dict of {argument_name: value} items.
Return type:dict
compose_args(action_name, in_argdict)[source]

Compose the argument list from an argument dictionary, with respect for default values.

Parameters:
  • action_name (str) – The name of the action to be performed.
  • in_argdict (dict) – Arguments as a dict, eg ``{‘InstanceID’: 0, ‘Speed’: 1}. The values can be a string or something with a string representation.
Returns:

a list of (name, value) tuples.

Return type:

list

Raises:
  • AttributeError – If this service does not support the action.
  • ValueError – If the argument lists do not match the action signature.
build_command(action, args=None)[source]

Build a SOAP request.

Parameters:
  • action (str) – the name of an action (a string as specified in the service description XML file) to be sent.
  • args (list, optional) – Relevant arguments as a list of (name, value) tuples.
Returns:

a tuple containing the POST headers (as a dict) and a

string containing the relevant SOAP body. Does not set content-length, or host headers, which are completed upon sending.

Return type:

tuple

send_command(action, args=None, cache=None, cache_timeout=None, **kwargs)[source]

Send a command to a Sonos device.

Parameters:
  • action (str) – the name of an action (a string as specified in the service description XML file) to be sent.
  • args (list, optional) – Relevant arguments as a list of (name, value) tuples, as an alternative to kwargs.
  • cache (Cache) – A cache is operated so that the result will be stored for up to cache_timeout seconds, and a subsequent call with the same arguments within that period will be returned from the cache, saving a further network call. The cache may be invalidated or even primed from another thread (for example if a UPnP event is received to indicate that the state of the Sonos device has changed). If cache_timeout is missing or None, the cache will use a default value (which may be 0 - see cache). By default, the cache identified by the service’s cache attribute will be used, but a different cache object may be specified in the cache parameter.
  • kwargs – Relevant arguments for the command.
Returns:

a dict of {argument_name, value} items.

Return type:

dict

Raises:
handle_upnp_error(xml_error)[source]

Disect a UPnP error, and raise an appropriate exception.

Parameters:xml_error (str) – a unicode string containing the body of the UPnP/SOAP Fault response. Raises an exception containing the error code.
subscribe(requested_timeout=None, auto_renew=False, event_queue=None)[source]

Subscribe to the service’s events.

Parameters:
  • requested_timeout (int, optional) – If requested_timeout is provided, a subscription valid for that number of seconds will be requested, but not guaranteed. Check Subscription.timeout on return to find out what period of validity is actually allocated.
  • auto_renew (bool) – If auto_renew is True, the subscription will automatically be renewed just before it expires, if possible. Default is False.
  • event_queue (Queue) – a thread-safe queue object on which received events will be put. If not specified, a (Queue) will be created and used.
Returns:

an insance of Subscription, representing

the new subscription.

Return type:

Subscription

To unsubscribe, call the unsubscribe method on the returned object.

actions

The service’s actions with their arguments.

Returns:A list of Action namedtuples, consisting of action_name (str), in_args (list of Argument namedtuples, consisting of name and argtype), and out_args (ditto).
Return type:list(Action)
The return value looks like this::
[
Action(

name=’GetMute’, in_args=[

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 13)

Unexpected indentation.

Argument(name=’InstanceID’, …), Argument(

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 15)

Unexpected indentation.
name=’Channel’, vartype=’string’, list=[‘Master’, ‘LF’, ‘RF’, ‘SpeakerOnly’], range=None

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 19)

Block quote ends without a blank line; unexpected unindent.

)

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 20)

Block quote ends without a blank line; unexpected unindent.

], out_args=[

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 22)

Unexpected indentation.
Argument(name=’CurrentMute, …)

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 23)

Block quote ends without a blank line; unexpected unindent.

]

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 24)

Definition list ends without a blank line; unexpected unindent.

) Action(…)

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/soco/checkouts/latest/soco/services.py:docstring of soco.services.Service.actions, line 26)

Definition list ends without a blank line; unexpected unindent.

]

Its string representation will look like this::
GetMute(InstanceID: ui4, Channel: [Master, LF, RF, SpeakerOnly]) -> {CurrentMute: boolean}
iter_actions()[source]

Yield the service’s actions with their arguments.

Yields:Action – the next action.

Each action is an Action namedtuple, consisting of action_name (a string), in_args (a list of Argument namedtuples consisting of name and argtype), and out_args (ditto), eg:

Action(
    name='SetFormat',
    in_args=[
        Argument(name='DesiredTimeFormat', vartype=<Vartype>),
        Argument(name='DesiredDateFormat', vartype=<Vartype>)],
    out_args=[]
)
event_vars

The service’s eventable variables.

Returns:A list of (variable name, data type) tuples.
Return type:list(tuple)
iter_event_vars()[source]

Yield the services eventable variables.

Yields:tuple – a tuple of (variable name, data type).
class soco.services.AlarmClock(soco)[source]

Sonos alarm service, for setting and getting time and alarms.

class soco.services.MusicServices(soco)[source]

Sonos music services service, for functions related to 3rd party music services.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
class soco.services.DeviceProperties(soco)[source]

Sonos device properties service, for functions relating to zones, LED state, stereo pairs etc.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
class soco.services.SystemProperties(soco)[source]

Sonos system properties service, for functions relating to authentication etc.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
class soco.services.ZoneGroupTopology(soco)[source]

Sonos zone group topology service, for functions relating to network topology, diagnostics and updates.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
GetZoneGroupState(*args, **kwargs)[source]

Overrides default handling to use the global shared zone group state cache, unless another cache is specified.

class soco.services.GroupManagement(soco)[source]

Sonos group management service, for services relating to groups.

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
class soco.services.QPlay(soco)[source]

Sonos Tencent QPlay service (a Chinese music service)

Parameters:soco (SoCo) – A SoCo instance to which the UPnP Actions will be sent
class soco.services.ContentDirectory(soco)[source]

UPnP standard Content Directory service, for functions relating to browsing, searching and listing available music.

class soco.services.MS_ConnectionManager(soco)[source]

UPnP standard connection manager service for the media server.

class soco.services.RenderingControl(soco)[source]

UPnP standard rendering control service, for functions relating to playback rendering, eg bass, treble, volume and EQ.

class soco.services.MR_ConnectionManager(soco)[source]

UPnP standard connection manager service for the media renderer.

class soco.services.AVTransport(soco)[source]

UPnP standard AV Transport service, for functions relating to transport management, eg play, stop, seek, playlists etc.

class soco.services.Queue(soco)[source]

Sonos queue service, for functions relating to queue management, saving queues etc.

class soco.services.GroupRenderingControl(soco)[source]

Sonos group rendering control service, for functions relating to group volume etc.