spotifyctl

spotifyctl is a python module/API with which you can query and control the Spotify executable.

It works by talking to Spotify via dbus, letting you control the current playback or getting metadata about the currently playing track.

Dependencies

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'
# }

Have a look at the complete API documentation for a more complete list of API calls.

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

Documentation

The API documentation is hosted here. To build it yourself, you can install pdoc and run:

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