music.spotify#

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.

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]#
Parameters:

  • client_id – Spotify client ID.

  • client_secret – Spotify client secret.

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": 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"
}

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_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": 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_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": 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"
  }
]
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.

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(delta: int = 5, device: str | None = None)[source]#

Set the volume down by a certain delta.

Parameters:

  • delta – Decrease 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.

volup(delta: int = 5, device: str | None = None)[source]#

Set the volume up by a certain delta.

Parameters:

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