Skip to content

Latest commit

 

History

History
49 lines (39 loc) · 2.93 KB

data-structures-mod.rst

File metadata and controls

49 lines (39 loc) · 2.93 KB
Raw

The Music Library Data Structures

This page contains a thorough introduction to the data structures used for the music library items1. The data structures are implemented in the :pysoco.data_structures module and they are used to represent the metadata for music items, such as music tracks, albums, genres and playlists.

Many music related items have a lot of metadata in common. For example, a music track and an album may both have artist and title metadata. It is therefore possible and useful to derive a hierarchy of items, and to implement them as a class hierarchy. The hierarchy which Sonos has adopted is represented by the DIDL Lite xml schema (DIDL stands for 'Digital Item Description Language'. For more details, see the UPnP specifications (PDF).

In the data_structures module, each class represents a particular DIDL-Lite object and is illustrated in the figure below <figure-inheritance>. The black lines are the lines of inheritance, going from left to right.

All data structures are subclasses of the abstract Didl Object item <soco.data_structures.DidlObject> class. You should never need to instantiate this directly. The subclasses are divided into :pyContainers <soco.data_structures.DidlContainer> and :pyItems <soco.data_structures.DidlObject>. In general, :pyContainers <soco.data_structures.DidlContainer> are things, like playlists, which are intended to contain other items.

At the bottom of the class hierarchy are 10 types of :pyDIDL items <.DidlObject>. On each of these classes, relevant metadata items are available as attributes (though they may be implemented as properties). Each has a :pytitle <.DidlObject.title>, a :pyURI <.DidlObject.uri>, an :pyitem id <.DidlObject.item_id> and a :pyUPnP class <.DidlObject.item_class>. Some have other attributes. For example, :py.DidlMusicTrack and :py.DidlMusicAlbum have some extra fields such as :pyalbum <.DidlMusicTrack.album>, :pyalbum_art_uri <.DidlMusicTrack.album_art_uri> and :pycreator <.DidlMusicTrack.creator>.

One of the more important attributes which each class has is :pydidl_metadata <.DidlObject.didl_metadata>. It is used to produce the metadata that is sent to the Sonos® units in the form of XML. This metadata is created in an almost identical way for each class, which is why it is implemented in :py.DidlObject. It uses the URI, the UPnP class and the title that the items are instantiated with, along with the two class variables parent_id and _translation.

Footnotes

  1. Text of the first footnote.↩