Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chiply/spot4e

Emacs client for Spotify search and playback using helm
https://github.com/chiply/spot4e

emacs emacs-helm spotify-api

Last synced: 2 months ago
JSON representation

Emacs client for Spotify search and playback using helm

Awesome Lists containing this project

README 

        
* spot4e

An emacs helm interface for searching Spotify and controlling

playback (on premium).



Of note, spot4e controls Spotify via the Spotify API, not

dbus.  This means you can control Spotify _playback_ on whichever

device Spotify is currently active.  For example, you can control

Spotify playback on your iPhone or Google Home if you wish.  You do

not have to have Spotify open on the computer running emacs.



This feature also means that spot4e should work as-is on most

operating systems.



* Installation

** Dependencies

spot4e depends upon lisp packages json, url, and helm to function properly.



Also, this app is NOT a backdoor to Spotify.  You need to have a

premium account to use playback features!



** Installation instructions

This package is not yet on MELPA.



To install, simply download the spot4e.el file and install however you

like.



For example, clone the project to whichever location you prefer, and

add the directory to your load path.  I recommend placing the

following to your init file:



#+BEGIN_SRC emacs-lisp

(add-to-list 'load-path "/path/to/spot4e")

#+END_SRC



** Initial setup

Because spot4e controls a given user's Spotify playback, it requires

each user allow spot4e to access user data.  Each user must authorize

spot4e through Spotify's [[https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow][Authorization Code Flow]], so there is some

setup required:



*** Step 1:

To credential the app, run the interactive function spot4e-authorize:



M-x spot4e-authorize



This will open a login page in your browser.  



*** Step 2 

Log in (or click ok if you are already logged in).  You will be

redirected to Spotify's home page, where the URL contains your

authorization code:



https://www.spotify.com/us/?code=AUTH_CODE_HERE



*** Step 3

Copy the this code and paste into the emacs minibuffer prompt "Enter code

from URL" and press enter



*** Step 4

This authorization process has given you a refresh token, stored in

spot4e-refresh-token, which you will want to save for future sessions.



I recommend storing this token in your emacs config file:



#+BEGIN_SRC emacs-lisp

(setq spot4e-refresh-token "REFRESH_TOKEN_HERE")

#+END_SRC



Note: you can get your refresh token by simply typing

spot4e-refresh-token into any buffer, placing your cursor immediately

after the variable, and pressing C-u C-x C-e.  This evaluates the

variable and prints the output at point. 



*** Step 5

This refresh token does not expire and will be good for future

sessions.  The access-token, however, does expire every hour, so I

recommend refreshing it periodically with the spot4e-refresh function.

I recommend adding the following to your config file as well:



#+BEGIN_SRC emacs-lisp

(run-with-timer 0 (* 60 59) 'spot4e-refresh)

#+END_SRC



* Usage

To reiterate from the summary, spot4e controls user's Spotify _playback_

through the Spotify API.  You must have an active Spotify session for

spot4e to trigger playback on the respective device.



** Playback control

You can control Spotify playback with the following.



| spot4e-message-currently-playing | message current track in minibuffer |

| spot4e-player-play               | send play to Spotify playback       |

| spot4e-player-pause              | send pause to Spotify playback      |

| spot4e-player-next               | send next to Spotify playback       |

| spot4e-player-previous           | send previous to Spotify playback   |



** Search

*** Search track by album-, artist-, or track name

To start searching for tracks:



M-x spot4e-search-tracks



and begin searching for tracks.



Of note, this interfaces with the tracks search endpoint which allows

you to search for tracks by artist, album, and track name.



Once the items appear, you can go to next an previous with either the

C-n and C-p commands, respectively or the  and  keys,

respectively.



To play a track, simply press Enter.  By default, the track plays in

the context of the album in which it appears, otherwise playback stops

after the song is finished.

*** Search for album by album- or artist- name

To start searching for albums:



M-x spot4e-search-albums



and begin searching for albums



Navigate through tracks as usual and press enter to see album tracks.

Press enter on an album track to play the track.  You can navigate

back to search-albums with .

*** Search for artist by artist- name

To start searching for artists:



M-x spot4e-search-artists



and begin searching for artists



Navigate through artists as usual and press enter to see artist albums.

Press enter on an artist album to see album tracks.  You can navigate

back to search-albums with .



Press enter on album-track to play the track.

** Browse

*** Browse category --> playlist

To start the category browser:



M-x spot4e-helm-search-categories



And browse categories.  Press enter on a category to see that

category's playlists.  Press enter on a playlist to see a category's

tracks.  Press enter on a track to play the track.



A crude model for this browse interface is:



category<-->playlist<-->track



Note you can 'go back', let's say from playlists to category, by

pressing .  This makes browsing more natural - similar to what

you might experience in the Spotify app.



*** Browse new releases by album

To start the new releases browser:



M-x spot4e-helm-search-new-releases



And browse new releases.  Note these are albums.  Press enter on a new

release to see the tracks (note most of these new releases will be

singles, so there may only be one or two tracks).  Press enter on a

track to play the track.  Go back to new releases with .



*** Browse featured-playlists

To start browsing featured playlists:



M-x spot4e-helm-search-featured-playlists



And browse featured playlists.  Press enter on a playlist to view

it's tracks.  Press enter on a track to play the track or  to go

back to playlists.

*** Browse user-playlists

To start browsing user owned and followed playlists:



M-x spot4e-helm-search-user-playlists



And browse user followed playlists.  Press enter on a playlist to view

it's tracks.  Press enter on a track to play the track or  to go

back to playlists.

*** Browse user-artists

To start browsing user followed artists:



M-x spot4e-helm-search-user-artists



Navigate through artists as usual and press enter to see artist albums.

Press enter on an artist album to see album tracks.  You can navigate

back to search-albums with .



Press enter on album-track to play the track.

*** Browse user-tracks

To start browsing user saved tracks:



M-x spot4e-helm-search-user-tracks



and browse user-saved tracks.



Press enter on a track to play the track.



*** Browse recommended tracks based on currently playing track

Assuming a track is playing, start the recommended track browser with:



M-x spot4e-helm-search-recommendations-track



And browse recommendations.  Of note, if done repeatedly, the

recommended track list varies slightly, as I imagine there is some

randomization that occurs in Spotify's recommendation engine. 



Of note you can also get recommendations from the

spot4e-helm-search-tracks interface by pressing .  This way you

can get recommendations based upon specific songs you have in



** User data

*** Save tracks

To save a track:



spot4e-save.



This will then appear in your saved tracks on Spotify (can access

these with spot4e-helm-search-user-tracks).  Note that you can also

save tracks from the spot4e-helm-search-tracks interface with

spot4e-save. 

* Credits

This package was primarily inspired by Kris Jenkins's [[https://github.com/krisajenkins/helm-spotify/blob/master/README.org][helm-spotify]],

with the main differences being support for authentication and control

of playback on third-party devices.  



Credit is also due to the developers of the Spotify API, whose

excellent design made the development of this app straightforward.