Home

Awesome

GitHub GitHub Release Date GitHub release (latest by date) GitHub top language GitHub lines of Code

🎧 mpvc

Music player in POSIX-sh interfacing mpv from the shell + extras/goodies 1 🚀.

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!

<details open> <summary>mpvc-tui -T: running the mpvc TUI <i>(click to view screenshot)</i></summary>

mpvc-tui -T screenshot

</details> <details> <summary>mpvc-fzf -f: running with fzf to manage the playlist <i>(click to view screenshot)</i></summary>

mpvc-fzf screenshot

</details> <details> <summary>mpvc-tui -n: running with mpvc-fzf and desktop notifications on the upper-right corner <i>(click to view screenshot)</i></summary>

mpvc tui+fzf+notifications screenshot

</details>

▶️ Overview 1

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.

Requirements

Required:

Recommended extras:

Installation

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.

Manual

curl -LO https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer \
  && BINDIR=$HOME/bin sh ./mpvc-installer fetch-user

Git

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

Debian (and APT derivatives such as Ubuntu):

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

Arch mpvc-git

Arch (and derivatives):

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

BSD

BSD (and pkg(1) based derivatives as FreeBSD, see FAQ):

pkg install -y mpv curl socat fzf rlwrap jq libnotify # gawk gsed

MacOS

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

brew install mpv curl socat fzf rlwrap jq libnotify yt-dlp # gawk gnu-sed

Gentoo mpvc

emerge mpvc

Nix mpvc

nix-env -i mpvc

Usage

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

mpvc-tui

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

mpvc-fzf

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'

Limitations

Like any piece of software, mpvc is not perfect:

Check out the Issue Tracker for further improvements to be made.

Footnotes

  1. Skip directly to Installation to try mpvc 2