API Reference¶
Client¶
The Spotify API wrapper client itself.
You can start a client in a context using the async with
statement, see below. Do note the client calls
Client.authenticate()
itself, so you don’t have to do this.
async with asyncspotify.Client(auth) as sp:
# your code here
Otherwise, you would start a client like this:
sp = asyncspotify.Client(auth)
await sp.authenticate()
# your code here..
# close the client session before you exit
await sp.close()
-
class
asyncspotify.
Client
(auth)[source]¶ Client interface for the API.
This is the class you should be interfacing with when fetching Spotify objects.
- auth:
Authenticator
- Authenticator instance used for authenticating with the API.
-
__init__
(auth)[source]¶ Creates a Spotify Client instance.
Parameters: auth – Instance of Authenticator
Tell the authenticator to authorize this client.
-
create_playlist
(user, name, public=False, collaborative=False, description=None) → asyncspotify.playlist.FullPlaylist[source]¶ Create a new playlist.
Parameters: - user –
User
instance or Spotify ID. - name (str) – Name of the new playlist.
- description (str) – Description of the new playlist.
- public (bool) – Whether the playlist should be public.
- collaborative (bool) – Whether the playlist should be collaborative (anyone can edit it).
Returns: A
FullPlaylist
instance.- user –
-
edit_playlist
(playlist, name=None, description=None, public=None, collaborative=None)[source]¶ Edit a playlist.
Parameters: - playlist –
Playlist
instance or Spotify ID. - name (str) – New name of the playlist.
- description (str) – New description of the playlist.
- public (bool) – New public state of the playlist.
- collaborative (bool) – New collaborative state of the playlist.
- playlist –
-
following
(type, *ids, limit=None, after=None)[source]¶ Follow artists or users.
Parameters: - type (str) – The ID type: either artist or user.
- ids (str) – Spotify ID of the artist or the user.
- limit – Maximum number of items to return.
- after – The last artist ID retrieved from the previous request.
-
get_album
(album_id, market=None) → asyncspotify.album.FullAlbum[source]¶ Get an album.
Parameters: - album_id (str) – Spotify ID of album.
- market – ISO-3166-1 country code.
Returns: FullAlbum
instance.
-
get_album_tracks
(album, limit=20, offset=None, market=None) → List[asyncspotify.track.SimpleTrack][source]¶ Get tracks from an album.
Parameters: - album –
Album
or Spotify ID of album. - limit – How many tracks to fetch.
- offset – What pagination offset to start from.
- market – ISO-3166-1 country code.
Returns: List[
SimpleTrack
]- album –
-
get_albums
(*album_ids, market=None) → List[asyncspotify.album.FullAlbum][source]¶ Get several albums.
Parameters: - album_ids (str) – Spotify ID of album.
- market – ISO-3166-1 country code.
Returns: List[
FullAlbum
]
-
get_artist
(artist_id) → asyncspotify.artist.FullArtist[source]¶ Get an artist.
Parameters: artist_id (str) – Spotify ID of artist. Returns: FullArtist
instance.
-
get_artist_albums
(artist_id, limit=20, include_groups=None, country=None, offset=None) → List[asyncspotify.album.SimpleAlbum][source]¶ Get an artist’s albums.
Note
This endpoint does not return the track objects for each album. If you need those, you have to fetch them manually afterwards.
Parameters: - artist_id (str) – Spotify ID of artist.
- limit (int) – How many albums to return.
- kwargs – other query params for this method
Returns: List[
SimpleAlbum
]
Get an artists related artists.
Parameters: artist – Artist
or Spotify ID.Returns: A list of maximum 20 FullArtist
instances.
-
get_artist_top_tracks
(artist, market=None) → List[asyncspotify.track.FullTrack][source]¶ Returns the top tracks for an artist.
Parameters: - artist –
Artist
instance or Spotify ID. - market – ISO-3166-1 country code. Leave blank to let the library auto-resolve this.
Returns: A list of maximum 10
FullTrack
instances.- artist –
-
get_artists
(*artist_ids) → List[asyncspotify.artist.FullArtist][source]¶ Get several artists.
Parameters: artist_ids – List of artist Spotify IDs. Returns: List[ FullArtist
]
-
get_audio_analysis
(track) → asyncspotify.audioanalysis.AudioAnalysis[source]¶ Get Audio Analysis of a track.
Parameters: track – Track
instance or Spotify ID.Returns: AudioAnalysis
-
get_audio_features
(track) → asyncspotify.audiofeatures.AudioFeatures[source]¶ Get Audio Features of a track.
Parameters: track – Track
instance or Spotify ID.Returns: AudioFeatures
-
get_audio_features_multiple_tracks
(*tracks) → List[asyncspotify.audiofeatures.AudioFeatures][source]¶ Get Audio Features for multiple tracks.
Parameters: tracks (str) – Track
or a comma seperated list of Spotify IDsReturns: list[ AudioFeatures
]
-
get_devices
() → List[asyncspotify.device.Device][source]¶ Get a list of user devices.
Returns: A list of maximum 20 devices.
-
get_followed_artists
(limit=20, after=None) → List[asyncspotify.artist.SimpleArtist][source]¶ Get user’s followed artists
Parameters: - limit (int) – The maximum number of items to return. Default - infinity
- after – What artist ID to start the fetching from.
Returns: List[
SimpleArtist
]
-
get_me
() → asyncspotify.user.PrivateUser[source]¶ Gets the current user.
Returns: A PrivateUser
instance of the current user.
-
get_me_top_artists
(limit=20, offset=0, time_range='medium_term') → List[asyncspotify.artist.SimpleArtist][source]¶ Get the top artists of the current user.
Parameters: - limit (int) – How many artists to return. Maximum is 50.
- offset (int) – The index of the first result to return.
- time_range (str) – The time period for which data are selected to form a top.
- Valid values for
time_range
long_term
(calculated from several years of data and including all new data as it becomes available),medium_term
(approximately last 6 months),short_term
(approximately last 4 weeks).
Returns: List[ SimpleArtist
]
-
get_me_top_tracks
(limit=20, offset=None, time_range=None) → List[asyncspotify.track.SimpleTrack][source]¶ Gets the top tracks of the current user.
Requires scope
user-top-read
.Parameters: - limit (int) – How many tracks to return. Maximum is 50.
- offset (int) – The index of the first result to return.
- time_range (str) – The time period for which data are selected to form a top.
- Valid values for
time_range
long_term
(calculated from several years of data and including all new data as it becomes available),medium_term
(approximately last 6 months),short_term
(approximately last 4 weeks).
Returns: List[ SimpleTrack
]
-
get_player
(**kwargs) → asyncspotify.playing.CurrentlyPlayingContext[source]¶ Get a context for what user is currently playing.
Parameters: kwargs – query params for this request Returns: PlayingContext
-
get_playlist
(playlist_id) → asyncspotify.playlist.FullPlaylist[source]¶ Get a pre-existing playlist.
Parameters: playlist_id (str) – Spotify ID of the playlist. Returns: FullPlaylist
instance.
-
get_playlist_tracks
(playlist) → List[asyncspotify.track.PlaylistTrack][source]¶ Get tracks from a playlist.
Parameters: playlist – Playlist
instance or Spotify ID.Returns: List[ PlaylistTrack
]
-
get_track
(track_id) → asyncspotify.track.FullTrack[source]¶ Get a track.
Parameters: track_id (str) – Spotify ID of track. Returns: FullTrack
instance.
-
get_tracks
(*track_ids) → List[asyncspotify.track.FullTrack][source]¶ Get several tracks.
Parameters: track_ids (str) – List of track Spotify IDs. Returns: List[ FullTrack
]
-
get_user
(user_id) → asyncspotify.user.PublicUser[source]¶ Get a user.
Parameters: user_id (str) – Spotify ID of user. Returns: A PublicUser
instance.
-
get_user_playlists
(user) → List[asyncspotify.playlist.SimplePlaylist][source]¶ Get a list of attainable playlists a user owns.
Parameters: user – User
instance or Spotify ID.Returns: List[ SimplePlaylist
]
-
player_next
(device=None)[source]¶ Skip to the next track in a player.
Parameters: device – Device
or Spotify ID.
-
player_pause
(device=None)[source]¶ Stop playback on a device.
Parameters: device – Device
or Spotify ID.
-
player_play
(device=None, **kwargs)[source]¶ Start playback on device.
Parameters: - device –
Device
or Spotify ID. - kwargs – body params of the request.
Example:
player_play( context_uri='spotify:album:6xKK037rfCf2f6gf30SpvL', offset=dict(uri='spotify:track:2beor6qrB0XJxW1CM6X9x2'), position_ms=98500 )
- device –
-
player_prev
(device=None)[source]¶ Play the previous track.
Parameters: device – Device
or Spotify ID.
-
player_repeat
(state, device=None)[source]¶ Set player repeat mode.
Parameters: - state (str) – Can be ‘track’, ‘context’ or ‘off’.
- device –
Device
or Spotify ID.
-
player_seek
(time, device=None)[source]¶ Seek to a point in the currently playing track.
Parameters: - time – timedelta object or milliseconds (integer)
- device –
Device
or Spotify ID.
-
player_shuffle
(state, device=None)[source]¶ Set player shuffle mode.
Parameters: - state (bool) – Shuffle mode state.
- device –
Device
or Spotify ID.
-
player_volume
(volume, device=None)[source]¶ Set player volume.
Parameters: - volume (int) – Value from 0 to 100.
- device –
Device
or Spotify ID.
-
playlist_add_tracks
(playlist, *tracks, position=None)[source]¶ Add several tracks to a playlist.
Parameters: - playlist –
Playlist
instance or Spotify ID. - tracks – List of Spotify IDs or
Track
instance (or a mix). - position (int) – Position in the playlist to insert tracks.
- playlist –
-
search
(*types, q, limit=20, market=None, offset=None, include_external=None) → dict[source]¶ Searches for tracks, artists, albums and/or playlists.
Parameters: - types – One or more of the strings
track
,album
,artist
,playlist
or the class equivalents. - q (str) – The search query. See Spotifys’ query construction guide here.
- limit (int) – How many results of each type to return.
- market – ISO-3166-1 country code or the string
from_token
. - offset – Where to start the pagination.
- include_external – If this is equal to
audio
, the specified the response will include any relevant audio content that is hosted externally.
Returns: A dict with a key for each type, whose values are a list of instances.
- types – One or more of the strings
-
search_album
(q=None) → asyncspotify.album.SimpleAlbum[source]¶ Returns the top album for the query.
Returns: SimpleAlbum
-
search_albums
(q, limit=20, market=None, offset=None, include_external=None) → List[asyncspotify.album.SimpleAlbum][source]¶ Alias for
Client.search('album', ...)
Returns: List[ SimpleAlbum
]
-
search_artist
(q=None) → asyncspotify.artist.FullArtist[source]¶ Returns the top artist for the query.
Returns: SimpleArtist
or None
-
search_artists
(q, limit=20, market=None, offset=None, include_external=None) → List[asyncspotify.artist.FullArtist][source]¶ Alias for
Client.search('artist, ...)
Returns: List[ FullArtist
]
-
search_playlist
(q=None) → asyncspotify.playlist.SimplePlaylist[source]¶ Returns the top playlist for the query.
Returns: SimplePlaylist
-
search_playlists
(q, limit=20, market=None, offset=None, include_external=None) → List[asyncspotify.playlist.SimplePlaylist][source]¶ Alias for
Client.search('playlist', ...)
Returns: List[ SimplePlaylist
]
-
search_track
(q=None) → asyncspotify.track.SimpleTrack[source]¶ Returns the top track for the query.
Returns: SimpleTrack
or None
-
search_tracks
(q, limit=20, market=None, offset=None, include_external=None) → List[asyncspotify.track.SimpleTrack][source]¶ Alias for
Client.search('track', ...)
Returns: List[ SimpleTrack
]
- auth:
Spotify Objects¶
Note
None of these objects should be instantiated manually. They are returned by convenience methods in Client
.
-
class
asyncspotify.
SpotifyObject
(client, data)[source]¶ Represents a generic Spotify Object.
- id: str
- Spotify ID of the object.
- name: str
- Name of the object.
- uri: str
- Spotify URI of the object.
Track¶
-
class
asyncspotify.
SimpleTrack
(client, data)[source]¶ Represents a Track object.
- id: str
- Spotify ID of the track.
- name: str
- Name of the track.
- artists: List[
Artist
] - List of artists that appear on the track.
- images: List[
Image
] - List of associated images, such as album cover in different sizes.
- uri: str
- Spotify URI of the album.
- link: str
- Spotify URL of the album.
- type: str
- Plaintext string of object type:
track
. - available_markets: List[str] or None
- Markets where the album is available in ISO-3166-1 form.
- disc_number: int
- What disc the track appears on. Usually
1
unless there are several discs in the album. - duration: timedelta
- timedelta instance representing the length of the track.
- explicit: bool
- Whether the track is explicit or not.
- external_urls: dict
- Dictionary that maps type to url.
- is_playable: bool
- tbc
- linked_from:
LinkedTrack
- tbc
- restrictions: restrictions object
- tbc
- preview_url: str
- An URL to a 30 second preview (MP3) of the track.
- track_number: int
- The number of the track on the album.
- is_local: bool
- Whether the track is from a local file.
-
audio_analysis
() → asyncspotify.audioanalysis.AudioAnalysis¶ Get ‘Audio Analysis’ of the track.
Parameters: track – Track
instance or Spotify ID of track.Returns: AudioAnalysis
-
audio_features
() → asyncspotify.audiofeatures.AudioFeatures¶ Get ‘Audio Features’ of the track.
Parameters: track – Track
instance or Spotify ID of track.Returns: AudioFeatures
-
avaliable_in
(market)¶ Check if track is available in a market.
Parameters: market – ISO-3166-1 value. Returns:
-
class
asyncspotify.
FullTrack
(client, data)[source]¶ Represents a complete Track object.
This type has some additional attributes not existent in
SimpleTrack
.- album:
SimpleAlbum
- An instance of the album the track appears on.
- popularity: int
- An indicator of the popularity of the track, 0 being least popular and 100 being the most.
- external_ids: dict
- Dictionary of external IDs.
- album:
-
class
asyncspotify.
PlaylistTrack
(client, data)[source]¶ Represents a Track object originating from a playlist.
This type has some additional attributes not existent in
SimpleTrack
orFullTrack
.- added_at: datetime
- Indicates when the track was added to the playlist.
- added_by: User object
- Indicates who added the track to the playlist. The information provided from the API is not enough to instantiate a PublicUser object, so it’s a plain copy of the returned json object.
Artist¶
-
class
asyncspotify.
SimpleArtist
(client, data)[source]¶ Represents an Artist object.
- id: str
- Spotify ID of the artist.
- name: str
- Name of the artist.
- uri: str
- Spotify URI of the artist.
- link: str
- Spotify URL of the artist.
- external_urls: dict
- Dictionary that maps type to url.
-
albums
(limit=20, include_groups=None, country=None, offset=None)¶ Get artists albums
Returns: List[ SimpleAlbum
]
Get related artists. Maximum of 20 artists.
Returns: List[ FullArtist
]
-
class
asyncspotify.
FullArtist
(client, data)[source]¶ Represents a complete Artist object.
This type has some additional attributes not existent in
SimpleArtist
.- follow_count: int
- Follow count of the artist.
- genres: List[str]
- Genres associated with the artist.
- popularity: int
- An indicator of the popularity of the track, 0 being least popular and 100 being the most.
- images: List[
Image
] - List of associated images.
Playlist¶
-
class
asyncspotify.
SimplePlaylist
(client, data)[source]¶ Represents a playlist object.
Note
To iterate all tracks, you have to use the
async for
construct or fill the object with.fill()
before iterating.tracks
.- id: str
- Spotify ID of the playlist.
- name: str
- Name of the playlist.
- tracks: List[
SimpleTrack
] - All tracks in the playlist.
- track_count: int
- The expected track count as advertised by the last paging object.
is_filled()
can return True even if fewer tracks than this exists intracks
, since some fetched tracks from the API can be None for various reasons. - uri: str
- Spotify URI of the playlist.
- link: str
- Spotify URL of the playlist.
- snapshot_id: str
- Spotify ID of the current playlist snapshot. Read about snapshots here.
- collaborative: bool
- Whether the playlist is collaborative.
- public: bool
- Whether the playlist is public.
- owner:
PublicUser
- Owner of the playlist.
- external_urls: dict
- Dictionary that maps type to url.
- images: List[
Image
] - List of associated images.
-
async for track in playlist
Create a pager and iterate all tracks in this object. Also updates the
tracks
cache (same as callingfill()
).
-
add_track
(track, position=None)¶ Add a track to the playlist.
Parameters: - track – Spotify ID or
Track
instance. - position (int) – Position in the playlist to insert tracks.
- track – Spotify ID or
-
add_tracks
(*tracks, position=None)¶ Add several tracks to the playlist.
Parameters: - tracks – Several Spotify IDs or
Track
instances (or a mix). - position (int) – Position in the playlist to insert tracks.
- tracks – Several Spotify IDs or
-
edit
(name=None, public=None, collaborative=None, description=None)¶ Edit the playlist.
Parameters: - name (str) – New name of the playlist.
- description (str) – New description of the playlist.
- public (bool) – New public state of the playlist.
- collaborative (bool) – New collaborative state of the playlist.
-
fill
()¶ Update this objects
tracks
cache.
-
has_track
(track)¶ Check if this object has a track.
-
is_filled
()¶ Whether this object contains as many tracks as advertised by the previous pager.
-
class
asyncspotify.
FullPlaylist
(client, data)[source]¶ Represents a complete playlist object.
This type has some additional attributes not existent in
SimplePlaylist
.- description: str
- Description of the playlist, as set by the owner.
- primary_color: str
- Primary color of the playlist, for aesthetic purposes.
- follower_count: int
- Follower count of the playlist.
Album¶
-
class
asyncspotify.
SimpleAlbum
(client, data)[source]¶ Represents an Album object.
Note
To iterate all tracks, you have to use the
async for
construct or fill the object with.fill()
before iterating.tracks
.- id: str
- Spotify ID of the album.
- name: str
- Name of the album.
- tracks: List[
Track
] - List of tracks on the album.
- artists: List[
Artist
] - List of artists that appear on the album.
- images: List[
Image
] - List of associated images, such as album cover in different sizes.
- track_count: int
- The expected track count as advertised by the last paging object.
is_filled()
can return True even if fewer tracks than this exists intracks
, since some fetched tracks from the API can be None for various reasons. - uri: str
- Spotify URI of the album.
- link: str
- Spotify URL of the album.
- type: str
- Plaintext string of object type:
album
. - album_type:
- Type of album, e.g.
album
,single
orcompilation
. - available_markets: List[str] or None
- Markets where the album is available: ISO-3166-1.
- external_urls: dict
- Dictionary that maps type to url.
- release_date: datetime
- Date (and maybe time) of album release.
- release_date_precision: str
- Precision of
release_date
. Can beyear
,month
, orday
. - album_group: str or None
- Type of album, e.g.
album
,single
,compilation
orappears_on
.
-
async for track in album
Create a pager and iterate all tracks in this object. Also updates the
tracks
cache (same as callingfill()
).
-
fill
()¶ Update this objects
tracks
cache.
-
has_track
(track)¶ Check if this object has a track.
-
is_filled
()¶ Whether this object contains as many tracks as advertised by the previous pager.
-
class
asyncspotify.
FullAlbum
(client, data)[source]¶ Represents a complete Album object.
This type has some additional attributes not existent in
SimpleAlbum
.- genres: List[str]
- List of genres associated with the album.
- label: str
- The label for the album.
- popularity: int
- An indicator of the popularity of the album, 0 being least popular and 100 being the most.
- copyrights: dict
- List of copyright objects.
- external_ids: dict
- Dictionary of external IDs.
Audio Features¶
-
class
asyncspotify.
AudioFeatures
(client, data)[source]¶ Represents an Audio Features object.
- id: str
- The Spotify ID of the track.
- uri: str
- Spotify URI of the album.
- analysis_url: str
- An HTTP URL to access the full audio analysis of this track.
- track_href: str
- A link to the Web API endpoint providing full details of the track.
- duration: timedelta
- The duration of the track.
- key: int
- The estimated overall key of the track.
- mode: int
- Mode indicates the modality (major or minor) of a track, the type of scale from which its melodic content is derived.
- time_signature: int
- An estimated overall time signature of a track.
- acousticness: float
- A confidence measure from 0.0 to 1.0 of whether the track is acoustic.
- danceability: float
- A measure of how suitable the track is for dancing.
- energy: float
- Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity.
- instrumentalness: float
- Predicts whether a track contains no vocals.
- liveness: float
- Detects the presence of an audience in the recording.
- loudness: float
- The overall loudness of a track in decibels (dB).
- speechiness: float
- Speechiness detects the presence of spoken words in a track.
- valence: float
- A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track.
- tempo: float
- The overall estimated tempo of a track in beats per minute (BPM).
Audio Analysis¶
-
class
asyncspotify.
AudioAnalysis
(client, data)[source]¶ Represents an Audio Analysis object.
This page only skims the details on this object. Please read the official Spotify documentation here.
- bars: List[TimeInterval]
- The time intervals of the bars throughout the track. A bar (or measure) is a segment of time defined as a given number of beats.
- beats: List[TimeInterval]
- The time intervals of beats throughout the track. A beat is the basic time unit of a piece of music; for example, each tick of a metronome.
- sections: List[Section]
- List of sections of the track. Sections are defined by large variations in rhythm or timbre, e.g. chorus, verse, bridge, guitar solo, etc.
- segments: List[Segment]
- List of audio segments of the track. Audio segments attempts to subdivide a song into many segments, with each segment containing a roughly consistent sound throughout its duration.
- tatums: List[TimeInterval]
- The time intervals of tatums throughout the track. A tatum represents the lowest regular pulse train that a listener intuitively infers from the timing of perceived musical events (segments).
Image¶
User¶
-
class
asyncspotify.
PublicUser
(client, data)[source]¶ Represents a User object.
- id: str
- Spotify ID of the user.
- name: str
- Name of the user. Also aliased to the
display_name
attribute. - images: List[
Image
] - List of associated images, such as the users profile picture.
- uri: str
- Spotify URI of the user.
- link: str
- Spotify URL of the user.
- follower_count: int or None
- Follower count of the user.
- external_urls: dict
- Dictionary that maps type to url.
-
playlists
()¶ Get the users playlists.
Alias of
Client.get_user_playlists()
-
class
asyncspotify.
PrivateUser
(client, data)[source]¶ Represents a private User object, usually fetched through the
me
endpoint.This type has some additional attributes not existent in
PublicUser
.- country: str
- ISO-3166-1 code of users country.
- email: str
- Email of user. Please do not this email is note necessarily verified by Spotify.
- product: str
- Users Spotify subscription level, could be
free
,open
orpremium
.free
andopen
are synonyms.
-
create_playlist
(name, public=False, collaborative=False, description=None)[source]¶ Create a new playlist.
Parameters: - name (str) – Name of the new playlist.
- description (str) – Description of the new playlist.
- public (bool) – Whether the playlist should be public.
- collaborative (bool) – Whether the playlist should be collaborative (anyone can edit it).
Returns: A
FullPlaylist
instance.
-
playlists
()¶ Get the users playlists.
Alias of
Client.get_user_playlists()
-
top_artists
(limit=20, offset=None, time_range=None)[source]¶ Get the top artists of the current user.
Parameters: - limit (int) – How many artists to return. Maximum is 50.
- offset (int) – The index of the first result to return.
- time_range (str) – The time period for which data are selected to form a top.
- Valid values for
time_range
long_term
(calculated from several years of data and including all new data as it becomes available),medium_term
(approximately last 6 months),short_term
(approximately last 4 weeks).
Returns: List[ SimpleArtist
]
-
top_tracks
(limit=20, offset=None, time_range=None)[source]¶ Gets the top tracks of the current user.
Requires scope
user-top-read
.Parameters: - limit (int) – How many tracks to return. Maximum is 50.
- offset (int) – The index of the first result to return.
- time_range (str) – The time period for which data are selected to form a top.
- Valid values for
time_range
long_term
(calculated from several years of data and including all new data as it becomes available),medium_term
(approximately last 6 months),short_term
(approximately last 4 weeks).
Returns: List[ SimpleTrack
]
Playing Objects¶
-
class
asyncspotify.
CurrentlyPlaying
(client, data)[source]¶ Represents a Currently Playing object.
- timestamp: datetime
- When the object information was created by the Spotify API.
- progress: timedelta
- How far into the current track the player is.
- is_playing: bool
- Whether the track is playing or not.
- track:
Track
- What track is currently playing, can be
None
- currently_playing_type: str
- What is currently playing, can be
track
,episode
,ad
orunknown
.
-
class
asyncspotify.
CurrentlyPlayingContext
(client, data)[source]¶ Represents a Player object, extends
CurrentlyPlaying
This type has some additional attributes not existent in
CurrentlyPlaying
.- device:
Device
- What device is owns this context.
- repeat_state: str
- The repeat state of the player. Can be
off
,track
orcontext
. - shuffe_state: bool
- The shuffle state of the player. Can be
True
orFalse
.
-
play
(**kwargs)[source]¶ Starts playback.
Parameters: kwargs – Body parameters of the request. player_play( context_uri='spotify:album:1Je1IMUlBXcx1Fz0WE7oPT', offset=dict(uri='spotify:track:1301WleyT98MSxVHPZCA6M'), position_ms=1000 )
-
repeat
(state)[source]¶ Set player repeat mode.
Parameters: state (str) – Can be ‘track’, ‘context’ or ‘off’.
- device:
Device¶
-
class
asyncspotify.
Device
(client, data)[source]¶ Represents a Device object.
- is_active: bool
- Whether this device is currently the active device.
- is_private_session: bool
- If the device session is private.
- is_restricted: bool
- Whether controlling this device is restricted. If this is
true
, no API commands will work on it. - name: str
- Name of this device.
- type: str
- Equal to
device
. - volume_percent: int
- Volume of this device. Integer between 0 to 100.
Authenticators¶
A guide on how authentication works is located here.
Examples can also be found under the quickstart guide.
Note
You do not have to worry about when your access token expires as the library will refresh the tokens automatically. Unless you’re rolling your own authenticator, obviously.
ClientCredentialsFlow¶
Only requires a client id and secret to authenticate. Does not give access to private resources. No refresh token is used here. To extend, it simply authorizes again.
-
class
asyncspotify.
ClientCredentialsFlow
(client_id, client_secret, response_class=<class 'asyncspotify.oauth.response.AuthenticationResponse'>)[source]¶ Implements the Client Credentials flow.
You can only access public resources using this authenticator.
Authorize using this authenticator.
-
refresh
(start_task=True)¶ Refresh this authenticator.
EasyAuthorizationCodeFlow¶
Extends AuthorizationCodeFlow
and requires one extra argument, storage
, which tells the authenticator which
file to store tokens in.
-
class
asyncspotify.
EasyAuthorizationCodeFlow
(client_id, client_secret, scope=<Scope value=0>, storage='secret.json', response_class=<class 'asyncspotify.oauth.response.AuthorizationCodeFlowResponse'>)[source]¶ Authorize the client. Reads from the file specificed by store.
Craft the
Route
for the user to use for authorizing the client.
-
get_code_from_redirect
(url)¶ Extract the authorization code from the redirect uri.
-
refresh
(start_task=True)¶ Refresh this authenticator.
AuthorizationCodeFlow¶
Exposes helper methods for implementing a version of the Authorization Code flow. EasyAuthorizationCodeFlow
inherits from this and is recommended for most if access to private resources is required.
-
class
asyncspotify.
AuthorizationCodeFlow
(client_id, client_secret, scope, redirect_uri, response_class=<class 'asyncspotify.oauth.response.AuthorizationCodeFlowResponse'>)[source]¶ Implements the Authorization Code flow.
Note
This class is not for general use, please use
EasyAuthorizationCodeFlow
or subclass this and implement your own load(), store(response) and setup() methods.- client_id: str
- Your application client id.
- client_secret: str
- Your application client secret.
- scope:
Scope
- The scope you’re requesting.
- redirect_uri: str
- Where the user will be redirected to after accepting the client.
- response_class:
- The type that is expected to be returned from load() and setup(), and is passed to store(response) when a token refresh happens.
Should be
AuthorizationCodeFlowResponse
or inherit from it.
Craft the
Route
for the user to use for authorizing the client.
Authorize the client. Reads from the file specificed by store.
-
refresh
(start_task=True)¶ Refresh this authenticator.
Scope¶
You can create a scope with specific permissions by passing kwargs in, like:
scope = Scope(
user_top_read=True,
playlist_modify_private=True
)
-
class
asyncspotify.
Scope
(value=0, **kwargs)[source]¶ Flags representing Spotify scopes.
- ugc_image_upload
- Write access to user-provided images.
- user_modify_playback_state
- Write access to a user’s playback state.
- user_read_playback_state
- Read access to a user’s player state.
- user_read_currently_playing
- Read access to a user’s currently playing content.
- user_top_read
- Read access to a user’s top artists and tracks.
- user_read_playback_position
- Read access to a user’s playback position in a content.
- user_read_recently_played
- Read access to a user’s recently played tracks.
- user_library_modify
- Write/delete access to a user’s “Your Music” library.
- user_library_read
- Read access to a user’s “Your Music” library.
- user_follow_modify
- Write/delete access to the list of artists and other users that the user follows.
- user_follow_read
- Read access to the list of artists and other users that the user follows.
- playlist_read_private
- Read access to user’s private playlists.
- playlist_modify_public
- Write access to a user’s public playlists.
- playlist_modify_private
- Write access to a user’s private playlists.
- playlist_read_collaborative
- Include collaborative playlists when requesting a user’s playlists.
- user_read_private
- Read access to user’s subscription details (type of user account).
- user_read_email
- Read access to user’s email address.
- app_remote_control
- Remote control playback of Spotify. This scope is currently available to Spotify iOS and Android SDKs.
- streaming
- Control playback of a Spotify track. This scope is currently available to the Web Playback SDK. The user must have a Spotify Premium account.
Exceptions¶
-
class
asyncspotify.
SpotifyException
[source]¶ Base exception of all exceptions thrown by this library.
-
class
asyncspotify.
HTTPException
(response, message=None)[source]¶ Bases:
asyncspotify.exceptions.SpotifyException
Base exception of all HTTP related exceptions.
- response: aiohttp.ClientResponse
- The response of the failed HTTP request.
- message: Optional[str]
- Message about what went wrong.
-
class
asyncspotify.
BadRequest
(response, message=None)[source]¶ Bases:
asyncspotify.exceptions.HTTPException
400 Bad Request
Base class for all 4xx status code exceptions.
Bases:
asyncspotify.exceptions.BadRequest
401 Unauthorized
-
class
asyncspotify.
Forbidden
(response, message=None)[source]¶ Bases:
asyncspotify.exceptions.BadRequest
403 Forbidden