spotify.nvim

Native Spotify Web API integration for Neovim.

Features

• Playback controls: play, pause, toggle, next, previous
• :SpotifyLike to save the current track to Liked Songs
• Async playback polling cache for statusline usage
• statusline() helper for lualine.nvim / heirline.nvim
• OAuth login flow with local callback server (:SpotifyLogin)
• Optional Telescope pickers:
  • :SpotifySearch
  • :SpotifyPlaylists
  • :SpotifyDevices

Requirements

• Neovim 0.9+
• nvim-lua/plenary.nvim
• nvim-telescope/telescope.nvim (optional, only for pickers)
• A Spotify Premium account for playback control endpoints

Installation (lazy.nvim)

{
  "soon2moon/spotify.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-telescope/telescope.nvim", -- optional
  },
  config = function()
    require("spotify").setup({
      client_id = vim.env.SPOTIFY_CLIENT_ID,
      client_secret = vim.env.SPOTIFY_CLIENT_SECRET,
      redirect_uri = "http://127.0.0.1:8888/callback",
      notify_on_track_change = true,
    })
  end,
}

Spotify App Setup

1. Open https://developer.spotify.com/dashboard.
2. Create an app and copy Client ID and Client Secret.
3. Add your redirect URI (default): http://127.0.0.1:8888/callback.
4. Provide credentials via setup options or environment variables:
   • SPOTIFY_CLIENT_ID
   • SPOTIFY_CLIENT_SECRET
5. Run :SpotifyLogin in Neovim and approve access in browser.

Token data is stored at:

vim.fn.stdpath("data") .. "/spotify/auth.json"

Commands

• :SpotifyLogin
• :SpotifyLogout
• :SpotifyPlay [spotify:uri]
• :SpotifyPause
• :SpotifyToggle
• :SpotifyNext
• :SpotifyPrev
• :SpotifyLike
• :SpotifyNowPlaying
• :SpotifySearch [query] (Telescope)
• :SpotifyPlaylists (Telescope)
• :SpotifyDevices (Telescope)
• :SpotifyTransfer <device_id>

Lua API

local spotify = require("spotify")

spotify.setup({...})
spotify.play()
spotify.pause()
spotify.toggle()
spotify.next()
spotify.prev()
spotify.like()
spotify.search({ query = "boards of canada" })
spotify.playlists()
spotify.devices()

spotify.statusline() returns a short text string for statusline components.

Statusline Integration

lualine.nvim

require("lualine").setup({
  sections = {
    lualine_x = {
      function()
        return require("spotify").statusline()
      end,
    },
  },
})

Default Configuration

require("spotify").setup({
  client_id = vim.env.SPOTIFY_CLIENT_ID,
  client_secret = vim.env.SPOTIFY_CLIENT_SECRET,
  redirect_uri = "http://127.0.0.1:8888/callback",
  callback_host = "127.0.0.1",
  callback_port = 8888,
  auth_timeout_ms = 120000,
  scopes = {
    "user-read-playback-state",
    "user-modify-playback-state",
    "user-read-currently-playing",
    "user-library-modify",
    "playlist-read-private",
    "playlist-read-collaborative",
  },
  token_path = vim.fn.stdpath("data") .. "/spotify/auth.json",
  poll_interval_ms = 5000,
  auto_start_polling = true,
  notify_on_track_change = false,
  notify_timeout = 2000,
  statusline = {
    icon = "󰓇",
    playing_icon = "",
    paused_icon = "",
    stopped_text = "",
    max_title_length = 60,
  },
  telescope = {
    layout_strategy = "horizontal",
    layout_config = {
      width = 0.9,
      height = 0.8,
      preview_width = 0.55,
    },
  },
})