Neovim out of music players. Search, queue, listen — no browser, no ads, no nonsense.

rs-pug uses mpv + yt-dlp under the hood, with a terminal UI built on ratatui.

Features

• YouTube search and queue playback in TUI.
• Album search support (Albums tab).
• Smart Queue: Automatically find and play similar tracks.
• Local files playback with metadata support (Artist/Album/Title).
• Organized Local View: Switch between Flat and Organized (Artist -> Album -> Song) views.
• Playlist library: Create, delete, and manage your own playlists.
• 10-band equalizer with built-in and custom presets.
• Dynamic, reactive audio visualizer.
• Recently played history (saved to SQLite database).
• Playlist import/export from context menu (c).
• Theme switching: Multiple built-in themes + custom JSON themes.
• Mouse support: Scroll through lists and click tabs.
• Lua plugin system for extending functionality.
• MPRIS support: Media key and playerctl integration.

Dependencies

Required:

• mpv
• yt-dlp

Optional:

• mpv-mpris (for media key / playerctl support)

Installation

From AUR (Arch Linux)

yay -S rs-pug-git
# or
paru -S rs-pug-git

Manually

git clone https://github.com/JustRoccat/rs-pug
cd rs-pug
cargo build --release
./target/release/rs-pug

Keybinds

Navigation & Global

Playback

Tab Specific

• Library Tab:
  • a: Create new playlist.
  • x: Delete selected playlist (with confirmation).
  • e: Expand / Collapse playlist folders.
• Local Tab:
  • v: Toggle view mode (Flat vs Organized).
• Options Tab:
  • f: While focusing "EQ preset", press to save current EQ as a new preset.

Mouse Support

• Scroll Wheel: Scroll through search results, playlists, and the queue.
• Left Click: Click on tab icons at the top to switch between views.

Smart Queue

In the Options tab, you can trigger the Smart Queue. This feature analyzes the currently playing song and automatically finds similar tracks from the same uploader or with similar titles to keep the music flowing.

Customization

Themes

rs-pug comes with several built-in themes: dark (default), light, nord, gruvbox, and mono.

You can add your own themes by creating .json files in ~/.config/rs-pug/themes/.

Example mytheme.json:

{
  "text": [255, 255, 255],
  "dim": [100, 100, 100],
  "muted": [150, 150, 150],
  "info": [0, 255, 255],
  "warn": [255, 255, 0],
  "ok": [0, 255, 0],
  "primary": [255, 0, 255],
  "accent2": [200, 0, 200],
  "accent3": [100, 0, 100]
}

EQ Presets

Your custom EQ presets are stored as .json files in ~/.config/rs-pug/eqpresets/.

Local Music

By default, rs-pug scans ~/.config/rs-pug/music-local/. You can change this or add more directories in the Options tab. The app supports natural sorting and metadata extraction.

Playlists & Storage

Data is stored in a SQLite database at ~/.config/rs-pug/pug.db. Legacy JSON files are automatically migrated on first run.

• Import path: ~/.config/rs-pug/import_playlist.json
• Export path: ~/.config/rs-pug/exports/<playlist_name>.json

Plugins (Lua)

Drop Lua scripts into ~/.config/rs-pug/plugins/. They are loaded automatically and can react to keys, search queries, and playback events. See docs.md for the full API reference.

Configuration

Config file path: ~/.config/rs-pug/config.toml. The app also looks for rs-pug.toml or pug.toml in the current working directory.

Contributing

Plugin system is Lua-based. If you know Lua, example plugins / plugin PRs are very welcome.

BTW

Now you can see examples and you can download plugins, themes, eqpresets here: https://github.com/JustRoccat/all-rspug/

License

MIT