🎵 nvim-yt-player

A premium, lightweight, asynchronous YouTube audio player built directly inside Neovim. Powered by mpv and yt-dlp, it plays audio seamlessly in the background without freezing your editor or requiring complex Node.js/browser extensions.

---

✨ Features

• ⚡ Zero-Freeze Asynchronous Playback: Stream fetching and caching run entirely in the background. Neovim remains 100% responsive.
• 🏗️ Zero-Dependency Backend: Pure Lua talking to a local mpv process over a UNIX domain IPC socket. No bloated servers or external daemons needed.
• 🎨 Premium Player Layouts:
  • :YT player — Toggles a dedicated side-panel buffer featuring a beautiful custom ASCII bounding-box, a live bouncing music visualizer, an interactive progress slidebar, and volume/speed tracking.
  • :YT mini — Toggles a gorgeous floating window with the same premium visual player layout.
• 🔍 Interactive Search Picker (:YT search): Query YouTube and pick a result using a beautiful floating picker displaying channel names and track durations.
• 📁 Local Playlists (:YT playlists): Save tracks instantly with s and manage them inside a split-pane local playlist manager.
• 📝 Interactive Queue Editor (:YT queue_edit): Reorder tracks with J/K or delete them with dd in real-time.
• 🎵 Seamless Playlist Ingestion (:YT queue_playlist): Rapidly ingest and parse YouTube playlists containing 100+ tracks without blocking the UI.
• ⏩ Auto SponsorBlock: Automatically skip sponsors, intros, and non-music off-topic segments (enable in config).
• 📻 Autoplay Radio Mode (:YT radio): Endless recommendation stream (enabled by default). Spawns the YouTube Mix playlist matching your active song, deduplicates against active queue and history, and seamlessly appends fresh tracks before your queue ends.
• 📊 Lualine & Statusline Integration: Formats playing state, volume, speed, and real-time progress bars smoothly for statuslines.
• 🕐 Persistent Play History (:YT history): Stores recently played tracks so you can jump back or queue them later.

---

📦 Requirements

Before installing, ensure the following commands are available in your system path:

• Neovim 0.9+
• mpv (configured with Lua support)
• yt-dlp

---

🔧 Installation

Install using your favorite package manager:

lazy.nvim

{
  "sanjay-np/nvim-yt-player",
  dependencies = { "nvim-lualine/lualine.nvim" }, -- optional, for statusline component
  config = function()
    require("yt-player").setup({
      -- your configuration options here (see Configuration section)
    })
  end,
}

packer.nvim

use {
  "sanjay-np/nvim-yt-player",
  requires = { "nvim-lualine/lualine.nvim" }, -- optional
  config = function()
    require("yt-player").setup()
  end,
}

---

🚀 Quick Start

1. Start playing a URL immediately:

   :YT play https://www.youtube.com/watch?v=dQw4w9WgXcQ

2. Search and select tracks interactively:

   :YT search lofi hip hop

   In the search picker window:
   • <CR> (Enter): Play selected track (replaces active playlist)
   • a / A / <C-a>: Append selected track to the active queue
   • s: Save selected track to a Local Playlist
   • gg: Jump to first result
   • G: Jump to last result
   • i: Re-enter insert mode to refine your query
   • q / <Esc>: Close the picker

---

📋 Command Reference

All functions are available under the master command :YT with rich autocomplete (press <Tab>!).

Subcommand	Description
:YT play [url]	Play a URL/search query, or resume playback
:YT pause	Pause playback
:YT toggle	Toggle play/pause
:YT stop	Stop playback entirely
:YT next / :YT prev	Skip to next or previous track
:YT seek <seconds>	Seek to an absolute position (e.g. :YT seek 90 jumps to 1m 30s)
:YT seek_rel <±seconds>	Seek relatively (e.g. :YT seek_rel -10 seeks back 10 seconds)
:YT volume <0-100>	Set playback volume
:YT vol_up / :YT vol_down	Increase/decrease volume by 5%
:YT mute	Toggle playback mute state
:YT speed [value]	Adjust speed absolutely or relatively (Forms listed below)
:YT player	Toggle the premium player side-panel
:YT mini	Toggle the premium player floating window
:YT search [query]	Open the interactive search picker
:YT queue <url>	Append a track to the active queue
:YT queue_playlist <url>	Parse and append all tracks from a YouTube playlist URL
:YT queue_edit	Open the interactive queue editor
:YT playlists	Open the split-pane local playlist manager
:YT radio	Toggle autoplay radio mode (ON by default)
:YT history	Open the persistent play history picker
:YT history_clear	Clear play history
:YT resume	Resume the last persistent playback session

Playback Speed Control Forms

• :YT speed — Display current speed in a notification
• :YT speed 1.25 — Set absolute speed (supports values between 0.25 and 3.0)
• :YT speed up / down — Adjust speed by +0.25 / -0.25
• :YT speed +0.5 / -0.5 — Adjust speed by a custom offset

---

🎛️ Interactive Player Controls

When either the side-panel (:YT player) or floating window (:YT mini) is focused, you can control playback instantly using the following keymaps:

Keymap	Action
p / s / t	Play / Pause / Toggle
n / b	Next / Previous track
m	Mute toggle
+ / -	Volume ±5%
> / <	Speed ±0.25x
l / h	Seek ±5s (relative)
L / H	Seek ±30s (relative)
0 to 9	Seek to absolute percentage (0% to 90% of track)
G	Seek to 100% (ends track)
R	Cycle Repeat Mode (Track 🔂 ➔ Playlist 🔁 ➔ Off)
r	Toggle Autoplay Radio Mode
q / <Esc>	Close player window

---

⚙️ Configuration

Override defaults by passing options into setup():

require("yt-player").setup({
  statusline = {
    enabled = true,
    format = "{icon} {title} - {artist} [{position}/{duration}]",
    icon_playing = "▶",
    icon_paused = "⏸",
    truncate_title = 30,
    progress_width = 10,
  },

  search = {
    limit = 10, -- default number of results returned per search query
  },

  notifications = {
    enabled = true,
    notify_on_track_change = true, -- notify when a new song starts playing
  },

  player = {
    queue_display_limit = 5, -- number of upcoming tracks to show in the player layout
  },

  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, -- set to false to disable autoplay radio by default
    limit = 5,      -- number of related tracks to fetch at a time
  },
  
  sponsorblock = false, -- set to true to automatically skip YouTube sponsor segments
})

Statusline Customization

Use these placeholders to customize your statusline:

• {icon} — Play/Pause status icon (▶ / ⏸)
• {title} — Current track title
• {artist} — Channel / Uploader name
• {position} — Current playback position (e.g. 2:45)
• {duration} — Total track duration (e.g. 4:10)
• {progress} — Interactive progress bar (e.g. ▓▓▓░░░░░░░)
• {volume} — Volume percentage
• {speed} — Speed multiplier (e.g. 1.25x)
• {radio} — Autoplay radio status icon (renders 📻 when enabled)

Lualine Integration

Add yt-player directly to your lualine configuration sections:

require("lualine").setup({
  sections = {
    lualine_x = { "yt-player" }
  }
})

---

🏗️ Architecture

Neovim (Lua) ── UNIX Socket ──➔ mpv ──➔ yt-dlp ──➔ YouTube Stream

The plugin spawns a headless, detached background mpv process with IPC enabled. Multiple Neovim instances safely share the same mpv process via standard client process registration. The socket is automatically cleaned up when the last client closes.

---

🔧 Troubleshooting

• No Audio? Check that both mpv and yt-dlp are functioning correctly on your system by playing a URL directly:

  mpv --no-video "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

• Outdated yt-dlp? If YouTube streams fail to parse, update yt-dlp to get the latest decoders:

  yt-dlp -U

• Warning: mpv exited? Ensure mpv is compiled with Lua support. Most native distribution package managers compile it with Lua support by default.
• Searching Fails? Ensure Neovim has internet access and your geographic region is not blocked or rate-limited by YouTube's API filters.

---

❓ FAQ

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 control the same audio?
A: Yes! A shared client registry coordinates instances. When you start audio in one instance, others can view the statusline or control the active player.

---

📄 License

Distributed under the MIT License.