Music player in POSIX-sh interfacing mpv from the shell + extras/goodies [^install] 🚀.
A fork of lwillets/mpvc evolving on its own adding features like: improved CLI, TUI, FZF, WEB, EQ, & play Invidious, YouTube & streaming services. For more on the features of this fork check: Git QuickStart, Wiki, LogBook & Casts.
⏩ Skip directly to Installation to try mpvc!
mpvc is a collection of POSIX shell scripts:
For more details on how to use the above tools have a look at the Git QuickStart Guide, LogBook. In addition, the casts/ directory to shows some screencasts of mpvc in action.
Required:
mpv
socat
: is preferred due to the differing implementations of netcat
across UNIXes.awk
: a sane version of awk
for the same reason (gawk
works)Recommended extras:
curl
fzf
jq
notify-send
yt-dlp
Installing is just a matter of fetching the scripts either via Git/Curl/etc., scripts can be used directly from the repo, the mpvc-installer
bit is just there for easiness, to fetch & link them into your BINDIR=~/bin/
that mpvc-installer does by default.
The easiest for a onetime install is the Manual, however for @latest version a Git install is recommended.
Check for missing dependencies/requirements using mpvc-installer check-reqs
.
curl -LO https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer \
&& BINDIR=$HOME/bin sh ./mpvc-installer fetch-user
Below is a Quick Start guide showcasing mpvc git install and usage.
This does git clone, and symlinks the mpvc scripts to BINDIR
(default ~/bin
), so updating becomes a matter of just running git pull
.
# fetch a local copy of the github repo
git clone https://github.com/lwilletts/mpvc/
# use extras/mpvc-installer: just copy/link to BINDIR=$HOME/bin (by default)
(cd mpvc; extras/mpvc-installer link-user)
(cd mpvc; extras/mpvc-installer check-reqs)
# use mpvc to add/load/save media files or online YT URLs
mpvc add /path/to/your/*.mp3 # or your URLs
find . -type f -name | mpvc load
mpvc save my-playlist
# use mpvc stash to store/recover current mpv state (see the logbook for more)
mpvc stash ls
mpvc stash push current
mpvc stash apply current
# use mpvc-fzf to manage mpvc stash (see mpvc-fzf -h for more)
mpvc-fzf -a
# use mpvc-fzf to search and play youtube media
mpvc-fzf -p 'kupla mirage'
# use mpvc-fzf to browse & play lofi girl music
mpvc-fzf -b https://lofigirl.com/wp-content/uploads/2023/06
# use mpvc-fzf to manage the playlist
mpvc-fzf -f
# use mpvc-tui to start the tui + desktop notifications
mpvc-tui -T
For more check the LogBook (remeber your best chance is to try, play, and have fun).
Debian (and APT derivatives such as Ubuntu):
apt install mpv gawk curl socat fzf rlwrap jq libnotify-bin
Arch (and derivatives):
pacaur -y mpvc-git
pacman -Sy mpv gawk curl socat fzf rlwrap jq libnotify
BSD (and pkg(1) based derivatives as FreeBSD, see FAQ):
pkg install -y mpv curl socat fzf rlwrap jq libnotify # gawk gsed
MacOS (and brew(1) based derivatives see FAQ):
brew install mpv curl socat fzf rlwrap jq libnotify yt-dlp # gawk gnu-sed
emerge mpvc
nix-env -i mpvc
usage: mpvc opts # @version v1.5 (c) gmt4 https://github.com/gmt4/mpvc
-a | --add : Add media to playlist (see --load for stdin).
-s | --stop : Always stop playback.
-P | --play : Always start playback.
-p | --toggle : Toggle playback.
| --next : Jump to next entry in the playlist
| --prev : Jump to previous entry in the playlist
-i | --playlist : Print filenames of tracks to fit within terminal.
-I | --fullplaylist : Print all filenames of tracks in current playlist.
-v | --vol : Increase/decrease volume relative to current volume.
-h | --help : Prints the short help.
-H | --long-help : Prints the long help.
*tips: If unsure about where to begin, have a look at https://gmt4.github.io/mpvc
usage: mpvc-tui opts # @version v1.5 (c) gmt4 https://github.com/gmt4/mpvc
-d|dir : Set the WD to the media directory given as argument
-n|notify : Desktop notification using notify on mpvc events (notify-send*)
-s|suggest : Suggest a random media to play based on previous media played
-S|scrobler: Starts the mpvc-tui scrobbler
-H|history : Starts the mpvc-tui history
-t|tui : Starts the mpvc-tui to manage the mpv playlist (rlwrap*)
-T|Tui : Combo that starts mpvc-tui -t -n, and adds media given as args
-x|launch : Starts mpvc-tui in a new xterm ($MPVC_TUI_TERM) # combine with <opts>
-v|version : Prints the mpvc-tui version.
*tips: If unsure about where to begin, start with: mpvc-tui -d /path/to/media/ -T
usage: mpvc-fzf opts # @version v1.5 (c) gmt4 https://github.com/gmt4/mpvc
-b|browse : Browse the provided ytdl-archive URL with fzf
-c|chapters : Start fzf to manage the current mpv chapterlist
-d|dir : Set the WD to the media directory given as argument
-e|eqz : Start fzf to manage the equalizer settings
-f|playlist : Start fzf to manage the current mpv playist
-g|fetch : Fetch the given YT URL, and store locally
-G|Fetch : Search on Invidious, fetch, and store locally
-i|lyrics : Search given media lyrics on Invidious
-k|dplay : Search & play DuckDuckGo videos
-K|dsearch : Search DuckDuckGo videos
-l|local : Search & play local media
-s|search : Search on Invidious
-p|splay : Search & play media found using Invidious
-y|related : Search related media on Invidious
-Y|Related : Search & play related media using Invidious
-x|launch : Starts mpvc-fzf in a new xterm (config $MPVC_TERM) [combine -x with other opts]
-v|version : Prints the mpvc-fzf version.
somafm : Search & play SomaFM channels
radioapi : Search & play Radio-Browser API channels
*tips: If unsure about where to begin, start: mpvc-fzf -p 'kupla mirage'
Like any piece of software, mpvc is not perfect:
mpvc-installer check-reqs
.Check out the Issue Tracker for further improvements to be made.
[^install]: Skip directly to Installation to try mpvc