https://github.com/sanjay-np/nvim-yt-player

nvim-yt-player is a Neovim plugin for playing YouTube audio directly from Neovim using mpv + yt-dlp via IPC socket. Features include a premium ASCII visualizer UI, interactive search picker, queue editor, SponsorBlock integration, and full playback controls.
https://github.com/sanjay-np/nvim-yt-player

mpv music nvim-plugin player video-player youtube yt-dlp

Last synced: 28 days ago
JSON representation

nvim-yt-player is a Neovim plugin for playing YouTube audio directly from Neovim using mpv + yt-dlp via IPC socket. Features include a premium ASCII visualizer UI, interactive search picker, queue editor, SponsorBlock integration, and full playback controls.

• Host: GitHub
• URL: https://github.com/sanjay-np/nvim-yt-player
• Owner: sanjay-np
• License: mit
• Created: 2026-02-13T17:06:59.000Z (3 months ago)
• Default Branch: master
• Last Pushed: 2026-03-02T03:15:08.000Z (about 2 months ago)
• Last Synced: 2026-03-02T07:25:09.254Z (about 2 months ago)
• Topics: mpv, music, nvim-plugin, player, video-player, youtube, yt-dlp
• Language: Lua
• Homepage:
• Size: 59.6 KB
• Stars: 11
• Watchers: 0
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome-neovim - sanjay-np/nvim-yt-player - Play YouTube audio using `mpv` and `yt-dlp` via IPC socket. (Media / Cursorline)
• awesome-neovim-sorted - sanjay-np/nvim-yt-player - yt-player is a Neovim plugin for playing YouTube audio directly from Neovim using mpv + yt-dlp via IPC socket. Features include a premium ASCII visualizer UI, interactive search picker, queue editor, SponsorBlock integration, and full playback controls. | (Media)

README

          
# 🎵 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

| Dependency | Install |

|------------|---------|

| [Neovim](https://neovim.io/) 0.9+ | — |

| [mpv](https://mpv.io/) | `sudo apt install mpv` or `brew install mpv` |

| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | `pip install yt-dlp` or [binary release](https://github.com/yt-dlp/yt-dlp/releases) |

## 🔧 Installation

### lazy.nvim

```lua

{

  "sanjay-np/nvim-yt-player",

  config = function()

    require("yt-player").setup()

  end,

}

```

### packer.nvim

```lua

use {

  "sanjay-np/nvim-yt-player",

  config = function()

    require("yt-player").setup()

  end,

}

```

## 🚀 Quick Start

```vim

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

```

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

```vim

:YT search lofi hip hop

```

In the interactive search window:

- `` (Enter): Play result (replaces current track)

- `` (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`!).

| Command | Description |

|---------|-------------|

| `:YT play [url]` | Play URL / search, or resume |

| `:YT search [query]` | 🔍 Search YouTube and pick a result |

| `:YT queue ` | Append a single URL to the playlist |

| `:YT queue_playlist ` | Fetch and append an entire playlist |

| `:YT queue_edit` | Open interactive queue editor |

| `:YT pause` | Pause |

| `:YT toggle` | Toggle play/pause |

| `:YT stop` | Stop playback |

| `:YT next` / `:YT prev` | Next / previous track |

| `:YT seek ` | Seek to absolute position |

| `:YT seek_rel <±sec>` | Seek relative |

| `:YT volume <0-100>` | Set volume |

| `:YT vol_up` / `:YT vol_down` | Volume ±5 |

| `:YT mute` | Toggle mute |

| `:YT speed ` | Set speed (0.25–3.0) |

| `:YT speed_up` / `:YT speed_down` | Speed ±0.25 |

| `:YT shuffle` / `:YT repeat_toggle`| Shuffle / repeat |

| `:YT ui` | Toggle the dedicated player side-panel |

| `:YT info` | Toggle the floating player window |

## 🎛️ Floating Player

`:YTInfo` opens an interactive floating window:

| Key | Action |

|-----|--------|

| `p` / `s` / `t` | Play / Pause / Toggle |

| `n` / `b` | Next / Previous |

| `m` | Mute |

| `>` / `<` | Speed ±0.25 |

| `+` / `-` | Volume ±5 |

| `l` / `h` | Seek ±5s |

| `L` / `H` | Seek ±30s |

| `q` / `` | Close |

## ⚙️ Configuration

All options with defaults:

```lua

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 = "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

```lua

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 ` 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-`, unique per Neovim instance

## 📄 License

MIT