@gmt4 mpvc 🎧

Star Follow @gmt4 Download Watch Issue Sponsor

⠀⠀⠀⠀⠀⠀⠀⢀⣤⠖⠂⠉⠉⠉⠀⠒⠤⣀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⠀⣶⡟⢀⣴⣶⣿⣾⣶⣶⣄⡀⠈⠑⢤⡀⠀⠀
⠀⠀⠀⡴⣫⣼⡿⣴⡟⠛⠉⠉⠛⠛⠿⣿⣿⣷⣦⡀⠙⢄⠀
⠀⠀⣼⢁⣟⡟⣷⠁⠀⠀⠀⠀⠀⠀⠀⠀⠙⢿⣿⣷⣆⠈⢣
⠀⢰⣿⢼⣿⣷⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠹⣿⣿⡆⠀⢱⠀⠀
⠀⢸⡵⣾⣇⣸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣧⠀⠀⢧⠀⠀⠀
⠀⠘⣴⣿⢯⡏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠹⡿⠛⠉⠹⡆⠀⠀
⢀⣼⣿⣧⠟⠁⢀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢯⣴⣶⣴⡇⠀⠀⠀
⢸⣿⣼⣿⣋⣉⠀⠀⠀⠈⠙⠦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿⣷⣷⡀⠀⠀
⢸⠁⠊⣿⠛⢛⢟⣦⡀⠀⠀⠀⠈⢆⠀⠀⠀⠀⢀⠔⣨⣶⡜⠂⠈⠽⣧⡀⠀
⠸⣶⣾⡯⠤⢄⡀⠵⢿⣦⡀⠀⠀⠀⡷⡄⠀⡰⢁⣾⣿⣿⣿⠀⠀⠀⣿⡹⡄
⠀⣿⣡⠦⢄⡀⠈⠳⣬⣹⣿⣆⠀⠀⢉⠻⣴⠇⣾⣿⡟⢻⠁⠀⠀⠀⣿⠁⡇
⠀⣿⡭⡀⠀⠈⠲⣦⣸⣿⣿⣿⣧⣀⠈⡔⣜⣴⣿⡟⢀⡎⡈⠀⠀⢰⡿⢠⣷
⠀⢸⣿⣄⣒⡀⡀⣿⣷⡿⣿⢿⣿⣷⡰⡸⣯⣏⣿⡷⢋⣼⣁⡢⢠⠟⠀⣼⣿
⠀⠀⠻⣷⣈⣁⣮⢻⢸⡇⢨⣿⣿⣿⣷⢶⣿⣏⣩⣶⣿⣿⣿⣿⡯⣤⣴⣿⠃
⠀⠀⠀⠘⠿⣿⣿⣽⣽⣷⣿⣿⣿⣿⣿⡶⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠁⠀
⠀⠀⠀⠀⠀⠀⠉⠙⠿⢿⣿⣿⣿⣿⠟⠁⠀⠘⠿⣿⣿⣿⠿⠟⠉⠀⠀⠀⠀

Contents


Overview

mpvc is a collection of POSIX shell scripts: For more details on how to use the above tools have a look at the logbook.html. In addition, the casts/ directory to shows some screencasts of mpvc in action.

QuickInstall ▶️

mpvc-installer fetch-user: installs mpvc under BINDIR=~/bin/

curl -fsSL -o mpvc-installer https://github.com/gmt4/mpvc/raw/master/extras/mpvc-installer; sh ./mpvc-installer fetch-user

QuickStart

Below is a Quick Start guide showcasing mpvc commands usage.

 # fetch a local copy of the github repo
 git clone https://github.com/gmt4/mpvc/
 # use extras/mpvc-installer: just copy/link to your $HOME/bin
 (cd mpvc; extras/mpvc-installer link-user)
 (cd mpvc; extras/mpvc-installer config-user)
 (cd mpvc; extras/mpvc-installer check-reqs)
 # adjust .config/mpvc/mpvc.conf to suit your needs, mpvc-installer config-user just installs the defaults

 # use mpvc-fzf to search and play youtube media
 mpvc-fzf -p 'kupla mirage'
 # use mpvc-fzf to manage the playlist
 mpvc-fzf -f
 # use mpvc to enqueue local media / online YT media
 mpvc add /path/to/your/*.mp3 # or your URLs
 # 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).

Screenshots

mpvc-fzf running on mac OS (screenshot click to view) mpvc-fzf on Mac OS screenshot

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

mpvc-tui -f: running with fzf (screenshot click to view) mpvc-tui fzf screenshot

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


Documentation

Usage

mpvc(1)
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(1)
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 TUI
 -tt|tinytui    : Starts the mpvc-tui TUI (tiny mode)
 -ttt|ttinytui  : Starts the mpvc-tui TUI (ttiny mode)
 -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 
 -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(1)
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 & play local media at ytdl-archive/
  -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
    (--)rapi    : Search & play Radio-Browser API channels
    (--)ntsr    : 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(1)
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
  install-sys    : Install to BINDIR=/usr/local/bin (sets PREFIX=/usr/local)
  uninstall-user : Uninstall from BINDIR=/home/user/bin
  uninstall-sys  : Uninstall from BINDIR=/usr/local/bin (sets PREFIX=/usr/local)

*tips: If unsure where to start, start with: mpvc-installer fetch-user

Logbook

The logbook got big enought to deserve a page on its own, see here: logbook.html


📅 Mon, 15 Jun 2026 by gmt4 ⚡ PoweredBy #HTML