spotify.el

by danielfm

danielfm / spotify.el

Control the Spotify app from within Emacs.

153 Stars 22 Forks Last release: Not found GNU General Public License v3.0 151 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Spotify.el

Control Spotify app from within Emacs.

asciicast

Spotify.el is a collection of extensions that allows you to control the Spotify application from within your favorite text editor. If you are running on Mac OS X or Linux, you can control the locally running instance. If you are running on any platform with a network connection (including Windows - and even headless!) and have a Spotify premium subscription, you can control an instance of Spotify via the Spotify Connect feature.

Features

  • Spotify client integration for GNU/Linux (via D-Bus) and OS X (via AppleScript)
  • Device playback display & selection using the Spotify Connect API (requires premium)
  • Communicates with the Spotify API via Oauth2
  • Displays the current track in mode line or title bar
  • Create playlists (public or private)
  • Browse the Spotify featured playlists, your own playlists, and their tracks
  • Search for tracks and playlists that match the given keywords
  • Easily control basic Spotify player features like, play/pause, previous, next, shuffle, and repeat with the Spotify Remote minor mode

Installation

First, make sure your system satisfies the given dependencies:

  • Emacs 24.4+

To manually install spotify.el, just clone this project somewhere in your disk, add that directory in the

load-path
, and require the
spotify
module:
(add-to-list 'load-path "")
(require 'spotify)

;; Settings (setq spotify-oauth2-client-secret "") (setq spotify-oauth2-client-id "") (define-key spotify-mode-map (kbd "C-c .") 'spotify-command-map) </spotify.el-dir>

That keymap prefix is just a suggestion, following the conventions suggested for minor modes as defined in the Emacs manual Key Binding Conventions. Previous versions of this package used "M-p"

In order to get the the client ID and client secret, you need to create a Spotify app, specifying http://localhost:8080/spotify-callback as the redirect URI (or whichever port you have specified via customize). The OAuth2 exchange is handled by

simple-httpd
. If you are not already using this package for something else, you should not need to customize this port. Otherwise, you'll want to set it to whatever port you are running on.

To use the "Spotify Connect" transport (vs. controlling only your local instance - though you can also control your local instance as well), set

spotify-transport
to
'connect
as follows. This feature requires a Spotify premium subscription.
(setq spotify-transport 'connect)

Creating The Spotify App

Go to Create an Application and give your application a name and a description:

Creating a Spotify App 1/3

After creating the new app, click the Edit Settings, scroll down a little bit, type http://localhost:8080/spotify-callback as the Redirect URI for the application, and click Add. Then, hit Save.

Creating a Spotify App 2/3

At this point, the client ID and the client secret are available, so set those values to

spotify-oauth2-client-id
and
spotify-oauth2-client-secret
, respectively.

Creating a Spotify App 3/3

Usage

Remote Minor Mode

Whenever you enable the

spotify-remote-mode
minor mode you get the following key bindings:

| Key | Function | Description | |:---------------------|:-----------------------------|:-------------------------------------------| | C-c . M-s |

spotify-toggle-shuffle
| Turn shuffle on/off [1] | | C-c . M-r |
spotify-toggle-repeat
| Turn repeat on/off [1] | | C-c . M-p |
spotify-toggle-play
| Play/pause | | C-c . M-f |
spotify-next-track
| Next track | | C-c . M-b |
spotify-previous-track
| Previous track | | C-c . p m |
spotify-my-playlists
| Show your playlists | | C-c . p f |
spotify-featured-playlists
| Show the featured playlists | | C-c . p s |
spotify-playlist-search
| Search for playlists | | C-c . p u |
spotify-user-playlists
| Show playlists for the given user | | C-c . p c |
spotify-create-playlist
| Create a new playlist | | C-c . t r |
spotify-recently-played
| List of recently played tracks | | C-c . t s |
spotify-track-search
| Search for tracks | | C-c . v u |
spotify-volume-up
| Increase the volume [2] | | C-c . v d |
spotify-volume-down
| Decrease the volume [2] | | C-c . v m |
spotify-volume-mute-unmute
| Alternate the volume between 0 and 100 [2] | | C-c . d |
spotify-select-device
| Select a playback device [2] |

The current song being played by the Spotify client is displayed in the mode line along with the player status (playing, paused). The interval in which the player status is updated can be configured via the

spotify-player-status-refresh-interval
variable:
;; Updates the player status every 10 seconds (default is 5)
;; Note: Set 0 to disable this feature, and avoid values between 1 and 4 when
;; using the 'connect transport.
(setq spotify-player-status-refresh-interval 10)

[1] No proper support for this in D-Bus implementation for GNU/Linux
[2] This feature uses Spotify Connect and requires a premium subscription

Users of the package hydra may find the code below more convenient for managing Spotify:

;; A hydra for controlling spotify.
(defhydra hydra-spotify (:hint nil)
    "
^Search^                  ^Control^               ^Manage^
^^^^^^^^-----------------------------------------------------------------
_t_: Track               _SPC_: Play/Pause        _+_: Volume up
_m_: My Playlists        _n_  : Next Track        _-_: Volume down
_f_: Featured Playlists  _p_  : Previous Track    _x_: Mute
_u_: User Playlists      _r_  : Repeat            _d_: Device
^^                       _s_  : Shuffle           _q_: Quit
"
    ("t" spotify-track-search :exit t)
    ("m" spotify-my-playlists :exit t)
    ("f" spotify-featured-playlists :exit t)
    ("u" spotify-user-playlists :exit t)
    ("SPC" spotify-toggle-play :exit nil)
    ("n" spotify-next-track :exit nil)
    ("p" spotify-previous-track :exit nil)
    ("r" spotify-toggle-repeat :exit nil)
    ("s" spotify-toggle-shuffle :exit nil)
    ("+" spotify-volume-up :exit nil)
    ("-" spotify-volume-down :exit nil)
    ("x" spotify-volume-mute-unmute :exit nil)
    ("d" spotify-select-device :exit nil)
    ("q" quit-window "quit" :color blue))

(bind-key "a" #'hydra-spotify/body some-map)

Customizing The Player Status

The information displayed in the player status can be customized by setting the desired format in

spotify-player-status-format
. The following placeholders are supported:

| Symbol | Description | Example | |:------:|:---------------------------|:-------------------------------| |

%u
| Track URI |
spotify:track:
| |
%a
| Artist name (truncated) |
Pink Floyd
| |
%t
| Track name (truncated) |
Us and Them
| |
%n
| Track # |
7
| |
%l
| Track duration, in minutes |
7:49
| |
%r
| Player repeat status |
R
,
-
| |
%s
| Player shuffle status |
S
,
-
| |
%p
| Player playing status |
Playing
,
Paused
,
Stopped
|

The default format is

"[%p: %a - %t ◷ %l %r%s]"
.

The number of characters to be shown in truncated fields can be configured via the

spotify-player-status-truncate-length
variable.
(setq spotify-player-status-truncate-length 10) ; default: 15

The text indicator for each of the following player statuses can be configured via their corresponding variables:

| Player State | Variable | Default Value | |:--------------|:-------------------------------------------|:-------------:| | Playing |

spotify-player-status-playing-text
|
"Playing"
| | Paused |
spotify-player-status-paused-text
|
"Paused"
| | Stopped |
spotify-player-status-stopped-text
|
"Stopped"
| | Shuffling On |
spotify-player-status-repeating-text
|
"R"
| | Shuffling Off |
spotify-player-status-not-repeating-text
|
"-"
| | Repeating On |
spotify-player-status-shuffling-text
|
"S"
| | Repeating Off |
spotify-player-status-not-shuffling-text
|
"-"
|

Global Remote Mode

This mode can be enabled globally by running M-x global-spotify-remote-mode.

Searching For Tracks

To search for tracks, run M-x spotify-track-search and type in your query. The results will be displayed in a separate buffer with the following key bindings:

| Key | Description | |:-----------------|:-----------------------------------------------------------------| | a | Adds track to a playlist | | l | Loads the next page of results (pagination) | | g | Clears the results and reloads the first page of results | | M-RET | Plays the track under the cursor in the context of its album [1] |

[1] D-Bus implementation for GNU/Linux do not support passing the context, so only the track under the cursor will be played

The resulting buffer loads the

spotify-remote-mode
by default.

Tip: In order to customize the number of items fetched per page, just change the variable

spotify-api-search-limit
:
;; Do not use values larger than 50 for better compatibility across endpoints
(setq spotify-api-search-limit 50)

Playing a Spotify URI

To ask the Spotify client to play a resource by URI, run M-x spotify-play-uri and enter the resource URI.

Creating Playlists

To create new playlists, run M-x spotify-create-playlist and follow the prompts.

Currently it's not possible to add tracks to a playlist you own, or to remove tracks from them.

Searching For Playlists

To return the playlists for the current user, run M-x spotify-my-playlists, or M-x spotify-user-playlists to list the public playlists for some given user. To search playlists that match the given search criteria, run M-x spotify-playlist-search CRITERIA. Also, run M-x spotify-featured-playlists in order to browse the featured playlists from Spotify en_US.

Change the following variables in order to customize the locale and region for the featured playlists endpoint:

;; Spanish (Mexico)
(setq spotify-api-locale "es_MX")
(setq spotify-api-country "MX")

All these commands will display results in a separate buffer with the following key bindings:

| Key | Description | |:-----------------|:---------------------------------------------------------| | l | Loads the next page of results (pagination) | | g | Clears the results and reloads the first page of results | | f | Follows the playlist under the cursor | | u | Unfollows the playlist under the cursor | | t | Lists the tracks of the playlist under the cursor | | M-RET | Plays the playlist under the cursor |

Once you open the list of tracks of a playlist, you get the following key bindings in the resulting buffer:

| Key | Description | |:-----------------|:--------------------------------------------------------------------| | a | Adds track to a playlist | | l | Loads the next page of results (pagination) | | g | Clears the results and reloads the first page of results | | f | Follows the current playlist | | u | Unfollows the current playlist | | M-RET | Plays the track under the cursor in the context of the playlist [1] |

Both buffers load the

spotify-remote-mode
by default.

[1] D-Bus implementation for GNU/Linux do not support passing the context, so only the track under the cursor will be played

Selecting a Device for Playback

M-x spotify-select-device will display a list of devices available for playback in a separate buffer.

Note: use of this feature requires a Spotify premium subscription.

Once you open the list of devices, you get the following key bindings in the resulting buffer:

| Key | Description | |:-----------------|:--------------------------------------------------------------------| | RET | Transfer playback to the device under the cursor. | | g | Reloads the list of devices |

Specifying the Player Status Location

By default, the player status (playing, paused, track name, time, shuffle, repeat, etc.) are shown in the modeline. If you want to display the status in the title bar when using a graphical display, you can set the following:

(setq spotify-status-location 'title-bar)

Valid values include

'title-bar
,
'modeline
and
nil
, where nil turns off the display of the player status completely. If the value is set to
title-bar
but you are not using a graphical display, the player status will be displayed in the mode line instead.

If you want to customize the separator between the existing title bar text and the player status, you can set the following, i.e.:

el
(setq spotify-title-bar-separator "----")
Otherwise, it defaults to 4 spaces.

License

Copyright (C) Daniel Fernandes Martins

Distributed under the GPL v3 License. See COPYING for further details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.