soco.data_structures module

This module contains classes for handling DIDL-Lite metadata.

DIDL is the Digital Item Declaration Language , an XML schema which is part of MPEG21. DIDL-Lite is a cut-down version of the schema which is part of the UPnP ContentDirectory specification. It is the XML schema used by Sonos for carrying metadata representing many items such as tracks, playlists, composers, albums etc. Although Sonos uses ContentDirectory v1, the document for v2 [pdf] is more helpful.

soco.data_structures.to_didl_string(*args)[source]

Convert any number of DidlObjects to a unicode xml string.

Parameters

*args (DidlObject) – One or more DidlObject (or subclass) instances.

Returns

A unicode string representation of DIDL-Lite XML in the form '<DIDL-Lite ...>...</DIDL-Lite>'.

Return type

str

soco.data_structures.didl_class_to_soco_class(didl_class)[source]

Translate a DIDL-Lite class to the corresponding SoCo data structures class

soco.data_structures.form_name(didl_class)[source]

Return an improvised name for vendor extended classes

class soco.data_structures.DidlResource(uri, protocol_info, import_uri=None, size=None, duration=None, bitrate=None, sample_frequency=None, bits_per_sample=None, nr_audio_channels=None, resolution=None, color_depth=None, protection=None)[source]

Identifies a resource, typically some type of a binary asset, such as a song.

It is represented in XML by a <res> element, which contains a uri that identifies the resource.

Parameters
  • uri (str) – value of the <res> tag, typically a URI. It must be properly escaped (percent encoded) as described in RFC 3986

  • protocol_info (str) – a string in the form a:b:c:d that identifies the streaming or transport protocol for transmitting the resource. A value is required. For more information see section 2.5.2 of the UPnP specification [ pdf]

  • import_uri (str, optional) – uri locator for resource update.

  • size (int, optional) – size in bytes.

  • duration (str, optional) – duration of the playback of the res at normal speed (H*:MM:SS:F* or H*:MM:SS:F0/F1)

  • bitrate (int, optional) – bitrate in bytes/second.

  • sample_frequency (int, optional) – sample frequency in Hz.

  • bits_per_sample (int, optional) – bits per sample.

  • nr_audio_channels (int, optional) – number of audio channels.

  • resolution (str, optional) – resolution of the resource (X*Y).

  • color_depth (int, optional) – color depth in bits.

  • protection (str, optional) – statement of protection type.

Note

Not all of the parameters are used by Sonos. In general, only uri, protocol_info and duration seem to be important.

uri

a percent encoded URI

Type

(str)

protocol_info

protocol information.

Type

(str)

duration

playback duration

Type

str

classmethod from_element(element)[source]

Set the resource properties from a <res> element.

Parameters

element (Element) – The <res> element

to_element()[source]

Return an ElementTree Element based on this resource.

Returns

an Element.

Return type

Element

to_dict(remove_nones=False)[source]

Return a dict representation of the DidlResource.

Parameters

remove_nones (bool, optional) – Optionally remove dictionary elements when their value is None.

Returns

a dict representing the DidlResource

Return type

dict

classmethod from_dict(content)[source]

Create an instance from a dict.

An alternative constructor. Equivalent to DidlResource(**content).

Parameters

content (dict) – a dict containing metadata information. Required. Valid keys are the same as the parameters for DidlResource.

class soco.data_structures.DidlMetaClass(name, bases, attrs)[source]

Meta class for all Didl objects.

Create a new instance.

Parameters
  • name (str) – Name of the class.

  • bases (tuple) – Base classes.

  • attrs (dict) – attributes defined for the class.

class soco.data_structures.DidlObject(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Abstract base class for all DIDL-Lite items.

You should not need to instantiate this. Its XML representation looks like this:

<DIDL-Lite xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/"
 xmlns:dc="http://purl.org/dc/elements/1.1/"
 xmlns:r="urn:schemas-rinconnetworks-com:metadata-1-0/"
 xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/">
  <item id="...self.item_id..." parentID="...cls.parent_id..."
    restricted="true">
    <dc:title>...self.title...</dc:title>
    <upnp:class>...self.item_class...</upnp:class>
    <desc id="cdudn"
      nameSpace="urn:schemas-rinconnetworks-com:metadata-1-0/">
      RINCON_AssociatedZPUDN
    </desc>
  </item>
</DIDL-Lite>
Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

classmethod from_element(element)[source]

Create an instance of this class from an ElementTree xml Element.

An alternative constructor. The element must be a DIDL-Lite <item> or <container> element, and must be properly namespaced.

Parameters

xml (Element) – An Element object.

classmethod from_dict(content)[source]

Create an instance from a dict.

An alternative constructor. Equivalent to DidlObject(**content).

Parameters

content (dict) – a dict containing metadata information. Required. Valid keys are the same as the parameters for DidlObject.

to_dict(remove_nones=False)[source]

Return the dict representation of the instance.

Parameters

remove_nones – Optionally remove dictionary elements when their value is None.

to_element(include_namespaces=False)[source]

Return an ElementTree Element representing this instance.

Parameters

include_namespaces (bool, optional) – If True, include xml namespace attributes on the root element

Returns

an Element.

Return type

Element

get_uri(resource_nr=0)[source]

Return the uri to use for playing this item.

Parameters

resource_nr (int) – The index of the resource. Note that there is no known object with more than one resource, so you can probably keep the default value (0).

Returns

The uri.

Return type

str

set_uri(uri, resource_nr=0, protocol_info=None)[source]

Set a resource uri for this instance. If no resource exists, create a new one with the given protocol info.

Parameters
  • uri (str) – The resource uri.

  • resource_nr (int) – The index of the resource on which to set the uri. If it does not exist, a new resource is added to the list. Note that by default, only the uri of the first resource is used for playing the item.

  • protocol_info (str) – Protocol info for the resource. If none is given and the resource does not exist yet, a default protocol info is constructed as '[uri prefix]:*:*:*'.

class soco.data_structures.DidlItem(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

A basic content directory item.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'creator': ('dc', 'creator'), 'radio_show': ('r', 'radioShowMd'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAudioItem(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

An audio item.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'creator': ('dc', 'creator'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'publisher': ('dc', 'publisher'), 'radio_show': ('r', 'radioShowMd'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicTrack(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library track.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem.musicTrack'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album': ('upnp', 'album'), 'album_art_uri': ('upnp', 'albumArtURI'), 'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'original_track_number': ('upnp', 'originalTrackNumber'), 'playlist': ('upnp', 'playlist'), 'publisher': ('dc', 'publisher'), 'radio_show': ('r', 'radioShowMd'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAudioBook(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents an audio book.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem.audioBook'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'producer': ('upnp', 'producer'), 'publisher': ('dc', 'publisher'), 'radio_show': ('r', 'radioShowMd'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'storageMedium': ('upnp', 'storageMedium'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAudioBroadcast(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents an audio broadcast.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem.audioBroadcast'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'channel_nr': ('upnp', 'channelNr'), 'creator': ('dc', 'creator'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'publisher': ('dc', 'publisher'), 'radio_call_sign': ('upnp', 'radioCallSign'), 'radio_show': ('r', 'radioShowMd'), 'radio_station_id': ('upnp', 'radioStationID'), 'region': ('upnp', 'region'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlRecentShow(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a recent radio show/podcast.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem.musicTrack.recentShow'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album': ('upnp', 'album'), 'album_art_uri': ('upnp', 'albumArtURI'), 'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'original_track_number': ('upnp', 'originalTrackNumber'), 'playlist': ('upnp', 'playlist'), 'publisher': ('dc', 'publisher'), 'radio_show': ('r', 'radioShowMd'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAudioBroadcastFavorite(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents an audio broadcast Sonos favorite.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.item.audioItem.audioBroadcast.sonos-favorite'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'channel_nr': ('upnp', 'channelNr'), 'creator': ('dc', 'creator'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'publisher': ('dc', 'publisher'), 'radio_call_sign': ('upnp', 'radioCallSign'), 'radio_show': ('r', 'radioShowMd'), 'radio_station_id': ('upnp', 'radioStationID'), 'region': ('upnp', 'region'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'stream_content': ('r', 'streamContent'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlFavorite(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a Sonos favorite.

Note that the favorite itself isn’t playable in all cases, please use the object returned by favorite.reference instead.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.itemobject.item.sonos-favorite'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'creator': ('dc', 'creator'), 'description': ('r', 'description'), 'favorite_nr': ('r', 'ordinal'), 'radio_show': ('r', 'radioShowMd'), 'resource_meta_data': ('r', 'resMD'), 'stream_content': ('r', 'streamContent'), 'type': ('r', 'type'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

property reference

The Didl object this favorite refers to.

class soco.data_structures.DidlContainer(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library container.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAlbum(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

A content directory album.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.album'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'long_description': ('upnp', 'longDescription'), 'publisher': ('dc', 'publisher'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicAlbum(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library album.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.album.musicAlbum'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'long_description': ('upnp', 'longDescription'), 'producer': ('upnp', 'producer'), 'publisher': ('dc', 'publisher'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'toc': ('upnp', 'toc'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicAlbumFavorite(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a Sonos favorite music library album.

This class is not part of the DIDL spec and is Sonos specific.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.album.musicAlbum.sonos-favorite'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'long_description': ('upnp', 'longDescription'), 'producer': ('upnp', 'producer'), 'publisher': ('dc', 'publisher'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'toc': ('upnp', 'toc'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicAlbumCompilation(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a Sonos favorite music library compilation.

This class is not part of the DIDL spec and is Sonos specific.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.album.musicAlbum.compilation'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'album_art_uri': ('upnp', 'albumArtURI'), 'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'long_description': ('upnp', 'longDescription'), 'producer': ('upnp', 'producer'), 'publisher': ('dc', 'publisher'), 'relation': ('dc', 'relation'), 'rights': ('dc', 'rights'), 'toc': ('upnp', 'toc'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlPerson(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

A content directory class representing a person.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.person'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'language': ('dc', 'language'), 'write_status': ('upnp', 'writeStatus')}

dfdf

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlComposer(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library composer.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.person.composer'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'language': ('dc', 'language'), 'write_status': ('upnp', 'writeStatus')}

dfdf

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicArtist(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library artist.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.person.musicArtist'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'artist_discography_uri': ('upnp', 'artistDiscographyURI'), 'creator': ('dc', 'creator'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'write_status': ('upnp', 'writeStatus')}

dfdf

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlAlbumList(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library album list.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.albumlist'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlPlaylistContainer(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music library play list.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.playlistContainer'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'producer': ('dc', 'producer'), 'rights': ('dc', 'rights'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlSameArtist(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents all tracks by a single artist.

This type is returned by browsing an artist or a composer

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.playlistContainer.sameArtist'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'producer': ('dc', 'producer'), 'rights': ('dc', 'rights'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlPlaylistContainerFavorite(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a Sonos favorite play list.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.playlistContainer.sonos-favorite'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'producer': ('dc', 'producer'), 'rights': ('dc', 'rights'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlPlaylistContainerTracklist(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a Sonos tracklist.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.playlistContainer.tracklist'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'artist': ('upnp', 'artist'), 'contributor': ('dc', 'contributor'), 'creator': ('dc', 'creator'), 'date': ('dc', 'date'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'language': ('dc', 'language'), 'long_description': ('upnp', 'longDescription'), 'producer': ('dc', 'producer'), 'rights': ('dc', 'rights'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlGenre(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

A content directory class representing a general genre.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.genre'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'long_description': ('upnp', 'longDescription'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlMusicGenre(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a music genre.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.genre.musicGenre'

str - the DIDL Lite class for this object.

tag = 'item'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'description': ('dc', 'description'), 'genre': ('upnp', 'genre'), 'long_description': ('upnp', 'longDescription'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.DidlRadioShow(title, parent_id, item_id, restricted=True, resources=None, desc='RINCON_AssociatedZPUDN', **kwargs)[source]

Class that represents a radio show.

Parameters
  • title (str) – the title for the item.

  • parent_id (str) – the parent ID for the item.

  • item_id (str) – the ID for the item.

  • restricted (bool) – whether the item can be modified. Default True

  • resources (list, optional) – a list of resources for this object.

  • None. (Default) –

  • desc (str) – A DIDL descriptor, default 'RINCON_AssociatedZPUDN'. This is not the same as “description”. It is used for identifying the relevant third party music service.

  • **kwargs – Extra metadata. What is allowed depends on the _translation class attribute, which in turn depends on the DIDL class.

item_class = 'object.container.radioShow'

str - the DIDL Lite class for this object.

tag = 'container'

str - the XML element tag name used for this instance.

_translation = {'creator': ('dc', 'creator'), 'write_status': ('upnp', 'writeStatus')}

dict - A dict used to translate between instance attribute names and XML tags/namespaces. It also serves to define the allowed tags/attributes for this instance. Each key an attribute name and each key is a (namespace, tag) tuple.

class soco.data_structures.ListOfMusicInfoItems(items, number_returned, total_matches, update_id)[source]

Abstract container class for a list of music information items.

Instances of this class are returned from queries into the music library or to music services. The attributes total_matches and number_returned are used to ascertain whether paging is required in order to retrive all elements of the query. total_matches is the total number of results to the query and number_returned is the number of results actually returned. If the two differ, paging is required. Paging is typically performed with the start and max_items arguments to the query method. See e.g. the get_music_library_information() method for details.

property number_returned

the number of returned matches.

Type

str

property total_matches

the number of total matches.

Type

str

property update_id

the update ID.

Type

str

class soco.data_structures.SearchResult(items, search_type, number_returned, total_matches, update_id)[source]

Container class that represents a search or browse result.

Browse is just a special case of search.

property search_type

the search type.

Type

str

class soco.data_structures.Queue(items, number_returned, total_matches, update_id)[source]

Container class that represents a queue.