# spotifyctl

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

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.
Dbus is preinstalled on most Linux distros.

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

Have a look at [the complete API documentation](https://docs.skyforest.net/spotifyctl/index.html)
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](https://docs.skyforest.net/spotifyctl/index.html).
To build it yourself, you can install [pdoc](https://pypi.org/project/pdoc/) and run:

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