soco.music_library module¶
Access to the Music Library.
The Music Library is the collection of music stored on your local network.
For access to third party music streaming services, see the
music_service
module.
-
class
soco.music_library.
MusicLibrary
(soco=None)[source]¶ The Music Library.
Parameters: soco ( SoCo
, optional) – ASoCo
instance to query for music library information. IfNone
, or not supplied, a randomSoCo
instance will be used.-
build_album_art_full_uri
(url)[source]¶ Ensure an Album Art URI is an absolute URI.
Parameters: url (str) – the album art URI. Returns: An absolute URI. Return type: str
-
get_artists
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_formation
withsearch_type='artists'
. For details of other arguments, see that method.
-
get_album_artists
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='album_artists'
. For details of other arguments, see that method.
-
get_albums
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='albums'
. For details of other arguments, see that method.
-
get_genres
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='genres'
. For details of other arguments, see that method.
-
get_composers
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='composers'
. For details of other arguments, see that method.
-
get_tracks
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='tracks'
. For details of other arguments, see that method.
-
get_playlists
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='playlists'
. For details of other arguments, see that method.Note
The playlists that are referred to here are the playlists imported from the music library, they are not the Sonos playlists.
-
get_sonos_favorites
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='sonos_favorites'
. For details of other arguments, see that method.
-
get_favorite_radio_stations
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='radio_stations'
. For details of other arguments, see that method.
-
get_favorite_radio_shows
(*args, **kwargs)[source]¶ Convenience method for
get_music_library_information
withsearch_type='radio_stations'
. For details of other arguments, see that method.
-
get_music_library_information
(search_type, start=0, max_items=100, full_album_art_uri=False, search_term=None, subcategories=None, complete_result=False)[source]¶ Retrieve music information objects from the music library.
This method is the main method to get music information items, like e.g. tracks, albums etc., from the music library with. It can be used in a few different ways:
The
search_term
argument performs a fuzzy search on that string in the results, so e.g calling:get_music_library_information('artists', search_term='Metallica')
will perform a fuzzy search for the term ‘Metallica’ among all the artists.
Using the
subcategories
argument, will jump directly into that subcategory of the search and return results from there. So. e.g knowing that among the artist is one called ‘Metallica’, calling:get_music_library_information('artists', subcategories=['Metallica'])
will jump directly into the ‘Metallica’ sub category and return the albums associated with Metallica and:
get_music_library_information('artists', subcategories=['Metallica', 'Black'])
will return the tracks of the album ‘Black’ by the artist ‘Metallica’. The order of sub category types is: Genres->Artists->Albums->Tracks. It is also possible to combine the two, to perform a fuzzy search in a sub category.
The
start
,max_items
andcomplete_result
arguments all have to do with paging of the results. By default the searches are always paged, because there is a limit to how many items we can get at a time. This paging is exposed to the user with thestart
andmax_items
arguments. So calling:get_music_library_information('artists', start=0, max_items=100) get_music_library_information('artists', start=100, max_items=100)
will get the first and next 100 items, respectively. It is also possible to ask for all the elements at once:
get_music_library_information('artists', complete_result=True)
This will perform the paging internally and simply return all the items.
Parameters: - search_type (str) – The kind of information to retrieve. Can be one of:
'artists'
,'album_artists'
,'albums'
,'genres'
,'composers'
,'tracks'
,'share'
,'sonos_playlists'
, or'playlists'
, where playlists are the imported playlists from the music library. - start (int, optional) – starting number of returned matches (zero based). Default 0.
- max_items (int, optional) – Maximum number of returned matches. Default 100.
- full_album_art_uri (bool) – whether the album art URI should be absolute (i.e. including
the IP address). Default
False
. - search_term (str, optional) – a string that will be used to perform a fuzzy search among the search results. If used in combination with subcategories, the fuzzy search will be performed in the subcategory.
- subcategories (str, optional) – A list of strings that indicate one or more subcategories to dive into.
- complete_result (bool) – if
True
, will disable paging (ignorestart
andmax_items
) and return all results for the search.
Warning
Getting e.g. all the tracks in a large collection might take some time.
Returns: an instance of SearchResult
.Return type: SearchResult
Note
- The maximum numer of results may be restricted by the unit, presumably due to transfer size consideration, so check the returned number against that requested.
- The playlists that are returned with the
'playlists'
search, are the playlists imported from the music library, they are not the Sonos playlists.
Raises: SoCoException
upon errors.- search_type (str) – The kind of information to retrieve. Can be one of:
-
browse
(ml_item=None, start=0, max_items=100, full_album_art_uri=False, search_term=None, subcategories=None)[source]¶ Browse (get sub-elements from) a music library item.
Parameters: - ml_item (
DidlItem
) – the item to browse, if left out orNone
, items at the root level will be searched. - start (int) – the starting index of the results.
- max_items (int) – the maximum number of items to return.
- full_album_art_uri (bool) – whether the album art URI should be fully qualified with the relevant IP address.
- search_term (str) – A string that will be used to perform a fuzzy
search among the search results. If used in combination with
subcategories, the fuzzy search will be performed on the
subcategory. Note: Searching will not work if
ml_item
isNone
. - subcategories (list) – A list of strings that indicate one or more
subcategories to descend into. Note: Providing sub categories
will not work if
ml_item
isNone
.
Returns: A
SearchResult
instance.Raises: AttributeError
– ifml_item
has noitem_id
attribute.SoCoUPnPException
– witherror_code='701'
if the item cannot be browsed.
- ml_item (
-
browse_by_idstring
(search_type, idstring, start=0, max_items=100, full_album_art_uri=False)[source]¶ Browse (get sub-elements from) a given music library item, specified by a string.
Parameters: - search_type (str) – The kind of information to retrieve. Can be
one of:
'artists'
,'album_artists'
,'albums'
,'genres'
,'composers'
,'tracks'
,'share'
,'sonos_playlists'
, and'playlists'
, where playlists are the imported file based playlists from the music library. - idstring (str) – a term to search for.
- start (int) – starting number of returned matches. Default 0.
- max_items (int) – Maximum number of returned matches. Default 100.
- full_album_art_uri (bool) – whether the album art URI should be
absolute (i.e. including the IP address). Default
False
.
Returns: a
SearchResult
instance.Return type: Note
The maximum numer of results may be restricted by the unit, presumably due to transfer size consideration, so check the returned number against that requested.
- search_type (str) – The kind of information to retrieve. Can be
one of:
-
start_library_update
(album_artist_display_option='')[source]¶ Start an update of the music library.
Parameters: album_artist_display_option (str) – a value for the album artist compilation setting (see album_artist_display_option
).
-
search_track
(artist, album=None, track=None, full_album_art_uri=False)[source]¶ Search for an artist, an artist’s albums, or specific track.
Parameters: Returns: A
SearchResult
instance.
-
get_albums_for_artist
(artist, full_album_art_uri=False)[source]¶ Get an artist’s albums.
Parameters: Returns: A
SearchResult
instance.
-
get_tracks_for_album
(artist, album, full_album_art_uri=False)[source]¶ Get the tracks of an artist’s album.
Parameters: Returns: A
SearchResult
instance.
-
album_artist_display_option
¶ The current value of the album artist compilation setting.
Possible values are:
'WMP'
- use Album Artists'ITUNES'
- use iTunes® Compilations'NONE'
- do not group compilations
See also
The Sonos FAQ on compilation albums.
To change the current setting, call
start_library_update
and pass the new setting.Type: str
Return a list of the music library shares.
Returns: - The music library shares, which are strings of the form
'//hostname_or_IP/share_path'
.
Return type: list
Delete a music library share.
Parameters: share_name (str) – the name of the share to be deleted, which should be of the form '//hostname_or_IP/share_path'
.Raises: SoCoUPnPException
-