sanjay-np/nvim-yt-player

github

media

6

0

0

1

CREATED

2026-02-13

UPDATED

2026-02-27

---

🎵 nvim-yt-player

Play YouTube audio directly from Neovim using mpv + yt-dlp. No browser, no Node.js — just pure Lua talking to mpv over a local IPC socket.

✨ Features

• ▶️ Seamless Playback: Play any YouTube URL or search query instantly via a simple Neovim command.
• 🏗️ Zero-Dependency Backend: Runs entirely on pure Lua via a local UNIX socket. No browser extension, no Node.js requirement, no external bloated servers. Just mpv and yt-dlp.
• 🎨 Premium ASCII Visualizer UI: Implements a dedicated (:YT ui) animated player layout featuring a custom bounding-box grid, bouncy audio visualizer, interactive progress slidebar, and built-in queue alignment.
• 🔍 Interactive Search Picker: Search YouTube directly inside Neovim and preview video durations/channels in a native floating window buffer.
• 📝 Interactive Queue Editor: View and modify your active queue in real-time. Use dd to remove tracks or J/K to reorder them (:YT queue_edit).
• 🎵 Endless Queuing & Playlists: Instantly append streams or search results to your queue. You can even pass a full YouTube Playlist URL to rapidly ingest 100+ tracks (:YT queue_playlist).
• ⏩ SponsorBlock Integration: Natively caches and injects an mpv script to automatically skip sponsor and intro segments in YouTube videos (enable via config).
• 🎛️ Total Control: Full mappings to Play/Pause, Seek, Skip, Mute, Volume, and manipulate Playback Speed (0.25x – 3.0x).
• 📊 Statusline Integration: Formats progress bars smoothly for plugins like lualine
• 🔔 Asynchronous Stability: Stream fetching runs in the background. Neovim will never freeze or block while caching metadata or traversing tracks.

📦 Requirements

🔧 Installation

lazy.nvim

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

packer.nvim

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

🚀 Quick Start

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

Or search directly from Neovim (opens in a custom interactive floating window!):

:YT search lofi hip hop

In the interactive search window:

• <CR> (Enter): Play result (replaces current track)
• <C-a> (Ctrl+A) or a / A (in Normal mode): Append result to the queue

📋 Commands

All functionality is grouped under a single :YT command with auto-completion (press Tab!).

🎛️ Floating Player

:YTInfo opens an interactive floating window:

⚙️ Configuration

All options with defaults:

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

  -- Search settings
  search = {
    limit = 10, -- number of results to fetch
  },

  notifications = {
    enabled = true,
    notify_on_track_change = true,
    notify_on_command = false,
  },

  player = {
    queue_display_limit = 5, -- Number of upcoming tracks to show in the `:YT ui` side-panel
  },

  keymaps = {
    enabled = false,
    prefix = "<leader>y",
  },
  
  sponsorblock = false, -- Set to true to automatically skip embedded sponsor segments
})

Statusline Placeholders

{icon} {title} {artist} {album} {position} {duration} {volume} {progress} {speed}

Example output: ▶ Song Name ▓▓▓▓░░░░░░ [2:30/5:00] 1.5x

📊 Lualine Integration

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

🏗️ Architecture

Neovim (Lua) ←─ IPC pipe ─→ mpv ←── yt-dlp ←── YouTube

The plugin spawns a headless mpv --no-video process and communicates through a UNIX domain socket using mpv's JSON IPC protocol. yt-dlp is used by mpv internally to resolve YouTube URLs into streamable media.

🔧 Troubleshooting

• No audio: Run mpv --no-video <youtube-url> directly to verify mpv + yt-dlp work
• yt-dlp outdated: Run yt-dlp -U to update
• Port conflict: The IPC socket path is /tmp/nvim-yt-player-ipc-<pid>, unique per Neovim instance

📄 License

MIT