rust / ratatui / mpv / yt-dlp / lua v1.x / gpl-2.0

You name it, we stream it.

rs-pug is a blazing fast terminal music player built in Rust on mpv, yt-dlp and ratatui. It streams and downloads from YouTube and SoundCloud, pulls tracks from a self hosted Sonum server, manages a local library and playlists, and extends with Lua plugins, all without leaving the terminal.

$ rs-pug --help
rs-pug music player

Usage: rs-pug [OPTIONS]

Options:
  -s, --source <SOURCE>  Search source: youtube, soundcloud,
                         sonum, or a custom source name
      --play <PLAY>
      --toggle-pause
      --next
      --prev
      --debug
      --validate         Validate config.toml and exit
  -h, --help             Print help
  -V, --version          Print version

$ cargo install rs-pug

requires: mpv. recommended: yt-dlp for streaming. mpris2 works out of the box, no mpv-mpris needed. linux, termux and wsl2.

[ github ] [ usage guide ] [ plugin api ] [ discord ]

quickstart.sh sh

# install deps, then the player
sudo *your package manager* mpv yt-dlp
cargo install rs-pug

# run, validate config, pick a source
rs-pug
rs-pug --validate
rs-pug --source sonum

discover and queue

Minimal look

features

Straight from README.md. One interface for streaming and local files, with queue, library and plugin control.

youtube + soundcloud + sonum

Search and stream from YouTube, SoundCloud or self hosted Sonum, or play local files.

queue with bulk add

Multiselect with b, Enter queues marked songs in order. Marks track songs, not rows.

sqlite library

Playlists and library backed by SQLite at pug.db, with auto migration from legacy JSON.

smart queue + playlist

Finds similar tracks to keep music flowing, plus auto Smart Playlist of most played and recent.

fft visualizer

Real time spectrum with synthetic fallback. Ctrl+V switches to parec or pw-cat capture.

minimal mode

Shift+Z leaves pixelated cover art, title, thin FFT strip and progress. Cover tinted background.

10-band eq

Graphic EQ with savable presets in eqpresets dir. Adjust gain -12 to +12 dB per band.

remappable keys

Full remap incl. modifiers and sequences like g g. Options tab edits core playback keys.

mpris2 built in

Native in process MPRIS2 daemon. Set mpris_enabled to false to stay off the session bus.

lua scripting

Lua 5.4 plugins for keys, live panels, tabs and layout. Hot reload on file save. See plugins page.

command palette + ipc

Fuzzy palette on : for every action. IPC flags drive a running instance from waybar or hotkeys.

themes + hot reload

Built in dark, light, nord, gruvbox, mono plus custom JSON. Config and theme apply live.

requirements

Install once, then rs-pug stays out of your way.

mpv required for playback. yt-dlp recommended, without it streaming is off but local works. Use latest yt-dlp and mpv before filing bugs.

keys

Daily core. Full table in usage. Remap in config.toml under [keybinds].

key	action
`1-5`	discover / albums / library / local / options
`j / k`	move down / up
`/`	search
`enter`	play, or queue marked songs
`space`	pause / resume
`n / p`	next / previous
`b`	mark for bulk queue
`:`	command palette
`?`	command reference
`shift+z`	minimal mode
`q`	quit

lua in 10 lines

Drop .lua files into ~/.config/rs-pug/plugins. Full hooks in plugins.

plugins/quick_seek.lua lua 5.4

plugin = {}
function plugin.on_key(key, state)
  if key == "char:]" then
    return { consume = true,
      core_actions = { { type = "seek", seconds = 15 } } }
  end
end
return plugin

install

01 / deps

mpv + yt-dlp

sudo pacman -S mpv yt-dlp. Optional parec or pw-cat for real FFT.

02 / player

cargo install rs-pug

Or clone and cargo build --release. crates.io maintained, AUR seeks maintainer.

03 / run

rs-pug

Scans music-local by default. Add dirs in Options. Config hot reloads.

Tested on Linux and Termux. WSL2 should work. Local scan root: ~/.config/rs-pug/music-local. DB: pug.db. Presets: eqpresets. Themes: themes.