The Music Library Data Structures
This page contains a thorough introduction to the data structures used
for the music library items. The data
structures are implemented in the soco.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. The
black lines are the lines of inheritance, going from left to right.
digraph inheritanceb4197a4333 {
bgcolor=transparent;
rankdir=LR;
size="";
"DidlAlbum" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAlbum",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="A content directory album."];
"DidlContainer" -> "DidlAlbum" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAlbumList" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAlbumList",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library album list."];
"DidlContainer" -> "DidlAlbumList" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAudioBook" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAudioBook",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents an audio book."];
"DidlAudioItem" -> "DidlAudioBook" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAudioBroadcast" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAudioBroadcast",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents an audio broadcast."];
"DidlAudioItem" -> "DidlAudioBroadcast" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAudioBroadcastFavorite" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAudioBroadcastFavorite",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents an audio broadcast Sonos favorite."];
"DidlAudioBroadcast" -> "DidlAudioBroadcastFavorite" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAudioItem" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAudioItem",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="An audio item."];
"DidlItem" -> "DidlAudioItem" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlAudioLineIn" [URL="../api/soco.data_structures.html#soco.data_structures.DidlAudioLineIn",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents an audio line in."];
"DidlAudioItem" -> "DidlAudioLineIn" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlComposer" [URL="../api/soco.data_structures.html#soco.data_structures.DidlComposer",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library composer."];
"DidlPerson" -> "DidlComposer" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlContainer" [URL="../api/soco.data_structures.html#soco.data_structures.DidlContainer",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library container."];
"DidlObject" -> "DidlContainer" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlFavorite" [URL="../api/soco.data_structures.html#soco.data_structures.DidlFavorite",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a Sonos favorite."];
"DidlItem" -> "DidlFavorite" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlGenre" [URL="../api/soco.data_structures.html#soco.data_structures.DidlGenre",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="A content directory class representing a general genre."];
"DidlContainer" -> "DidlGenre" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlItem" [URL="../api/soco.data_structures.html#soco.data_structures.DidlItem",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="A basic content directory item."];
"DidlObject" -> "DidlItem" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMetaClass" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMetaClass",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Meta class for all Didl objects."];
"DidlMusicAlbum" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicAlbum",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library album."];
"DidlAlbum" -> "DidlMusicAlbum" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMusicAlbumCompilation" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicAlbumCompilation",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a Sonos favorite music library compilation."];
"DidlMusicAlbum" -> "DidlMusicAlbumCompilation" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMusicAlbumFavorite" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicAlbumFavorite",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a Sonos favorite music library album."];
"DidlMusicAlbum" -> "DidlMusicAlbumFavorite" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMusicArtist" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicArtist",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library artist."];
"DidlPerson" -> "DidlMusicArtist" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMusicGenre" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicGenre",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music genre."];
"DidlGenre" -> "DidlMusicGenre" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlMusicTrack" [URL="../api/soco.data_structures.html#soco.data_structures.DidlMusicTrack",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library track."];
"DidlAudioItem" -> "DidlMusicTrack" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlObject" [URL="../api/soco.data_structures.html#soco.data_structures.DidlObject",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Abstract base class for all DIDL-Lite items."];
"DidlPerson" [URL="../api/soco.data_structures.html#soco.data_structures.DidlPerson",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="A content directory class representing a person."];
"DidlContainer" -> "DidlPerson" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlPlaylistContainer" [URL="../api/soco.data_structures.html#soco.data_structures.DidlPlaylistContainer",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a music library play list."];
"DidlContainer" -> "DidlPlaylistContainer" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlPlaylistContainerFavorite" [URL="../api/soco.data_structures.html#soco.data_structures.DidlPlaylistContainerFavorite",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a Sonos favorite play list."];
"DidlPlaylistContainer" -> "DidlPlaylistContainerFavorite" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlPlaylistContainerTracklist" [URL="../api/soco.data_structures.html#soco.data_structures.DidlPlaylistContainerTracklist",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a Sonos tracklist."];
"DidlPlaylistContainer" -> "DidlPlaylistContainerTracklist" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlRadioShow" [URL="../api/soco.data_structures.html#soco.data_structures.DidlRadioShow",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a radio show."];
"DidlContainer" -> "DidlRadioShow" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlRecentShow" [URL="../api/soco.data_structures.html#soco.data_structures.DidlRecentShow",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents a recent radio show/podcast."];
"DidlMusicTrack" -> "DidlRecentShow" [arrowsize=0.5,style="setlinewidth(0.5)"];
"DidlResource" [URL="../api/soco.data_structures.html#soco.data_structures.DidlResource",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Identifies a resource, typically some type of a binary asset, such as a"];
"DidlSameArtist" [URL="../api/soco.data_structures.html#soco.data_structures.DidlSameArtist",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Class that represents all tracks by a single artist."];
"DidlPlaylistContainer" -> "DidlSameArtist" [arrowsize=0.5,style="setlinewidth(0.5)"];
"ListOfMusicInfoItems" [URL="../api/soco.data_structures.html#soco.data_structures.ListOfMusicInfoItems",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Abstract container class for a list of music information items."];
"Queue" [URL="../api/soco.data_structures.html#soco.data_structures.Queue",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Container class that represents a queue."];
"ListOfMusicInfoItems" -> "Queue" [arrowsize=0.5,style="setlinewidth(0.5)"];
"SearchResult" [URL="../api/soco.data_structures.html#soco.data_structures.SearchResult",color=dodgerblue,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=14,height=0.75,shape=box,style=rounded,target="_top",tooltip="Container class that represents a search or browse result."];
"ListOfMusicInfoItems" -> "SearchResult" [arrowsize=0.5,style="setlinewidth(0.5)"];
}
All data structures are subclasses of the abstract Didl Object item class. You should never need to instantiate this directly. The subclasses are divided into Containers and Items. In general, Containers are things, like playlists, which are intended to contain other items.
At the bottom of the class hierarchy are 10 types of DIDL items. On each of these classes, relevant metadata items
are available as attributes (though they may be implemented as properties).
Each has a title, a URI, an item id and
a UPnP class. Some have other
attributes. For example, DidlMusicTrack and DidlMusicAlbum have
some extra fields such as album,
album_art_uri and creator.
One of the more important attributes which each class has is
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 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