A premium, lightweight, asynchronous YouTube music & audio player built directly inside Neovim.
Powered by pure Lua, UNIX domain socket IPC, mpv, and yt-dlp. Zero external servers. Zero editor lag.
Rendered preview with sample tracks. Click the image to view it at full size.
The player opens as a framed terminal music station: an animated record deck, a live visualizer, a formatted queue table with artist and duration columns, and a persistent transport bar. Mint, cyan, and amber accents distinguish playback state, metadata, and controls. All player backgrounds are transparent (including panels, tabs, selections, borders, and search input) so your terminal and editor transparency show through cleanly.
mpv process over a local UNIX domain socket. Stream extraction and playback never block your editor or drop keystrokes.sponsorblock = true to skip sponsor segments, intros, outros, self-promos, and non-music sections so your focus remains uninterrupted (uses curl).mpv: an instance that finds a player already running attaches to it instead of starting a second one.mpv + yt-dlp (plus curl for the optional SponsorBlock). No Python daemons, no Node.js processes, no Electron bloat.:YT):cmus and ncmpcpp) featuring an animated vinyl deck, interactive progress bar, live music visualizer, structured queue table, and persistent transport bar.:YT always opens the main Deck tab by default and starts with a clean search prompt.:YT mini β Toggles a floating Mini HUD in the top-right corner with record artwork, playback progress, visualizer, and next-track preview.:YT player β Toggles a docked sidebar panel with the same deck and framed queue.:YT search):<CR>), append to queue (a), save to playlist (s), or paginate for more results (L).:YT queue_edit):J/K, remove with dd, or shuffle the entire queue with S. Currently playing track is highlighted in bold green.:YT playlists):Tab). Create (N), rename (r), play (<CR>), queue (a), or remove tracks/playlists (dd with confirmation).:YT history):5m ago, 2h ago), instant replay, and one-key queueing. Clear history anytime with :YT history clear (or :YT history_clear).:YT queue_playlist)::YT resume)::YT resume.vim.g.have_nerd_font or configured explicitly).Before installing, ensure the following tools are available in your system PATH:
mpv and yt-dlpbrew install mpv yt-dlp
Ubuntu / Debian:
sudo apt update
sudo apt install mpv yt-dlp
(Note: If your distribution repository has an outdated yt-dlp, you can install the latest release via pipx install yt-dlp or direct binary download).
Arch Linux / Manjaro:
sudo pacman -S mpv yt-dlp
Fedora / RHEL:
sudo dnf install mpv yt-dlp
openSUSE:
sudo zypper install mpv yt-dlp
Alpine Linux:
sudo apk add mpv yt-dlp
Install using your preferred package manager:
vim.pack (Neovim Native Package Manager)vim.pack.add({
{ src = "https://github.com/sanjay-np/nvim-yt-player" },
{ src = "https://github.com/nvim-lualine/lualine.nvim" }, -- optional, for statusline component
})
require("yt-player").setup({
-- your configuration overrides here (see Configuration section)
})
{
"sanjay-np/nvim-yt-player",
dependencies = { "nvim-lualine/lualine.nvim" }, -- optional, for statusline component
config = function()
require("yt-player").setup({
-- your configuration overrides here (see Configuration section)
})
end,
}
use {
"sanjay-np/nvim-yt-player",
requires = { "nvim-lualine/lualine.nvim" }, -- optional
config = function()
require("yt-player").setup()
end,
}
Plug 'sanjay-np/nvim-yt-player'
Plug 'nvim-lualine/lualine.nvim' " optional
" In your configuration:
lua require('yt-player').setup()
Play a track or search query directly:
:YT play https://www.youtube.com/watch?v=dQw4w9WgXcQ
" Or search directly by name:
:YT play lofi hip hop beats
Open the Unified Music Hub:
:YT
Search for songs inside the Hub:
:YT search lofi chill
:YT)When inside the unified Hub window, navigate and control playback with the following keys:
| Key | Action |
|---|---|
1 β 5 |
Switch tab directly: Deck (1), Search (2), Queue (3), Playlists (4), History (5) |
Tab / Shift-Tab |
Cycle tabs forward / backward (or switch between playlist list and track list on Playlists tab) |
j / k or β / β |
Move selection down / up |
gg / G |
Jump to first / last item |
Ctrl-d / Ctrl-u |
Scroll half-page down / up |
Enter (<CR>) |
Contextual play: play selected track, execute search, or play entire playlist |
Space / p |
Toggle play / pause |
n / b |
Skip to next / previous track in queue |
+ / - |
Volume up / down (Β±5%) |
m |
Toggle mute |
> / < |
Speed up / down (Β±0.25x) |
h / l |
Seek Β±5s (relative) / switch playlist pane |
/ or i |
Focus YouTube search input (switches to Search tab) |
a / A / <C-a> |
Contextual queue: queue search result, playlist track, or history item; save active queue track |
s |
Save selected track to a local playlist |
dd |
Remove item from queue / delete playlist (with confirmation) |
J / K |
Move selected track down / up in queue |
S |
Shuffle queue |
L |
Load more search results (pagination) |
N |
Create a new playlist (Playlists tab) |
r |
Toggle autoplay radio mode (on Playlists tab: rename selected playlist) |
R |
Cycle repeat mode (File π β Playlist π β Off) |
v |
Cycle visualizer style (wave β bars β dots β none) |
? |
Toggle shortcuts cheatsheet overlay |
q / <Esc> |
Close Hub |
When typing inside the embedded search bar:
Enter (<CR> in normal or insert mode): Submit search queryβ / <C-j> / <Tab> / j: Move focus to search results<Esc>: Return to normal modeq: Close Hub:YT mini) & Sidebar (:YT player) ControlsWhen either the docked side-panel (:YT player) or floating window (:YT mini) is focused:
| Keymap | Action |
|---|---|
Space / t |
Toggle play / pause |
p / s |
Play / Pause explicitly |
n / b |
Next / Previous track |
+ / - |
Volume Β±5% |
m |
Mute toggle |
> / < |
Speed Β±0.25x |
l / h |
Seek Β±5s (relative) |
L / H |
Seek Β±30s (relative) |
0 to 9 |
Seek to percentage (0% to 90% of track) |
G |
Seek to 100% (ends current track) |
r |
Toggle autoplay radio mode |
R |
Cycle repeat mode (Track π β Playlist π β Off) |
q / <Esc> |
Close player window |
All commands are available under the master :YT command with tab completion:
| Command | Description |
|---|---|
:YT |
Open / toggle the Unified Hub (defaults to Deck tab, Tab 1) |
:YT play [url or query] |
Play a URL or search query, or resume paused playback |
:YT pause |
Pause playback |
:YT toggle |
Toggle play / pause |
:YT stop |
Stop playback entirely |
:YT next / :YT prev |
Skip to next / previous track in queue |
:YT seek <seconds or MM:SS> |
Seek to absolute position (e.g. :YT seek 90 or :YT seek 1:30) |
:YT seek_rel <Β±seconds> |
Seek relative position (e.g. :YT seek_rel -10 or :YT seek_rel 30) |
:YT volume <0-100> |
Set playback volume |
:YT vol_up / :YT vol_down |
Increase / decrease volume by 5% |
:YT mute |
Toggle mute state |
:YT speed [value] |
Set or inspect speed (e.g. :YT speed 1.25, :YT speed up, :YT speed +0.1) |
:YT shuffle |
Shuffle active queue |
:YT repeat_toggle |
Toggle playlist repeat on/off |
:YT radio [on|off|toggle] |
Toggle or set autoplay radio mode (ON by default) |
:YT player |
Toggle docked player sidebar panel |
:YT mini |
Toggle top-right floating Mini HUD |
:YT search [query] |
Open search tab inside the Hub (with optional query) |
:YT queue <url> |
Append track URL to active queue |
:YT queue_edit |
Open interactive queue editor inside the Hub (Tab 3) |
:YT queue_playlist <url> |
Parse and append an entire YouTube playlist |
:YT playlists |
Open local playlists manager inside the Hub (Tab 4) |
:YT history |
Open play history timeline inside the Hub (Tab 5) |
:YT history clear / :YT history_clear |
Clear saved play history |
:YT resume |
Restore the queue, track, position, volume, speed, and repeat mode saved when Neovim last exited |
Default configuration options:
require("yt-player").setup({
ui = {
nerd_fonts = "auto", -- true, false, or "auto" (respects vim.g.have_nerd_font; otherwise Unicode)
theme = "auto", -- automatically inherits your active colorscheme
border = "rounded", -- "rounded", "single", "double", "solid", "none"
visualizer = "wave", -- "wave", "bars", "dots", "none"
mini = {
position = "top_right", -- "top_right", "bottom_right", "center"
width = 54,
},
},
statusline = {
enabled = true,
format = "{icon} {title} - {artist} [{position}/{duration}]",
icon_playing = "βΆ",
icon_paused = "βΈ",
truncate_title = 30,
progress_width = 10,
},
search = {
limit = 10, -- number of search results to fetch per page
},
notifications = {
enabled = true,
notify_on_track_change = true, -- notify when a new song starts playing
format = "βΆ {title} - {artist}",
icon_playing = "βΆ",
timeout = 3000, -- ms; honoured by notification UIs such as nvim-notify and snacks.nvim
},
player = {
queue_display_limit = 10, -- upcoming tracks shown in player layouts
},
keymaps = {
enabled = false, -- set to true to enable global keymaps
prefix = "<leader>y",
play = "p",
pause = "s",
toggle = "t",
next = "n",
prev = "b",
mute = "m",
volume_up = "+",
volume_down = "-",
seek_forward = "f",
seek_backward = "r",
speed_up = ">",
speed_down = "<",
},
radio = {
enabled = true, -- autoplay radio enabled by default
limit = 5, -- related tracks to fetch when queue is running low
},
youtube = {
-- yt-dlp player clients used by mpv's ytdl_hook to resolve streams.
-- YouTube 403-blocks stream URLs resolved via default clients (ANDROID_VR/MWEB/WEB).
-- Verified working clients: "android,tv_simply", "android", "tv_simply", "web_music".
player_client = "android,tv_simply",
},
sponsorblock = false, -- true: skip sponsor, intro, outro, self-promo, and non-music segments (needs curl)
})
Customize statusline.format with these placeholders:
{icon} β Play/Pause status icon (βΆ / βΈ){title} β Current track title (truncated per config){artist} β Channel / uploader name{album} β Album name (if available){position} β Current playback position (e.g. 2:45){duration} β Total track duration (e.g. 4:10){progress} β Graphical progress bar (e.g. ββββββββββ){volume} β Volume percentage (0β100){speed} β Speed multiplier, shown only when not 1x (e.g. 1.25x){radio} β Autoplay radio status icon (π» when enabled)Customize notifications.format with:
{icon} β Play icon (notifications.icon_playing){title} β Track title{artist} β Channel name (when unknown, it is dropped along with the separator before it)One notification is shown per track, once its real title is known.
Add yt-player directly into any lualine section:
require("lualine").setup({
sections = {
lualine_x = { "yt-player" },
},
})
All UI surfaces use transparent backgrounds (bg = "NONE") by default. You can easily customize any element to match your theme:
-- Surface & Borders
vim.api.nvim_set_hl(0, "YtPlayerNormal", { fg = "#d9e2ef" })
vim.api.nvim_set_hl(0, "YtPlayerBorder", { fg = "#60758d" })
vim.api.nvim_set_hl(0, "YtPlayerFrame", { fg = "#60758d" })
vim.api.nvim_set_hl(0, "YtPlayerTitle", { fg = "#8ee3b5", bold = true })
vim.api.nvim_set_hl(0, "YtPlayerFooter", { fg = "#8594a8" })
-- Tabs & Badges
vim.api.nvim_set_hl(0, "YtPlayerTabActive", { fg = "#8ee3b5", bold = true, underline = true })
vim.api.nvim_set_hl(0, "YtPlayerTabInactive", { fg = "#8594a8" })
vim.api.nvim_set_hl(0, "YtPlayerKeyHint", { fg = "#81cce5" })
-- Playback & Progress
vim.api.nvim_set_hl(0, "YtPlayerPlaying", { fg = "#8ee3b5", bold = true })
vim.api.nvim_set_hl(0, "YtPlayerSelected", { fg = "#8ee3b5", bold = true })
vim.api.nvim_set_hl(0, "YtPlayerProgress", { fg = "#8ee3b5", bold = true })
vim.api.nvim_set_hl(0, "YtPlayerProgressBg", { fg = "#60758d" })
vim.api.nvim_set_hl(0, "YtPlayerVolume", { fg = "#81cce5" })
vim.api.nvim_set_hl(0, "YtPlayerSpeed", { fg = "#ecc48d" })
vim.api.nvim_set_hl(0, "YtPlayerRadio", { fg = "#ecc48d" })
-- Track Metadata
vim.api.nvim_set_hl(0, "YtPlayerTitleText", { fg = "#d9e2ef", bold = true })
vim.api.nvim_set_hl(0, "YtPlayerArtist", { fg = "#81cce5" })
vim.api.nvim_set_hl(0, "YtPlayerDuration", { fg = "#81cce5" })
vim.api.nvim_set_hl(0, "YtPlayerMuted", { fg = "#8594a8" })
Neovim (Lua) ββ UNIX Domain Socket βββ mpv βββ yt-dlp βββ YouTube Stream
mpv process with IPC enabled over a local UNIX domain socket.mpv through a socket at stdpath("cache")/nvim-yt-player/ipc.sock. An instance that finds a player listening there attaches to it rather than spawning another. A client registry tracks the open instances: playback continues while any of them is running, and mpv is shut down when the last one exits.yt-dlp) execute asynchronously using vim.uv (libuv) child processes and pipes.Tracks skip instantly with no audio?
YouTube periodically 403-blocks direct stream URLs resolved by yt-dlp's default player clients (ANDROID_VR/MWEB/WEB). This plugin forces verified working clients via youtube.player_client ("android,tv_simply" by default). If streams fail, you can try alternate clients:
require("yt-player").setup({
youtube = { player_client = "web_music" }, -- or "android", "tv_simply"
})
No audio playing?
Verify that both mpv and yt-dlp can stream directly in your terminal:
mpv --no-video "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
Streams fail to load?
Update yt-dlp to ensure you have the latest YouTube extractors:
yt-dlp -U
mpv exited with error?
Ensure mpv was compiled with Lua support. Most native distribution package managers (brew, apt, pacman) compile with Lua enabled by default.
SponsorBlock never skips anything?
Check that sponsorblock = true is set and curl is on your PATH. Segments come from community submissions, so many music videos simply have none.
Warning that a history or playlists file was unreadable?
This usually means the JSON was edited by hand and is no longer valid. The plugin moves the file aside to <name>.json.corrupt-<timestamp> in stdpath("data") instead of overwriting it. Fix the JSON in that backup and rename it back to restore your data.
Q: Does this download videos to my computer?
A: No. It streams only the audio tracks in real-time, saving disk space and bandwidth.
Q: Can multiple Neovim instances share playback?
A: Yes. Whichever instance starts playback runs a single background mpv, and the others share it. An instance opened after playback began attaches at startup. One that was already open attaches the first time you use :YT (or the Hub) in it. Attached instances show the same statusline and can control the player. Closing one instance doesn't stop the music while others are still open.
Q: Does it work with private playlists?
A: Local playlists created inside Neovim (:YT playlists) are stored locally as JSON in your Neovim data path (stdpath('data')).
Contributions, issues, and feature requests are welcome!
Check out our Contributing Guidelines to get started with local testing and development.
Distributed under the MIT License. See LICENSE for more information.