ShellMusic

A terminal music player built on fzf and mpv, with a real-time progress bar, a VU meter driven by the actual audio level, and a fuzzy-searchable folder browser.

Features

• Fuzzy-searchable browser for nested folders of music, powered by fzf
• Now-playing screen with a real progress bar, remaining time, and a VU meter fed by mpv's own audio filter (not a fake animation)
• Shuffle toggle (Ctrl-S in the browser, r/u while playing) that live-updates the header
• Bigger, configurable volume steps instead of mpv's tiny 2% default
• Terminal window title follows whatever's currently playing
• Follows symlinks, so albums or playlists linked into your music folder show up like any other

Dependencies

• fzf
• mpv
• python3 (used for the now-playing display, no extra packages needed)

On Debian/Ubuntu:

sudo apt install fzf mpv python3

Usage

git clone https://github.com/AFaria20s/shellmusic.git
cd shellmusic

Install as a command

sudo make install

This installs to /usr/local/bin/shellmusic, so you can run shellmusic from anywhere. To install without sudo, put it under your home folder instead:

make install PREFIX=$HOME/.local

Make sure ~/.local/bin is on your PATH (the installer tells you if it isn't). To remove it later:

make uninstall            # or: make uninstall PREFIX=$HOME/.local

make check-deps checks that fzf, mpv and python3 are all present, and make help lists every target.

Run without installing

chmod +x shellmusic.sh
./shellmusic.sh

Point it at a folder, or leave it to default to ~/Music:

MUSIC_DIR=~/Downloads/music ./shellmusic.sh

Keybindings

Browser

Key	Action
Tab / ↑ ↓	Navigate
Enter	Open folder / play track
Ctrl-S	Toggle shuffle
Esc	Back / quit

Now playing

Key	Action
space	Play / pause
← →	Seek 5s
> <	Next / previous track
9 0	Volume down / up
r / u	Shuffle / unshuffle
q	Back to menu

Environment variables

Variable	Default	Description
MUSIC_DIR	~/Music	Folder to browse
VOLUME_STEP	10	Percent the volume changes per 9/0 press
MUSIC_ROWS	40	Terminal rows requested on start
MUSIC_COLS	110	Terminal columns requested on start
MUSIC_NO_RESIZE	unset	Set to 1 to skip the automatic terminal resize

Platform

Built for Linux, and tested there. It relies on GNU-specific behavior (find -L, sed -r, mktemp -d with a template) that isn't guaranteed to work as-is on macOS's BSD tools.

License

MIT, see LICENSE.