# 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](https://dbus.freedesktop.org) 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](https://pypi.org/project/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:

```python
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](#documentation)
for a more complete list of API calls.

## Documentation

To build the docs, install [pdoc](https://pypi.org/project/pdoc/) and run:

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