🎧 mpvc

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

An elegant, lightweight, mpc-like command-line and web controller for the mpv media player, built on POSIX shell scripts and Unix sockets.

⚡ Installation

curl -fsSLO https://github.com/gmt4/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

Prefer using package managers like Homebrew, Nix, Pkg, Gentoo, or the Arch AUR? See the Detailed Installation steps in docs/README.md.

---

🚀 Quickstart Guide

1. Base Player Controls (mpvc)

mpvc toggle                          # Toggle playback state (play/pause)
mpvc togglev                         # Toggle video playback state (on/off)
mpvc togglei                         # Toggle idle playback state (once/always/off)
mpvc next                            # Skip to the next track in the playlist
mpvc add "https://youtube.com..."    # Stream online media via yt-dlp
find ~/Music -type f -name "*.mp3" | mpvc load    # Pipe local directories into the active queue

2. Interactive Search Controls (mpvc-fzf)

mpvc-fzf -f         # Launch fzf to visually manage your current playlist queue
mpvc-fzf -p 'query' # Search on Invidious/YouTube and stream matching audio
mpvc-fzf --lofi     # Instantly search and play live Lo-Fi audio feeds
mpvc-fzf --somafm   # Browse and stream live background channels from SomaFM

3. Web Browser Control (mpvc-web)

mpvc-web -c start       # Start, and open `http://localhost:8888` in your browser
mpvc-web -c start -s1   # Start, and open `https://localhost:8443` in your browser

Looking for high-level script wrappers, playlist stashes, or advanced command examples? Check out the Complete Usage Examples in docs/README.md.

---

🎛️ Companion Tools

• mpvc: Core CLI interface for absolute playback, queue sequencing, and scripting.
• mpvc-fzf: Interactive fuzzy-finder integration to look up tracks and stream streams.
• mpvc-tui: Terminal-user-interface console to display tracks and desktop notifications.

To see the full breakdown and capabilities of each tool script, read our Overview in docs/README.md.

Screenshots

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)

---

⚙️ System Requirements

• Required: POSIX-compliant shell (sh), mpv, socat.
• Recommended: fzf, yt-dlp.

For package manager setups or troubleshooting tips, consult the Prerequisites Guide in docs/README.md.

---

🛠️ Configuration

Config file located at ~/.config/mpvc/mpvc.conf.

For full variable template defaults or configuring backend rules (mpv.conf / yt-dlp.conf), look over our Configuration in docs/README.md.

---

🗺️ Documentation

Documentation can be found in the man pages, FAQ, README, and dev log:

• https://github.com/gmt4/mpvc : The project site at github.

• https://gmt4.github.io/mpvc/man/man1/ : For the mpvc command-line tools read the manual page.

• https://gmt4.github.io/mpvc/logbook.html : The logbook (blog) is a companion of mpvc that covers mpvc usage & evolution:

• https://github.com/gmt4/mpvc/docs/FAQ.md : Check the FAQ for any questions left after reading the above docs.

Issues

If you encounter a bug file an Issue.