soco.music_services.music_service module
Sonos Music Services interface.
This module provides the MusicService class and related functionality.
Known problems:
Not all music services follow the pattern layout for the authentication information completely. This means that it might be necessary to tweak the code for individual services. This is an unfortunate result of Sonos not enforcing data hygiene of its services. The implication for SoCo is that getting all services to work will require more effort and the kind of broader testing we will only get by putting the code out there. Hence, if you are an early adopter of the music service code (added in version 0.26) consider yourselves guinea pigs.
There currently is no way to reset an authentication, at least when authentication has been performed for TIDAL (which uses device link authentication), after it has been done once for a particular household ID, it fails on subsequent attempts. What this might mean is that if you lose the authentication tokens for such a service, it may not be possible to generate new ones. Obviously, some method must exist to reset this, but it is not presently implemented.
- class soco.music_services.music_service.MusicServiceSoapClient(endpoint, timeout, music_service, token_store, device=None)[source]
A SOAP client for accessing Music Services.
This class handles all the necessary authentication for accessing third party music services. You are unlikely to need to use it yourself.
- Parameters:
endpoint (str) – The SOAP endpoint. A url.
timeout (int) – Timeout the connection after this number of seconds
music_service (
MusicService
) – The MusicService object to which this client belongs.token_store (
TokenStoreBase
) – A token store instance. The token store is an instance of a subclass ofTokenStoreBase
device (SoCo) – (Optional) If provided this device will be used for the communication; if not, the device returned by
discovery.any_soco
will be used
- get_soap_header()[source]
Generate the SOAP authentication header for the related service.
This header contains all the necessary authentication details.
- Returns:
- A string representation of the XML content of the SOAP
header.
- Return type:
- call(method, args=None)[source]
Call a method on the server.
- Parameters:
- Returns:
An OrderedDict representing the response.
- Return type:
- Raises:
MusicServiceException – containing details of the error returned by the music service.
- begin_authentication()[source]
Perform the first part of a Device or App Link authentication session
See
begin_authentication
for details
- complete_authentication(link_code, link_device_id=None)[source]
Completes a previously initiated authentication session
See
complete_authentication
for details
- class soco.music_services.music_service.MusicService(service_name, token_store=None, device=None)[source]
The MusicService class provides access to third party music services.
Example
List all the services Sonos knows about:
>>> from soco.music_services import MusicService >>> print(MusicService.get_all_music_services_names()) ['Spotify', 'The Hype Machine', 'Saavn', 'Bandcamp', 'Stitcher SmartRadio', 'Concert Vault', ... ]
Interact with TuneIn:
>>> tunein = MusicService('TuneIn') >>> print (tunein) <MusicService 'TuneIn' at 0x10ad84e10>
Browse an item. By default, the root item is used. An
SearchResult
is returned (the output of print is here indented for easier reading):>>> print(tunein.get_metadata()) SearchResult( items=[ <soco.music_services.data_structures.MSContainer object at 0x7f58b038ac10>, <soco.music_services.data_structures.MSContainer object at 0x7f58b038a340>, <soco.music_services.data_structures.MSContainer object at 0x7f58b038a6d0>, <soco.music_services.data_structures.MSContainer object at 0x7f58b038a310>, <soco.music_services.data_structures.MSContainer object at 0x7f58b038a100>, <soco.music_services.data_structures.MSContainer object at 0x7f58b038a910> ], search_type='browse' )
Interact with Spotify (assuming you are subscribed):
>>> spotify = MusicService('Spotify')
Get some metadata about a specific track:
>>> response = spotify.get_media_metadata( ... item_id='spotify:track:6NmXV4o6bmp704aPGyTVVG') >>> print(dumps(response, indent=4)) { "mediaMetadata": { "id": "spotify:track:6NmXV4o6bmp704aPGyTVVG", "itemType": "track", "title": "Bøn Fra Helvete (Live)", "mimeType": "audio/x-spotify", "trackMetadata": { "artistId": "spotify:artist:1s1DnVoBDfp3jxjjew8cBR", "artist": "Kaizers Orchestra", "albumId": "spotify:album:6K8NUknbPh5TGaKeZdDwSg", "album": "Mann Mot Mann (Ep)", "duration": "317", "albumArtURI": "http://o.scdn.co/image/7b76a5074416e83fa3f3cd...9", "canPlay": "true", "canSkip": "true", "canAddToFavorites": "true" } } } or even a playlist:
>>> response = spotify.get_metadata( ... item_id='spotify:user:spotify:playlist:0FQk6BADgIIYd3yTLCThjg')
Find the available search categories, and use them:
>>> print(spotify.available_search_categories) ['albums', 'tracks', 'artists'] >>> result = spotify.search(category='artists', term='miles')
Note
Some of this code is still unstable, and in particular the data structures returned by methods such as
get_metadata
may change in future.- Parameters:
service_name (str) – The name of the music service, as returned by
get_all_music_services_names()
, eg ‘Spotify’, or ‘TuneIn’token_store (
TokenStoreBase
) – A token store instance. If none is given, it will default to an instance of theJsonFileTokenStore
using the ‘default’ token collection. The token store must be an instance of a subclass ofTokenStoreBase
.device (SoCo) – (Optional) If provided this device will be used for the communication, if not the device returned by
discovery.any_soco
will be used
- Raises:
- classmethod get_all_music_services_names()[source]
Get a list of the names of all available music services.
These services have not necessarily been subscribed to.
- Returns:
A list of strings.
- Return type:
- classmethod get_data_for_name(service_name)[source]
Get the data relating to a named music service.
- Parameters:
service_name (str) – The name of the music service for which data is required.
- Returns:
Data relating to the music service.
- Return type:
- Raises:
MusicServiceException – if the music service cannot be found.
- property available_search_categories
The list of search categories (each a string) supported.
May include
'artists'
,'albums'
,'tracks'
,'playlists'
,'genres'
,'stations'
,'tags'
, or others depending on the service. Some services, such as Spotify, support'all'
, but do not advertise it.Any of the categories in this list may be used as a value for
category
insearch()
.Example
>>> print(spotify.available_search_categories) ['albums', 'tracks', 'artists'] >>> result = spotify.search(category='artists', term='miles')
- Type:
- sonos_uri_from_id(item_id)[source]
Get a uri which can be sent for playing.
- Parameters:
item_id (str) – The unique id of a playable item for this music service, such as that returned in the metadata from
get_metadata
, egspotify:track:2qs5ZcLByNTctJKbhAZ9JE
- Returns:
A URI of the form:
soco://spotify%3Atrack %3A2qs5ZcLByNTctJKbhAZ9JE?sid=2311&sn=1
which encodes theitem_id
, and relevant data from the account for the music service. This URI can be sent to a Sonos device for playing, and the device itself will retrieve all the necessary metadata such as title, album etc.- Return type:
- property desc
The Sonos descriptor to use for this service.
The Sonos descriptor is used as the content of the <desc> tag in DIDL metadata, to indicate the relevant music service id.
- Type:
- begin_authentication()[source]
Perform the first part of a Device or App Link authentication session
This result of this is an authentication URL, which a user needs visit and complete the necessary authentication on and then proceed to
complete_authentication
Note
The
begin_authentication
andcomplete_authentication
methods must be completed on the same `MusicService` instance unless thelink_code
andlink_device_id
values are passed tocomplete_authentication
. These two values can be found as attributes on theMusicService
instance afterbegin_authentication
has been executed.- Returns:
Registration URL used for service linking.
- Return type:
- complete_authentication(link_code=None, link_device_id=None)[source]
Completes a previously initiated device or app link authentication session
This method is the second part of a two-step authentication process, see
begin_authentication
for details on the first part.
- get_metadata(item='root', index=0, count=100, recursive=False)[source]
Get metadata for a container or item.
- Parameters:
item (str or MusicServiceItem) – The container or item to browse given either as a MusicServiceItem instance or as a str. Defaults to the root item.
index (int) – The starting index. Default 0.
count (int) – The maximum number of items to return. Default 100.
recursive (bool) – Whether the browse should recurse into sub-items (Does not always work). Defaults to
False
.
- Returns:
The item or container’s metadata, or
None
.- Return type:
See also
The Sonos getMetadata API.
- search(category, term='', index=0, count=100)[source]
Search for an item in a category.
- Parameters:
category (str) – The search category to use. Standard Sonos search categories are ‘artists’, ‘albums’, ‘tracks’, ‘playlists’, ‘genres’, ‘stations’, ‘tags’. Not all are available for each music service. Call available_search_categories for a list for this service.
term (str) – The term to search for.
index (int) – The starting index. Default 0.
count (int) – The maximum number of items to return. Default 100.
- Returns:
The search results, or
None
.- Return type:
See also
The Sonos search API
- get_media_metadata(item_id)[source]
Get metadata for a media item.
- Parameters:
item_id (str) – The item for which metadata is required.
- Returns:
The item’s metadata, or
None
- Return type:
See also
The Sonos getMediaMetadata API
- get_media_uri(item_id)[source]
Get a streaming URI for an item.
Note
You should not need to use this directly. It is used by the Sonos players (not the controllers) to obtain the uri of the media stream. If you want to have a player play a media item, you should add it to the queue using its id and let the player work out where to get the stream from (see On Demand Playback and Programmed Radio)
- get_last_update()[source]
Get last_update details for this music service.
- Returns:
A dict with keys ‘catalog’, and ‘favorites’. The value of each is a string which changes each time the catalog or favorites change. You can use this to detect when any caches need to be updated.
- Return type:
- get_extended_metadata(item_id)[source]
Get extended metadata for a media item, such as related items.
- Parameters:
item_id (str) – The item for which metadata is required.
- Returns:
The item’s extended metadata or None.
- Return type:
See also
The Sonos getExtendedMetadata API
- get_extended_metadata_text(item_id, metadata_type)[source]
Get extended metadata text for a media item.
- Parameters:
- Returns:
The item’s extended metadata text or None
- Return type:
See also
The Sonos getExtendedMetadataText API