🎧 mpvc

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 QuickStart, LogBook & Casts.

⏩ Skip directly to Installation to try mpvc!

mpvc-fzf running on macOS (click to view screenshot)

mpvc-tui -T: running the mpvc TUI (with albumart) (click to view screenshot)

mpvc-tui -T: running the mpvc TUI (click to view screenshot)

mpvc-fzf -f: running with fzf to manage the playlist (click to view screenshot)

mpvc-tui -n: running with mpvc-fzf and desktop notifications on the upper-right corner (click to view screenshot)

▶️ Overview ¹

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: a hack to remotely control mpvc from web (handy on mobile)
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 QuickStart Guide, LogBook. In addition, the casts/ directory to shows some screencasts of mpvc in action.

Requirements

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

Warning

Note tools must be up to date, in special yt-dlp to play streaming services, run mpvc-installer check-reqs|config-user to check and update.

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 @latest version a Git install is recommended. Remember to check your installation for missing dependencies/requirements using mpvc-installer check-reqs, and, if you encounter any issue file an Issue.

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)
 (cd mpvc; extras/mpvc-installer config-user)
 # check ~/.config/mpvc/mpvc.conf to suit your needs

 # Running mpvc for first time can show some warnings:
 #   Warning: .config/mpvc/mpvc.conf not found, see docs/mpvc.conf
 # mpvc-installer config-user sets the default user config
 mpvc-installer config-user

 # Another common warning is when running mpvc:
 #   mpvc: Error: No files added to mpvsocket0
 # lets fix that by adding some music files to play
 mpvc

 # 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 (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 (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).

Curl

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

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

Debian

Debian (and APT derivatives such as Ubuntu):

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

Arch mpvc-git

Arch (and derivatives):

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

BSD

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

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

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

Gentoo mpvc

emerge mpvc

Nix mpvc

nix-env -i mpvc

Configuration

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.

QuickConfig

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/

Documentation

Manuals

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

Logbook

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

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

Screencasts

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

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

FAQ

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

docs/FAQ.md

Usage

mpvc

usage: mpvc opts # @version v1.8 (c) gmt4 https://github.com/gmt4/mpvc
 -a | --add | add         : Add media to playlist (see --load for stdin).
 -r | --remove | rm       : Remove media by id from playlist (see searchrm for rm by title)
 -s | --stop | stop       : Always stop playback.
 -P | --play | play       : Always start playback.
 -p | --toggle            : Toggle playback.
      --repeat | repeat   : Loop the playlist.
      --single | single   : Loop a single file.
    | --next | next       : Jump to next entry in the playlist
    | --prev | 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 | vol         : Increase/decrease volume relative to current volume.
 -h | --help              : Prints the short help.
 -H | --help-long         : Prints the long help (tip: mpvc -H 2>&1 | less).

*tips: If unsure about where to begin, have a look at https://gmt4.github.io/mpvc

mpvc-tui

usage: mpvc-tui opts # @version v1.8 (c) gmt4 https://github.com/gmt4/mpvc
 -d|dir     : Set the WD to the media directory given as argument
 -h|help    : This help you are reading
 -H|history : Starts the mpvc-tui history
 -k|kill    : Stop the running mpvc-tui
 -n|notify  : Desktop notification using notify on mpvc events (notify-send*)
   |socket  : Set mpv socket [default: ].
 -s|suggest : Suggest a random media to play based on previous media played
 -S|scrobler: Starts the mpvc-tui scrobbler
 -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.8 (c) gmt4 https://github.com/gmt4/mpvc
  -a|stash      : Start fzf to manage mpvc stashes
  -b|browse     : Start fzf to manage the provided ytdl-archive URL
  -c|chapters   : Start fzf to manage the current mpv chapterlist
  -C|cache      : Search cache by URL for remote media and return local file
 -CC|cmds       : Search and run commands from stdin
  -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
  -I|Lyrics     : Search given media lyrics on DDG
  -k|dplay      : Search & play DuckDuckGo videos
  -K|dsearch    : Search DuckDuckGo videos
  -l|local      : Search & play local media at $1 (handy to pipe to m load)
  -q|quality    : Select and change yt-dlp video quality (ytdl-format)
  -r|explorer   : Shortcut to search local media at ytdl-archive/
  -s|search     : Search on Invidious
  -S|socket     : Set mpv socket [default: ].
 -SS|socklist   : Select and set the current mpv socket to operate
  -t|thumbnail  : Retrieve thumbnail_url from metadata of the current YT-URL
  -T|Thumbnail  : Display thumbnail_url from metadata of the provided YT-URL
  -p|splay      : Search & play media found using Invidious
  -u|url        : Search the given YT URL (supports vids,channels,playlist feeds)
  -U|Url        : Search & play the given YT URL
  -x|launch     : Starts mpvc-fzf in a new xterm (config $MPVC_TERM) [combine -x with other opts]
  -y|related    : Search related media on Invidious
  -Y|Related    : Search & play related media using Invidious
  -z|relatedo   : Search current media-title on Invidious and return related media
  -v|version    : Return the mpvc-fzf version.

    now        : Return a shareable URL to the "now listening" playlist
    lofi       : Search & play Lo-Fi channels
    somafm     : Search & play SomaFM channels
    radioapi   : Search & play Radio-Browser API channels
    ntsradio   : Search & play NTS-Radio API channels
    custom     : Search & play your custom feeds (channels, playlists, ...)
    custom-gen : Generate a template for your custom feeds (channels, playlists, ...)
    invid-list : List available Invidious instances (set MPVC_FZF_INVID_URL)

*tips: If unsure about where to begin, start: mpvc-fzf -p 'kupla mirage'

mpvc-installer

usage: mpvc-installer args # @version v1.8 (c) gmt4 https://github.com/gmt4/mpvc
  check-update   : Check for updates
  check-reqs     : Check for required packages
  config         : Fetch mpv config
  config-user    : Fetch mpv config to BINDIR=/home/user/bin
  config-sys     : Fetch mpv config to BINDIR=/usr/local/bin
  fetch-user     : Fetch to BINDIR=/home/user/bin
  link-user      : Symlink to BINDIR=/home/user/bin
  install:       : Install to BINDIR=/usr/local/bin
  uninstall:     : Uninstall from BINDIR=/usr/local/bin
  install-user   : Install to BINDIR=/home/user/bin (sets PREFIX=/home/user)
  install-sys    : Install to BINDIR=/usr/local/bin (sets PREFIX=/usr/local)
  uninstall-user : Uninstall from BINDIR=/home/user/bin (sets PREFIX=/home/user)
  uninstall-sys  : Uninstall from BINDIR=/usr/local/bin (sets PREFIX=/usr/local)
*tips: If unsure where to start, start with: mpvc-installer fetch-user

Footnotes

Skip directly to Installation to try mpvc ↩ ↩²

mpvc

🎧 mpvc

▶️ Overview ¹

Requirements

Installation

Git

Curl

Debian

Arch mpvc-git

BSD

MacOS

Gentoo mpvc

Nix mpvc

Configuration

QuickConfig

Documentation

Manuals

Logbook

Screencasts

FAQ

Usage

mpvc

mpvc-tui

mpvc-fzf

mpvc-installer

Footnotes

MTT-File-Manager-RUST

Macropad_4chord_MIDI

Oscillody

PicoAudio.js

mpvc

🎧 mpvc

▶️ Overview 1

Requirements

Installation

Git

Curl

Debian

Arch mpvc-git

BSD

MacOS

Gentoo mpvc

Nix mpvc

Configuration

QuickConfig

Documentation

Manuals

Logbook

Screencasts

FAQ

Usage

mpvc

mpvc-tui

mpvc-fzf

mpvc-installer

Footnotes

MTT-File-Manager-RUST

Macropad_4chord_MIDI

Oscillody

PicoAudio.js

search

▶️ Overview ¹