lwilletts / mpvc

An mpc-like control interface for mpv.

mpvc 🎧

A terminal music player in POSIX sh(1) that interfaces mpv providing mpc(1) commands + extras. Originally a fork of lwillets/mpvc that evolved on its own, providing some extra goodies such as: improved CLI, TUI, FZF, WEB, EQ, & playing media from YouTube & streaming services. Check the Wiki, LogBook & Casts for a detailed view of the extra features of this fork.

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 player functionality is provided by:

• mpvc: provides the mpvc player core CLI commands
• 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-autostart: 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 LogBook. In addition, the casts/ directory to shows some screencasts of mpvc in action.

Requirements

Required:

• mpv
• socat: is preferred due to the differing implementations of netcat across UNIXes.
• awk: a sane version of awk for the same reason (gawk works)

Recommended extras:

• curl
• fzf
• jq
• notify-send

Check for missing dependencies using mpvc-installer check-reqs.

Installation

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

Manual

The easiest install method is just to run the mpvc-installer to install under $HOME/bin

curl -fsSL -o mpvc-installer https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer \
  && sh ./mpvc-installer fetch-user

Git

 # fetch a local copy of the github repo
 git clone https://github.com/lwilletts/mpvc/
 # use extras/mpvc-installer: just copy/link to your $HOME/bin
 (cd mpvc; extras/mpvc-installer link-user)

 # use mpvc-fzf to search and play youtube media
 mpvc-fzf -p 'kupla mirage'
 # 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-fzf to manage the playlist
 mpvc-fzf -f
 # use mpvc-tui to start the tui + desktop notifications
 mpvc-tui -T

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 such as FreeBSD):

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

MacOS

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

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

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 -[d:hHktTm:nsSP:x] args # @version v1.5 (c) gmt4 https://github.com/gmt4/mpvc
  -d : Set the WD to the media directory given as argument
  -n : Desktop notification using notify on mpvc events (notify-send*)
  -s : Suggest a random media to play based on previous media played
  -t : Starts the mpvc-tui to manage the mpv playlist (rlwrap*)
  -T : Combo that starts mpvc-tui -t -n, and adds media given as args
  -x : Starts mpvc-tui in a new xterm (config $MPVC_TERM) [combine -x with d:hHktTm:nsSP:x]
*tips: If unsure about where to begin, start with: mpvc-tui -d /path/to/media/ -T

mpvc-fzf

usage: mpvc-fzf -[01ab:cCd:efFg:G:hk:K:n:s:p:P:o:Or:lL:xv] args # @version v1.5 (c) gmt4 https://github.com/gmt4/mpvc
  -b : Browse the provided ytdl-archive URL with fzf (fzf*)
  -c : Start fzf to manage the current mpv chapterlist (fzf*)
  -d : Set the WD to the media directory given as argument
  -f : Start fzf to manage the current mpv playist (fzf*)
  -g : Fetch the given YT URL, and store locally (fzf*)
  -G : Search on Invidious, fetch, and store locally (fzf*)
  -l : Search & play local media (fzf*)
  -s : Search on Invidious (fzf*)
  -p : Search & play media found using Invidious (fzf*)
  -x : Starts mpvc-fzf in a new xterm (config $MPVC_TERM) [combine -x with 01ab:cCd:efFg:G:hk:K:n:s:p:P:o:Or:lL:xv]
*tips: If unsure about where to begin, start with: mpvc-fzf -p 'kupla mirage'

Tricks

There's some basic tricks in Git to get you started. For more check the LogBook.

This gives just a sneak peek on what's possible to manage mpv from the command-line, your best chances are to go play and have fun.

Limitations

Like any piece of software, mpvc is not perfect:

• mpvc does not resolve individual files in a directory unless it is currently in or has been inside that directory, giving misleading results about the total number of files in the current playlist. This is a limitation of mpv.
• mpvc depends on shell tools. If your shell is misconfigured or you are using unusual variants of basic UNIX tools, mpvc is not guaranteed to work. However, all effort has been made to make mpvc as POSIX compliant as possible.

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

mpvc's Issues

Here's a screenshot for you

http://pub.iotek.org/p/Z15P34j.png

--input-unix-socket is being replaced with --input-ipc-server

But --input-ipc-server is still very new, having only been added last mpv release, breaking compatibility with older mpv versions. I think the best solution will be to wait until mpv git removes --input-unix-socket completely, then start using and recommending it.

Weird terminal glitch

https://youtu.be/-RLFYJibT6k
So this is happening to me (xst - bash) and my friend (alacritty - mksh[?]). When you start the mpvc, looks like it make a glitch that begin to hidden/blend/mix(?) some words in a level that even make the terminal stop working of receivecommands.

Im using VoidLinux.
And thanks for the program!

Offer to use GNU netcat as an alternative to socat.

Title.

Implement consume mode.

Title.

Add GNU-style long options and a MPC compatibility layer.

Title.

Add fuzzy string search through playlist titles to play closest match.

Probably as part of --play.

PKGBUILD on Archlinux AUR repo is broken

Thanks for your work on this tool and the new 1.4 release.

From the README

To install mpvc:

...
Distro packages:

    Arch Linux package: pacaur -y mpvc-git

This is broken and not working. Since you are also the maintainer of that PKGBUILD could you check it out and correct ?

https://aur.archlinux.org/packages/mpvc-git

Thanks in advance.

mpv --idle=once

What do you think about using --idle=once if an mpv process isn't found? Using the "once" parameter would allow mpv to stop after it finishes its work rather than continue to retain resources while not in use. I don't think the cost of starting up a new mpv process is very big. People that want the single long-lived mpv behaviour can still start it externally with --idle=yes.

feature request: --format

Just to put it on the radar, would be nice to have an equivalent to mpc --format with relevant options.

nice script :)

Implement playlist-move function.

Allows the user to move a track in the current playlist to somewhere else in the playlist, respecting ranges.

Main barrier is implementing a safe way to get ONLY two args and no more.

Phraser cannot handle files with spaces in them.

Is it worth mentioning that mpvc -a $(find . -type f) will not work if the filenames have spaces? To use find this way you would need to use find . -type f -print0 | xargs -0 mpvc -a but at that point you might as well just pipe directly to mpvc. Nothing is really gained by using the command line argument syntax here.

mpvc -a * will still work fine however.

Build phraser to set absolute time of track with timestamp format.

--playnext inserts the track into the previous position

Describe the Issue
Using --playnext on a track when there is a queued playlist inserts the track into the previous position of the current track.

To Reproduce
Steps to reproduce the behavior:

1. Load a playlist using mpv --input-ipc-server=/tmp/mpvsocket [playlist link]
2. Insert a track using mpvc -A [video link]
3. If the current track is, e.g. #​5 in queue, the new track is #​5 and the currently playing track is #​6.

Expected behavior
The current track stays in the same position and the new track is inserted into the next position.

Script not POSIX on OpenBSD

Not currently working with the #!/bin/sh shebang that comes default on OpenBSD, (which has /bin/sh linked to ksh)

proof:

Changing the shebang to /bin/bash solves all problems -- works flawlessly.

Request: make POSIX to remove bash dependency

feature request: subscribe

mpc has mpc idleloop, which will output mpd events as they happen - this is useful for acting as a trigger for say, panel mpd status updates - I would like the same to be possible with mpvc - maybe have it monitor for a change in the socket type of thing?

Factoring and enqueuing https:// URLs (enhancement)

Hi there,

Forked the code at https://github.com/gmt4/mpvc/commits/master,
For now it's been just a few minor things to get going, such as:

• Factoring a bit the code
• Minor changes for enqueuing https:// URL with: mpvc -a https://...

Just to let you know in case there's something you find useful.

Save all songs in playlist to a file to load later.

Main barrier is that mpv depends on knowing the path to the files, not just the filename as mpv doesn't have a database file to use!

Phrasing Error

The following is an issue someone emailed to me:

Hi,

I noticed an error when -q -a are used together and then immediately -R.

I looked at the code and the playlist appends are backgrounded, so
mpvc exits but items are still being added, so I think it just need a
wait.

Remove all items from a playlist.

Just reminding myself to do this ^^

New release

Many commits have been made since 2016, can we get a 1.3 release?

Would be great for packaging this as ports without needing to use git.

Thanks.

formatPrint sed replacement error

If the file metadata contains '&', the %tag% will be inserted back like:
echo 'one %two% three' | sed 's#%two%#four&five#g'
would return:
'one four%two%five three' rather than 'one four&five three'

'&' will fix that behaviour but I'm not sure of an easy way to do that.

Random next track without changing playlist order.

Had this one in the mpc options section commented out for awhile to be implemented, but I talked to the one of the lead devs for mpv and he doesn't want to implement this option directly in mpv, so we'll have to fake do it in mpvc directly. Probably by storing a variable in a file somewhere.

New release (June 2022)

Great project ! Love that it uses simple good old Unix tools and requires no complicated dependencies

I'm trying to test this on Archlinux. Unfortunately we currently only have a "mpvc-git" PKGBUILD recipee. It builds pulling from github master. And worse, it is currently broken, https://aur.archlinux.org/packages/mpvc-git.

I would like to test this with a proper "mpvc" PKGBUILD. Not a "mpvc-git" PKGBUILD. The last release is from 2020. And I see a lot of activity recently since last year.

Could you please tag and release a new one ?
Thanks in advance

#43

feature request: add next / insert

I'm not knowledgeable enough to implement this myself, but an "insert" or "addnext" function like in mpc would be useful. All it does is add a song after the currently playing song in the queue.

Otherwise, I really like this script.

Thumbnail preview

ueberzug would be useful for this task.

Remove bc checks

I believe bc is a required utility for POSIX. Is it okay to remove from the dep checks / README?

change format %filename% --> %file%

to match mpc, for better script integration.

mpvc is not able anymore to add folders or YT videos to a playlist

I've been a long time enjoyer of mpvc since 2017, with my personal little addition mentioned here: #40 (comment).

However, after many years of not updating mpvc I finally took the time to try the new commits.

Since commit 7f3543c mpvc seems to have lost the ability to add folders or YT videos to a playlist.

For example when adding a YT video with:
mpvc add ytvideourl

I get:
/tmp/mpvsocket does not exist. Use mpv --input-ipc-server to start one.

and if I manually create the socket with mpv:
No files added to /tmp/mpvsocket

It works only when I add files with absolute paths.

I use:
Debian Sid
bash 5.2.0
mpv 0.34.1

Better mps-youtube integration

Might I suggest a better way to use mpvc and mps-youtube?

set download_command mpvc add https://youtu.be/%i#%f -- --vid=no

Then add tracks in mpsyt using, for example: da 1-5

Advantages:

• When using mpvc current you actually see info for the track playing instead of a crazy googlevideo.com link.
• When using mpvc -i the filename will include more interesting track information which can better parsed in the script.

Suggestion: make mpvc busybox compatible

nc - busybox's nc does not have the -U or -N flags

Solution: install socat

grep - busybox's grep does not have the -G flag

Solution: install gnugrep

Could there be a work around?