docs / usage

Usage guide

Everything that did not fit on the landing page. Config file is ~/.config/rs-pug/config.toml and it hot reloads. Sonum client config needs a restart.

keybinds

Remapping keys

Rebind playback and view toggles in config.toml. Modifiers use C for Ctrl, M for Alt, S for Shift. Sequences use a space, for example g g with 1.5s window.

[keybinds]
next = "n"
prev = "p"
mute = "m"
repeat = "r"
shuffle = "z"
seek_back = "["
seek_forward = "]"
fft_toggle = "C-v"
minimal_toggle = "S-Z"

Icons use Nerd Fonts glyphs. If your terminal lacks them, set icons to false under general or run icons from the palette for ASCII fallback.

queue

Multi-select bulk queue

sound

Equalizer and visualizer

focus

Minimal mode

Shift+Z hides tabs, lists and labels, leaving pixelated cover art as terminal halfblocks, title, thin FFT strip and progress. Real embedded art for local files, stream thumbnails for YouTube and SoundCloud. Allowed keys: Shift+Z or Esc to leave, Space pause, n and p skip, arrows seek, 9 and 0 volume, : palette, ? help, q quit.

[general]
image_background = true  # tint bg from cover hues

Toggle Image background row in Options or from palette. Blends three most vivid cover hues into a dark readable vertical gradient.

cli

CLI and IPC for status bars

Flags control a running instance over a Unix socket. Useful for i3status, waybar or global hotkeys. If no instance runs, you get an error instead of a new player.

rs-pug --toggle-pause
rs-pug --next
rs-pug --prev
rs-pug --play ~/music/mix.flac

rs-pug --debug    # log to rs-pug.log
rs-pug --validate # check config, exit 1 on warns
rs-pug --source sonum

look

Themes and storage

Built in dark, light, nord, gruvbox and mono. Set theme under general. Custom themes are JSON files in ~/.config/rs-pug/themes with r,g,b triples. All nine base colors required, spectrum optional.

{
  "text": [255, 255, 255],
  "primary": [255, 0, 255],
  "spectrum": [[255, 0, 255], [0, 255, 255]]
}

Local scan roots default to ~/.config/rs-pug/music-local, add more in Options. Data in SQLite pug.db with auto JSON migration. Import from import_playlist.json, export to exports folder. Smart Playlist refreshes each boot with most played, recent and unheard tracks, cap near 50. Disable with smart_playlists_enabled = false.

server

Sonum self hosted server

Sonum is a small Rust Axum server that scans a folder and serves tracks, lyrics and art over HTTP JSON with auto rescan. Point rs-pug at it, then set Search source to Sonum in Options.

# ~/.config/rs-pug/sonumclient.toml, restart after edit
host = "127.0.0.1"
port = 8420
# api_token = "your-secret-token"

Search hits GET tracks with query and limit, playback streams from tracks id stream endpoint, art from tracks id art. Albums view groups client side, so raise limit for large libraries. Token sent as Bearer when set.

sources

Custom search sources

Besides YouTube, SoundCloud and Sonum you can add ytdlp prefixes or command scripts. They join Options cycle and --source. Hot reload applies.

[search]
source = "youtube"
[[search.custom_sources]]
name = "YouTube (newest)"
type = "ytdlp"
prefix = "ytsearchdate"
[[search.custom_sources]]
name = "Audius"
type = "command"
command = ["/home/you/.config/rs-pug/scripts/audius-search.py", "{query}", "{limit}"]

Command scripts run directly without shell and must print a JSON array with id, title, webpage_url plus optional uploader and duration seconds. Limit stdout to 8 MiB, non zero exit or timeout shows a named error. Names match case insensitive, duplicates or built in clashes skipped with warning. Test prefixes first with yt-dlp flat playlist dump. Only trust scripts from sources you trust, they run with your user rights.

install

Install checklist