# 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
```