soco.music_services.music_service module

Sonos Music Services interface.

This module provides the MusicService class and related functionality.

Known problems:

  1. 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.
  2. 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.

  • 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 of TokenStoreBase
  • 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

Generate the SOAP authentication header for the related service.

This header contains all the necessary authentication details.

A string representation of the XML content of the SOAP
Return type:str
call(method, args=None)[source]

Call a method on the server.

  • method (str) – The name of the method to call.
  • args (List[Tuple[str, str]] or None) – A list of (parameter, value) pairs representing the parameters of the method. Defaults to None.

An OrderedDict representing the response.

Return type:



MusicServiceException – containing details of the error returned by the music service.


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.


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())
    <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>

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",
            "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 ='artists', term='miles')


Some of this code is still unstable, and in particular the data structures returned by methods such as get_metadata may change in future.

  • 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 the JsonFileTokenStore using the ‘default’ token collection. The token store must be an instance of a subclass of TokenStoreBase.
  • 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


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:list
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:dict
Raises:MusicServiceException – if the music service cannot be found.

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 in search().


>>> print(spotify.available_search_categories)
['albums', 'tracks', 'artists']
>>> result ='artists', term='miles')

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, eg spotify:track:2qs5ZcLByNTctJKbhAZ9JE
Returns:A URI of the form: soco://spotify%3Atrack %3A2qs5ZcLByNTctJKbhAZ9JE?sid=2311&sn=1 which encodes the item_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:str

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.


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


The begin_authentication and complete_authentication methods must be completed on the same `MusicService` instance unless the link_code and link_device_id values are passed to complete_authentication. These two values can be found as attributes on the MusicService instance after begin_authentication has been executed.

Returns:Registration URL used for service linking.
Return type:str
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.

  • link_code (str, optional) – A link code generated from begin_authentication. If not provided, cached code will be used.
  • link_device_id (str, optional) – A link device ID generated from begin_authentication. If not provided, cached device ID will be used.
get_metadata(item='root', index=0, count=100, recursive=False)[source]

Get metadata for a container or item.

  • 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.

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.

  • 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.

The search results, or None.

Return type:


See also

The Sonos search API


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:OrderedDict

See also

The Sonos getMediaMetadata API


Get a streaming URI for an item.


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)

Parameters:item_id (str) – The item for which the URI is required
Returns:The item’s streaming URI.
Return type:str

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:OrderedDict

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:OrderedDict

See also

The Sonos getExtendedMetadata API

get_extended_metadata_text(item_id, metadata_type)[source]

Get extended metadata text for a media item.

  • item_id (str) – The item for which metadata is required
  • metadata_type (str) – The type of text to return, eg
  • or 'ALBUM_NOTES'. Calling ('ARTIST_BIO',) –
  • for the item will show which extended (get_extended_metadata) –
  • are available (metadata_types) –

The item’s extended metadata text or None

Return type:


See also

The Sonos getExtendedMetadataText API