music.spotify

Platypush documentation

music.spotify#

Description#

Plugin to interact with the user’s Spotify library and players.

Warning

I don’t have a Spotify account, so I can’t test this plugin. If you have a Spotify account and you want to contribute to testing or improving this plugin, please reach out to me.

In order to use this plugin to interact with your Spotify account you need to register a new app on the Spotify developers website, whitelist the callback URL of your Platypush host and authorize the app to your account:

  • Create a developer app on https://developer.spotify.com.

  • Get the app’s client_id and client_secret.

  • Whitelist the authorization callback URL on the Platypush machine, usually in the form http(s)://your-platypush-hostname-or-local-ip:8008/spotify/auth_callback (you need the http Platypush backend to be enabled).

  • You can then authorize the app by opening the following URL in a browser: https://accounts.spotify.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=http(s)://your-platypush-hostname-or-local-ip:8008/spotify/auth_callback&scope=<comma-separated-list-of-scopes>&state=<some-random-string>.

This is the list of scopes required for full plugin functionalities:

  • user-read-playback-state

  • user-modify-playback-state

  • user-read-currently-playing

  • user-read-recently-played

  • app-remote-control

  • streaming

  • playlist-modify-public

  • playlist-modify-private

  • playlist-read-private

  • playlist-read-collaborative

  • user-library-modify

  • user-library-read

Alternatively, you can call any of the methods from this plugin over HTTP API, and the full authorization URL should be printed on the application logs/stdout.

Configuration#

music.spotify:
  # [Optional]

  # client_id:   # type=Optional[str]

  # [Optional]

  # client_secret:   # type=Optional[str]

Actions#

Module reference#

class platypush.plugins.music.spotify.MusicSpotifyPlugin(client_id: str | None = None, client_secret: str | None = None, **kwargs)[source]#

Bases: MusicPlugin, SpotifyMixin

Plugin to interact with the user’s Spotify library and players.

Warning

I don’t have a Spotify account, so I can’t test this plugin. If you have a Spotify account and you want to contribute to testing or improving this plugin, please reach out to me.

In order to use this plugin to interact with your Spotify account you need to register a new app on the Spotify developers website, whitelist the callback URL of your Platypush host and authorize the app to your account:

  • Create a developer app on https://developer.spotify.com.

  • Get the app’s client_id and client_secret.

  • Whitelist the authorization callback URL on the Platypush machine, usually in the form http(s)://your-platypush-hostname-or-local-ip:8008/spotify/auth_callback (you need the http Platypush backend to be enabled).

  • You can then authorize the app by opening the following URL in a browser: https://accounts.spotify.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=http(s)://your-platypush-hostname-or-local-ip:8008/spotify/auth_callback&scope=<comma-separated-list-of-scopes>&state=<some-random-string>.

This is the list of scopes required for full plugin functionalities:

  • user-read-playback-state

  • user-modify-playback-state

  • user-read-currently-playing

  • user-read-recently-played

  • app-remote-control

  • streaming

  • playlist-modify-public

  • playlist-modify-private

  • playlist-read-private

  • playlist-read-collaborative

  • user-library-modify

  • user-library-read

Alternatively, you can call any of the methods from this plugin over HTTP API, and the full authorization URL should be printed on the application logs/stdout.

__init__(client_id: str | None = None, client_secret: str | None = None, **kwargs)[source]#
add(resource: str, device: str | None = None, **kwargs)[source]#

Add a Spotify resource (track, or episode) to the playing queue.

Parameters:

  • resource – Spotify resource URI.

  • device – Device ID or name. If none is specified then the action will target the currently active device.

add_to_playlist(playlist: str, resources: str | Iterable[str], position: int | None = None)[source]#

Add one or more items to a playlist.

Parameters:

  • playlist – Playlist name, ID or URI.

  • resources – URI(s) of the resource(s) to be added.

  • position – At what (1-based) position the tracks should be inserted (default: append to the end).

create_playlist(name: str, description: str | None = None, public: bool = False)[source]#

Create a playlist.

Parameters:

  • name – Playlist name.

  • description – Optional playlist description.

  • public – Whether the new playlist should be public (default: False).

Returns:

{
  "collaborative": false,
  "description": "string",
  "id": "string",
  "name": "string",
  "owner": "Playlist owner data",
  "public": false,
  "snapshot_id": "Playlist snapshot ID - it changes when the playlist is modified",
  "tracks": "List of tracks in the playlist",
  "uri": "Playlist unique Spotify URI",
  "url": "Spotify URL"
}

current_track(**kwargs) → dict[source]#

Get the track currently playing.

Returns:

{
  "album": "Track album",
  "artist": "Track artist",
  "date": "Track year release date",
  "duration": "Track duration in seconds",
  "file": "Cross-compatibility file ID (same as uri)",
  "id": "Spotify ID",
  "image_url": "Album image URL",
  "popularity": "Popularity between 0 and 100",
  "title": "Track title",
  "track": "Album track number",
  "type": "track",
  "uri": "Spotify URI",
  "url": "Spotify URL"
}

follow_playlist(playlist: str, public: bool = True)[source]#

Follow a playlist.

Parameters:

  • playlist – Playlist name, ID or URI.

  • public – If True (default) then the playlist will appear in the user’s list of public playlists, otherwise it won’t.

get_albums(limit: int = 50, offset: int = 0) → List[dict][source]#

Get the list of albums saved by the user.

Parameters:

  • limit – Maximum number of results (default: 50).

  • offset – Return results starting from this index (default: 0).

Returns:

[
  {
    "artist": "Artist",
    "date": "Release date",
    "id": "Spotify ID",
    "image_url": "Image URL",
    "name": "Name/title",
    "popularity": "Popularity between 0 and 100",
    "tracks": "List of tracks on the album",
    "type": "album",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]

get_devices() → List[dict][source]#

Get the list of players associated to the Spotify account.

Returns:

[
  {
    "id": "Device unique ID",
    "is_active": "True if the device is currently active",
    "is_private_session": "True if the device is currently playing a private session",
    "is_restricted": "True if the device has restricted access",
    "name": "Device name",
    "type": "Supported types: [Unknown, Computer, Tablet, Smartphone, Speaker, TV, AVR, STB, Audio dongle]",
    "volume": "Player volume in percentage [0-100]"
  }
]

get_episodes(limit: int = 50, offset: int = 0) → List[dict][source]#

Get the list of episodes saved by the user.

Parameters:

  • limit – Maximum number of results (default: 50).

  • offset – Return results starting from this index (default: 0).

Returns:

[
  {
    "album": "Track album",
    "artist": "Track artist",
    "date": "Track year release date",
    "description": "Episode description",
    "duration": "Track duration in seconds",
    "file": "Cross-compatibility file ID (same as uri)",
    "id": "Spotify ID",
    "image_url": "Album image URL",
    "popularity": "Popularity between 0 and 100",
    "show": "Episode show name",
    "title": "Track title",
    "track": "Album track number",
    "type": "episode",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]

get_images(resources: Iterable[str], **__) → Dict[str, str | None]#

Get the images for a list of URIs.

Note

This is an optional action, and it may not be implemented by all plugins. If the plugin doesn’t implement this action, it will return an empty dictionary.

Parameters:

uris – List of URIs.

Returns:

Dictionary in the form {uri: image_url}.

get_playlist(playlist: str, with_tracks: bool = True, limit: int | None = None, offset: int = 0)[source]#

Get a playlist content.

Parameters:

  • playlist – Playlist name, ID or URI.

  • with_tracks – Return also the playlist tracks (default: false, return only the metadata).

  • limit – If with_tracks is True, retrieve this maximum amount of tracks (default: None, get all tracks).

  • offset – If with_tracks is True, retrieve tracks starting from this index (default: 0).

Returns:

{
  "collaborative": false,
  "description": "string",
  "id": "string",
  "name": "string",
  "owner": "Playlist owner data",
  "public": true,
  "snapshot_id": "Playlist snapshot ID - it changes when the playlist is modified",
  "tracks": "List of tracks in the playlist",
  "uri": "Playlist unique Spotify URI",
  "url": "Spotify URL"
}

get_playlists(limit: int = 1000, offset: int = 0, user: str | None = None)[source]#

Get the user’s playlists.

Parameters:

  • limit – Maximum number of results (default: 1000).

  • offset – Return results starting from this index (default: 0).

  • user – Return the playlist owned by a specific user ID (default: currently logged in user).

Returns:

{
  "collaborative": true,
  "description": "string",
  "id": "string",
  "name": "string",
  "owner": "Playlist owner data",
  "public": true,
  "snapshot_id": "Playlist snapshot ID - it changes when the playlist is modified",
  "tracks": "List of tracks in the playlist",
  "uri": "Playlist unique Spotify URI",
  "url": "Spotify URL"
}

get_shows(limit: int = 50, offset: int = 0) → List[dict][source]#

Get the list of shows saved by the user.

Parameters:

  • limit – Maximum number of results (default: 50).

  • offset – Return results starting from this index (default: 0).

Returns:

[
  {
    "artist": "Artist",
    "date": "Release date",
    "description": "Show description",
    "id": "Spotify ID",
    "image_url": "Image URL",
    "name": "Name/title",
    "popularity": "Popularity between 0 and 100",
    "publisher": "Show publisher name",
    "tracks": "List of tracks on the album",
    "type": "show",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]

get_tracks(limit: int = 100, offset: int = 0) → List[dict][source]#

Get the list of tracks saved by the user.

Parameters:

  • limit – Maximum number of results (default: 100).

  • offset – Return results starting from this index (default: 0).

Returns:

[
  {
    "album": "Track album",
    "artist": "Track artist",
    "date": "Track year release date",
    "duration": "Track duration in seconds",
    "file": "Cross-compatibility file ID (same as uri)",
    "id": "Spotify ID",
    "image_url": "Album image URL",
    "popularity": "Popularity between 0 and 100",
    "title": "Track title",
    "track": "Album track number",
    "type": "track",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]

history(limit: int = 20, before: datetime | str | int | None = None, after: datetime | str | int | None = None)[source]#

Get a list of recently played track on the account.

Parameters:

  • limit – Maximum number of tracks to be retrieved (default: 20, max: 50).

  • before – Retrieve only the tracks played before this timestamp, specified as a UNIX timestamp, a datetime object or an ISO datetime string. If before is set then after cannot be set.

  • after – Retrieve only the tracks played after this timestamp, specified as a UNIX timestamp, a datetime object or an ISO datetime string. If after is set then before cannot be set.

Returns:

next(device: str | None = None, **kwargs)[source]#

Skip to the next track.

Parameters:

device – Device ID or name. If none is specified then the action will target the currently active device.

pause(device: str | None = None)[source]#

Toggle paused state.

Parameters:

device – Device ID or name. If none is specified then the action will target the currently active device.

pause_if_playing()[source]#

Pause playback only if it’s playing

play(resource: str | None = None, device: str | None = None)[source]#

Change the playback state of a device to PLAY or start playing a specific resource.

Parameters:

  • resource – Resource to play, in Spotify URI format (e.g. spotify:track:xxxxxxxxxxxxxxxxxxxxxx). If none is specified then the method will change the playback state to PLAY.

  • device – Device ID or name. If none is specified then the action will target the currently active device.

play_if_paused(device: str | None = None)[source]#

Play only if it’s paused (resume)

Parameters:

device – Device ID or name. If none is specified then the action will target the currently active device.

play_if_paused_or_stopped()[source]#

Alias for play_if_paused().

playlist_move(playlist: str, from_pos: int, to_pos: int, range_length: int = 1, resources: str | Iterable[str] | None = None, **_)[source]#

Move or replace elements in a playlist.

Parameters:

  • playlist – Playlist name, ID or URI.

  • from_pos – Move tracks starting from this position (the first element has index 1).

  • to_pos – Move tracks to this position (1-based index).

  • range_length – Number of tracks to move (default: 1).

  • resources – If specified, then replace the items from from_pos to from_pos+range_length with the specified set of Spotify URIs (it must be a collection with the same length as the range).

previous(device: str | None = None, **kwargs)[source]#

Skip to the next track.

Parameters:

device – Device ID or name. If none is specified then the action will target the currently active device.

random(value: bool | None = None, device: str | None = None)[source]#

Set or toggle random/shuffle mode.

Parameters:

  • value – If set, set the shuffle state this value (true/false). Default: None (toggle current state).

  • device – Device ID or name. If none is specified then the action will target the currently active device.

remove_albums(resources: Iterable[str])[source]#

Remove a list of albums from the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the albums to remove.

remove_episodes(resources: Iterable[str])[source]#

Remove a list of episodes from the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the episodes to remove.

remove_from_playlist(playlist: str, resources: str | Iterable[str])[source]#

Remove one or more items from a playlist.

Parameters:

  • playlist – Playlist name, ID or URI.

  • resources – URI(s) of the resource(s) to be removed. A maximum of 100 tracks can be provided at once.

remove_shows(resources: Iterable[str])[source]#

Remove a list of shows from the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the shows to remove.

remove_tracks(resources: Iterable[str])[source]#

Remove a list of tracks from the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the tracks to remove.

repeat(value: bool | None = None, device: str | None = None)[source]#

Set or toggle repeat mode.

Parameters:

  • value – If set, set the repeat state this value (true/false). Default: None (toggle current state).

  • device – Device ID or name. If none is specified then the action will target the currently active device.

save_albums(resources: Iterable[str])[source]#

Save a list of albums to the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the albums to save.

save_episodes(resources: Iterable[str])[source]#

Save a list of episodes to the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the episodes to save.

save_shows(resources: Iterable[str])[source]#

Save a list of shows to the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the shows to save.

save_tracks(resources: Iterable[str])[source]#

Save a list of tracks to the user’s collection.

Parameters:

resources – Spotify IDs or URIs of the tracks to save.

search(query: str | dict | None = None, limit: int = 50, offset: int = 0, type: str = 'track', **filter) → Iterable[dict][source]#

Search for tracks matching a certain criteria.

Parameters:

  • query –

    Search filter. It can either be a free-text or a structured query. In the latter case the following fields are supported:

    • any: Search for anything that matches this text.

    • uri: Search the following Spotify ID/URI or list of IDs/URIs.

    • artist: Filter by artist.

    • track: Filter by track name.

    • album: Filter by album name.

    • year: Filter by year (dash-separated ranges are supported).

  • limit – Maximum number of results (default: 50).

  • offset – Return results starting from this index (default: 0).

  • type – Type of results to be returned. Supported: album, artist, playlist, track, show and episode (default: track).

  • filter – Alternative key-value way of representing a structured query.

Returns:

If type=track:
[
  {
    "album": "Track album",
    "artist": "Track artist",
    "date": "Track year release date",
    "duration": "Track duration in seconds",
    "file": "Cross-compatibility file ID (same as uri)",
    "id": "Spotify ID",
    "image_url": "Album image URL",
    "popularity": "Popularity between 0 and 100",
    "title": "Track title",
    "track": "Album track number",
    "type": "track",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]
If type=album:
[
  {
    "artist": "Artist",
    "date": "Release date",
    "id": "Spotify ID",
    "image_url": "Image URL",
    "name": "Name/title",
    "popularity": "Popularity between 0 and 100",
    "tracks": "List of tracks on the album",
    "type": "album",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]
If type=artist:
[
  {
    "genres": "Artist genres",
    "id": "Spotify ID",
    "image_url": "Image URL",
    "name": "Artist name",
    "popularity": "Popularity between 0 and 100",
    "type": "artist",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]
If type=playlist:
[
  {
    "collaborative": false,
    "description": "string",
    "id": "string",
    "name": "string",
    "owner": "Playlist owner data",
    "public": true,
    "snapshot_id": "Playlist snapshot ID - it changes when the playlist is modified",
    "tracks": "List of tracks in the playlist",
    "uri": "Playlist unique Spotify URI",
    "url": "Spotify URL"
  }
]
If type=episode:
[
  {
    "album": "Track album",
    "artist": "Track artist",
    "date": "Track year release date",
    "description": "Episode description",
    "duration": "Track duration in seconds",
    "file": "Cross-compatibility file ID (same as uri)",
    "id": "Spotify ID",
    "image_url": "Album image URL",
    "popularity": "Popularity between 0 and 100",
    "show": "Episode show name",
    "title": "Track title",
    "track": "Album track number",
    "type": "episode",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]
If type=show:
[
  {
    "artist": "Artist",
    "date": "Release date",
    "description": "Show description",
    "id": "Spotify ID",
    "image_url": "Image URL",
    "name": "Name/title",
    "popularity": "Popularity between 0 and 100",
    "publisher": "Show publisher name",
    "tracks": "List of tracks on the album",
    "type": "show",
    "uri": "Spotify URI",
    "url": "Spotify URL"
  }
]

seek(position: float, device: str | None = None, **kwargs)[source]#

Set the cursor to the specified position in the track.

Parameters:

  • position – Position in seconds.

  • device – Device ID or name. If none is specified then the action will target the currently active device.

set_volume(volume: int, device: str | None = None)[source]#

Set the playback volume on a device.

Parameters:

  • volume – Target volume as a percentage between 0 and 100.

  • device – Device ID or name. If none is specified then the currently active device will be used.

spotify_api_authenticate()#

Authenticate to the Spotify API for requests that don’t require access to user data.

spotify_api_call(url: str, method='get', scopes: Iterable[str] | None = None, **kwargs) → dict#

Send an API request to a Spotify endpoint.

Parameters:

  • url – URL to be requested.

  • method – HTTP method (default: get).

  • scopes – List of scopes required by the call.

  • kwargs – Extra keyword arguments to be passed to the request.

Returns:

The response payload.

spotify_get_track(track_id: str)#

Get information about a Spotify track ID.

spotify_user_authenticate(scopes: Iterable[str] | None = None)#

Authenticate to the Spotify API for requests that require access to user data.

spotify_user_call(url: str, method='get', scopes: Iterable[str] | None = None, **kwargs) → dict#

Shortcut for spotify_api_call that requires all the application scopes if none are passed.

start_or_transfer_playback(device: str)[source]#

Start or transfer playback to the device specified.

Parameters:

device – Device ID or name.

status(**kwargs) → dict[source]#

Get the status of the currently active player.

Returns:

{
  "device_id": "Playing device unique ID",
  "device_name": "Playing device name",
  "elapsed": "Time elapsed into the current track",
  "random": "True if the device is in shuffle mode",
  "repeat": "True if the device is in repeat mode",
  "state": "Supported types: [stop, play, pause, idle]",
  "time": "Duration of the current track",
  "track": "Information about the current track",
  "volume": "Player volume in percentage [0-100]"
}

stop(**kwargs)[source]#

This method is actually just an alias to stop(), since Spotify manages clearing playback sessions automatically after a while for paused devices.

unfollow_playlist(playlist: str)[source]#

Unfollow a playlist.

Parameters:

playlist – Playlist name, ID or URI.

voldown(step: float | None = None, device: str | None = None, **kwargs)[source]#

Set the volume down by a certain step.

Parameters:

  • step – Decrease the volume by this percentage amount (between 0 and 100). Default: 5%.

  • device – Device ID or name. If none is specified then the currently active device will be used.

volup(step: float | None = None, device: str | None = None, **kwargs)[source]#

Set the volume up by a certain step.

Parameters:

  • step – Increase the volume by this percentage amount (between 0 and 100).

  • device – Device ID or name. If none is specified then the currently active device will be used.

Platypush documentation