Quickstart

This page will guide into installing and setting up a client.

Installing

The recommended way of installing this library is from PyPI.

pip install asyncspotify

Run pip as a module to install for a specific version of Python:

python3.7 -m pip install asyncspotify

To test your installation, you can import asyncspotify and print the version string:

import asyncspotify
print(asyncspotify.__version__)

Getting started

To communicate with the Spotify Web API, you have to create a Spotify Application first. Go to this page and create an app.

After having made an app, you will be forwarded to a page showing miscellaneous stats. The client id and client secret provided here is what you’ll use when authenticating. If you’re going to use the EasyAuthenticationCodeFlow authorizer, you have to click edit and add http://localhost/ to the list of redirect URIs.

To authenticate, you have to create an authenticator. If you do not need to access or modify personal data, you can simply use the ClientCredentialsFlow class:

import asyncio
import asyncspotify


async def main():
	# authenticate using the Client Credentials flow
	auth = asyncspotify.ClientCredentialsFlow(
		client_id='your client id',
		client_secret='your client secret',
	)
	
	# create and authorize your spotify client
	sp = asyncspotify.Client(auth)
	await sp.authorize()

	# done!
	playlist = await sp.get_playlist('1MG01HhbCvVhH9NmXhd9GC')
	async for track in playlist:
		print(track.name)


asyncio.run(main())

If you do need to access and modify personal data, you will have to use the Authentication Code flow and specify the scope you require. The easiest way to do this is to use the EasyAuthenticationCodeFlow class, which will handle storing your tokens and fetching them when your program restarts:

# this flow is "scoped", which means we have to list the resources we want access to.
# you can specify them like this, or do Scope.all() or Scope.none()
scope = asyncspotify.Scope(
	playlist_modify_public=True,
	playlist_modify_private=True,
	playlist_read_private=True,
	playlist_read_collaborative=True
)

# this is where our tokens will be stored
token_file = 'secret.json'

# create our authenticator
auth = asyncspotify.EasyAuthorizationCodeFlow(
	client_id='your client_id',
	client_secret='your client_secret',
	scope=scope,
	storage=token_file
)

# pass it to our new spotify client and authorize
sp = asyncspotify.Client(auth)
await sp.authorize()

# now we can do anything :)
print(await sp.get_me())

The EasyAuthenticationCodeFlow requires a first-time setup, please follow the steps in your console carefully. Remember to add http://localhost/ to the list of redirect URIs on your Spotify Application page!

If you need more granular control of how tokens are stored, you can extend AuthenticationCodeFlow with your own methods.

To see some basic usage of the API, see the examples. For everything else, see the API Reference.