🎵spotipy.nvim

For Neovim users who want to have music at their fingertips.
spotipy.nvim is a plugin that allows you to control your Spotify account from within Neovim.

Features

• Display/Filter the search results with Telescope

• Currently playing statusline.

• Currently playing notification.

• Toggle track status

• Skip a track

• Add a track to queue

• Select which device to play on

• Search by tracks

Requirements

spotipy.nvim is a python based plugin, using the spotipy library to interact with the Spotify API.

• pynvim
• spotipy
• Telescope
• Spotify
• Spotify Premium

As spotipy.nvim only handles the interaction with the Spotify API, you will need a Spotify Premium account to use this plugin.
As Spotify API does not handle the playback of the music, you will need to have the Spotify app running in the background.
The spotipy.nvim plugin was tested using on linux and mac using the full version of the Spotify app, it may not work with spotifyd.

Installation

packer

-- Lua
use {
    "AvivKehrmann/spotipy.nvim",
    requires = 'nvim-telescope/telescope.nvim',
    config = function()
    local spotipy = require("spotipy.nvim")
    spotipy.setup({
        status = {
            update_interval = 10000}
        })
    end
}

lazy.nvim

return {
    {
        "AvivKehrmann/spotipy.nvim",
        requires = "nvim-telescope/telescope.nvim",
        config = function()
            local spotipy = require("spotipy.nvim")
            spotipy.setup({
                status = {
                    update_interval = 10000}
            })
        end
    }
}

Notes

Decreasing the update_interval value means more API calls in a shorter period. Because of the Spotify API rate limiter, setting this too low can block future requests.
Besides that, keep in mind these updates are api calls, they will slow your computer down.
Generally, i use 5000ms as the update interval, and experience no issues.

Connecting to Spotify’s API

spotipy.nvim needs to connect to Spotify’s API in order to find music by name, play tracks etc.

In order to do so please follow these steps:

1. Go to the Spotify dashboard.
2. Click Create an app.
   • You now can see your Client ID and Client Secret.
3. Now click Edit Settings.
4. Add http://localhost:8888/callback (if the spacific port is taken choose any port you'd like) to the Redirect URIs.
5. Scroll down and click Save.
6. You are now ready to authenticate with Spotify!.
7. Go back to the terminal.
8. Add the Client Id, Client Secret, and Redirect URI to your environment variables, by adding the following lines to your .bashrc or .zshrc:

   export SPOTIPY_CLIENT_ID='YOUR_CLIENT_ID'
   export SPOTIPY_CLIENT_SECRET='YOUR_CLIENT_SECRET'
   export SPOTIPY_REDIRECT_URI='http://localhost:'YOUR_PORT'/callback'

9. Use the source command to apply the changes:

   source ~/.bashrc  # or  source ~/.zshrc

10. Use the SpotifyDevices command to connect to your Spotify account.
11. A browser window will open, asking you to log in to your Spotify account.
12. After logging in, you will be redirected to a page that says Authentication complete. You can close this tab.
13. Now you are connected to the Spotify API and can use the spotipy.nvim plugin.

And now you are ready to use the spotipy.nvim

Usage

spotipy.nvim has several commands:

Adding a Track to the Queue

Add a track to the queue (plays it next) by specifying a track URI.

:SpotifyAdd <track_uri>

Connecting to a Device

Open a menu of the devices connected to your Spotify account and select which one to play on.

:SpotifyDevices

Playing a Track

Play a track by providing its URI.

:SpotifyPlay <track_uri>

Controlling Playback

Control the playback with options to skip or go back a track.

:SpotifyPlayback -n/next      # Skip to the next track
:SpotifyPlayback -p/prev      # Go back to the previous track

Displaying the Playlist

Show the next 20 tracks in the queue.

:SpotifyPlaylist

Searching for a Track

Search for a track by providing its name and display the top 20 results.

:SpotifySearch <track_name>

Checking Current Status

Uses the vim.notify API to display the current Spotify status, including track name, album name, artist name, and duration. If no track is playing, an appropriate message will be shown.
Recommented usage with nvim.notify plugin.

:SpotifyStatus

Toggling Playback

Toggle the current playback on or off based on the current state.

:SpotifyToggle

Default keymaps

The following keymaps are set by default, notice they all need to be prefixed with youre leader key.:

mode	key	Description
normal	ms	search for tracks
normal	mt	toggle playback
normal	ml	show Playlist
normal	mn	skip track
normal	mp	go back to the previous track
normal	md	show devices
normal	mm	show current status

Override keymaps

The default keymaps are set during the spotipy.nvim setup function.
Make sure to call the setup function before setting your own keymaps.
You can override the default keymaps by settings your own in the following way:

vim.api.nvim_set_keymap("n", "<leader>mt", ":SpotifyToggle<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>ml", ":SpotifyPlaylist<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>mn", ":SpotifyPlayback -n<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>mp", ":SpotifyPlayback -p<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>mm", ":SpotifyStatus<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>md", ":SpotifyDevices<CR>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<leader>ms", ":lua require('neovim-spotify').search()<CR>", { noremap = true, silent = true })

Statusline

You can display what's currently playing on your status bar.
The example below shows how to show it on lualine, although the configuration should be quite similar on other statusline plugins:

local status = require"spotipy.nvim".status

status:start()

require('lualine').setup {
    sections = {
        lualine_x = {
            status.listen
        }
    }
}

Notifications

You can display the current status and many other notifications using the nvim.notify plugin.

use {
    'rcarriga/nvim-notify',
    config = function()
        vim.notify = require("notify")
    end
    }