music.spotify
Platypush documentation
music.spotify
- class platypush.plugins.music.spotify.MusicSpotifyPlugin(client_id: Optional[str] = None, client_secret: Optional[str] = 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
andclient_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 thehttp
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: Optional[str] = None, client_secret: Optional[str] = None, **kwargs)[source]
- Parameters:
client_id – Spotify client ID.
client_secret – Spotify client secret.
- add(resource: str, device: Optional[str] = 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: Union[str, Iterable[str]], position: Optional[int] = 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: Optional[str] = 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": 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_playlist(playlist: str, with_tracks: bool = True, limit: Optional[int] = 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": 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" }
- get_playlists(limit: int = 1000, offset: int = 0, user: Optional[str] = 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": 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" }
- 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: Optional[Union[datetime, str, int]] = None, after: Optional[Union[datetime, str, int]] = 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 thenafter
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 thenbefore
cannot be set.
- Returns:
- next(device: Optional[str] = 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: Optional[str] = None)[source]
Toggle paused state.
- Parameters:
device – Device ID or name. If none is specified then the action will target the currently active device.
- play(resource: Optional[str] = None, device: Optional[str] = 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 toPLAY
.device – Device ID or name. If none is specified then the action will target the currently active device.
- play_if_paused(device: Optional[str] = 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: Optional[Union[str, Iterable[str]]] = 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: Optional[str] = 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: Optional[bool] = None, device: Optional[str] = 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: Union[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: Optional[bool] = None, device: Optional[str] = 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: Optional[Union[str, dict]] = 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
andepisode
(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": 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" } ]
- 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" } ]
- If
- seek(position: float, device: Optional[str] = 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: Optional[str] = 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.