[ Intro | Reqs | Install | Config | Docs | Usage ]

Music player in POSIX-sh using mpv from the shell/fzf + extras/goodies ¹ 📡🛸🚀.

A fork of lwillets/mpvc evolving on its own adding features such as: improved interfaces to CLI, TUI, FZF, WEB, EQZ, & play streaming services as YouTube/Invidious, with a focus on being fully programmable/scriptable from the shell. For more on the features of this fork check: Git install, LogBook & Casts.

⏩ Skip directly to Installation to try mpvc!

mpvc is a collection of POSIX shell scripts:

• mpvc: provides the core CLI commands to control mpv
• extras/mpvc-tui: provides a console TUI, using mpvc underneath
• extras/mpvc-fzf: provides FZF integration to mpvc.
• extras/mpvc-web: web player to remotely control mpvc (a hack)
• extras/mpvc-web-browser: mpvc-web companion to browse media library (a hack)
• extras/mpvc-mpris: speaks MPRIS to control mpv player through key-bindings.
• extras/mpvc-equalizer: provides a basic mpv equalizer for the CLI.
• extras/mpvc-autopilot: automatic mpv start/stop based on presence.
• extras/mpvc-installer: provides an installer to install/update mpvc.

For more details on how to use the above tools have a look at the Git install guide and the LogBook. In addition, the casts/ directory to shows some screencasts of mpvc in action.

Required:

• sh: a POSIX compliant shell (/bin/sh works)
• mpv: the mpv media player (see https://mpv.io)
• socat: is preferred due to the differing implementations of netcat across UNIXes.
• awk: a sane version of awk for the same reason (GNU/BSD awk works)

Recommended extras:

• curl
• fzf
• jq
• notify-send
• yt-dlp
• cava

• Curl
• Git
• Debian
• Arch
• BSD
• MacOS
• Gentoo
• Nix

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 using Curl, however for the @latest and keeping always updated a Git install is recommended.

Fetch the mpvc-installer (written in POSIX-sh), and ensure it runs under a POSIX-sh SHELL

• Zen Install achieve inner peace of mind before piping to your shell.

curl -fsSLO https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer;
# take your time to review the mpvc-installer for peace-of-mind
BINDIR=$HOME/bin SHELL=/bin/sh $SHELL ./mpvc-installer quickstart

• YOLO Install fast, but you're trusting the pipe (curl|sh).

curl -fsSLO https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer \
  && SHELL=/bin/sh BINDIR=$HOME/bin sh ./mpvc-installer quickstart

Clone the git repo to receive quick development updates via git pull, then, use the mpvc-installer inside the repo:

 # 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
 (cd mpvc; BINDIR=~/bin/ extras/mpvc-installer quickstart-ln)

Once installed, you can start using mpvc, below are some examples to get started:

 # 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 '*.mp3' | mpvc load
 fzf | mpvc load # even better than the above
 mpvc save my-playlist

 # use mpvc stash to store/recover current mpv state
 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 (archive.org)
 mpvc-fzf -b https://archive.org/download/lofigirl-youtube/mp3/
 # use mpvc-fzf to randomly enqueue a few lofi tracks (see mpvc-fzf lofi)
 mpvc-fzf -B https://archive.org/download/lofigirl-youtube/mp3/ | shuf -n 128 | mpvc load
 # 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 (remember your best chance is to try, play, learn, and have fun).

Debian (and APT derivatives such as Ubuntu):

apt install mpv gawk curl socat fzf rlwrap jq libnotify-bin # cava

Arch (and derivatives):

pacaur -y mpvc-git
pacman -Sy mpv gawk curl socat fzf rlwrap jq libnotify # cava

BSD systems as OpenBSD and NetBSD using pkg_add(1) see FAQ:

pkg_add mpv curl socat fzf rlwrap jq libnotify # mpv-mpris cava python3

BSD systems as FreeBSD using pkg(1) see FAQ:

pkg install -y mpv curl socat fzf rlwrap jq libnotify # mpv-mpris cava python3

MacOS (and brew(1) based derivatives see FAQ):

brew install mpv curl socat fzf rlwrap jq libnotify yt-dlp # cava

emerge mpvc

nix-env -i mpvc

Running mpvc-installer config-user, just installs the default configuration files from config/ listed below under ~/.config/mpvc/, afterwards, check and adjust them to suit your needs.

• mpvc configuration is performed on config/mpvc.conf.

• mpv configuration is performed on config/mpv.conf.

• yt-dlp configuration is performed on config/yt-dlp.conf.

• shell aliases to type less config/bash_aliases.mpvc.

• $TERM configuration: A decent terminal with color/sixels support is recommended (256color/vt340), but outside of the scope of mpvc config.

For a quick config just copy/symlink docs/config/ to ~/.config/mpvc/

# either use `mpvc-installer config-user` or do the cp/symlink by hand
cd mpvc/
ln -f -s $PWD/docs/config/mpv.conf ~/.config/mpv/
ln -f -s $PWD/docs/config/mpvc.conf ~/.config/mpvc/
ln -f -s $PWD/docs/config/yt-dlp.conf ~/.config/mpvc/

• docs/man/ : For the mpvc(1) command read the mpvc manual page.

• https://mpv.io/manual/stable/ : For the mpv(1) command read the mpv reference manual.

• logbook : For the functionality specific of this fork your best aim is the logbook

The logbook (blog) is a companion of mpvc that covers mpvc usage & evolution:

• https://gmt4.github.io/mpvc/logbook.html

Have a look at the screencasts to watch mpvc in action.

• https://gmt4.github.io/mpvc/casts/

Check the FAQ for any questions left after reading the above docs.

• docs/FAQ.md

If you encounter a bug file an Issue.