You need dbus to be installed and enabled on your system, which is the default on most Linux distros. Dbus can be installed and enabled using brew on MacOS.

spotifyctl depends on the dbus-python package.

Obviously, you need to have Spotify installed as well if you want spotifyctl to be useful.

Getting started

spotifyctl comes as a single, self-contained python script/module.

Simply import spotifyctl in your python program to access the API:

import spotifyctl

# Get the current state of the Spotify player
spotifyctl.player_get_playback_status()
# returns: "playing"

# Toggle bewteen play/pause
spotifyctl.player_action_toggle_play_pause()

# Skip to the next track
spotifyctl.player_action_next()

# Get some metadata for the current track in a python dict
spotifyctl.player_get_track_metadata()
# returns:
# {
#     'album_artist_names': ['Rick Astley'],
#     'album_name': 'Whenever You Need Somebody',
#     'artist_names': ['Rick Astley'],
#     'artwork_url': 'https://i.scdn.co/image/ab67616d0000b2735755e164993798e0c9ef7d7a',
#     'auto_rating': 0.8,
#     'disc_number': 1,
#     'length': datetime.timedelta(seconds=213, microseconds=573000),
#     'title': 'Never Gonna Give You Up',
#     'track_id': '4cOdK2wGLETKBW3PvgPWqT',
#     'track_number': 1,
#     'track_url': 'https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT'
# }

Note that if the Spotify executable is not running, API calls will throw exceptions.

Have a look at spotifyctl.py or build the complete API documentation yourself for a more complete list of API calls.

Documentation

To build the docs, install pdoc and run:

mkdir doc
pdoc --docformat numpy --output-dir ./doc ./spotifyctl.py