Isaiah Poston
isaiah@ilposton.com

MPVC(1)

MPVC(1) General Commands Manual MPVC(1)

mpvc — A terminal streaming music player

mpvc [-dh] [-f index] [-s socket]

mpvc is a terminal music player that supports both streaming from the network and local file playback.

By using mpv to play audio, it supports streaming from a URL and can easily be extended for more audio formats. mpvc also supports the MPRIS specification, which allows the playerctl(1) utility to control the player with a common API.

mpv is controlled over a unix(7) socket using mpv's JSON IPC protocol. This allows either mpvc or mpvd(1) to be swapped out without affecting the other half.

The options are as follows:

Print diagnostics to ./mpvc.log and log debugging messages.
index
Set and load index file. By default mpvc looks for ~/.local/share/mpvc/index.json.
Print the help message and exit.
socket
Set the socket file. By default mpvc listens on /tmp/mpvd.sock.

k, ARROW UP
Move up one item.
j, ARROW DOWN
Move down one item.
PAGE UP
Scroll up one page.
PAGE DOWN
Scroll down one page.
g, HOME
Move to the first item.
G, END
Move to the last item.
ENTER, l, KEY RIGHT
Select current item. If showing the artist view, selecting an artist switches to the playlist/song view. This view shows the playlists and songs for an artist.

If showing the playlist/song view, local index search results, or YouTube search results, selecting an item starts playback of the item, replacing any playing playlist or song.

If showing the playlist queue view, selecting an item starts playback of the playlist item, keeping the current playlist loaded.

h, KEY LEFT
Show the artist (default) view.
i
Show the playlist queue view. This view displays items of the play queue.
/
Search the local index.
:
Search YouTube using youtube-dl 'ytsearch:%s'.
a
Add a playlist or song to the index file.
w
Download the current playlist or song using youtube-dl.

mpvc looks for youtube-dl or a compatible fork in order of 'yt-dlp', 'yt-dlp_x86', and 'youtube-dl', searches for the executable in PATH and mpv's configuration directory.

p
Pause the player.
v
Stop playback and clear playlist.
x
Shuffle the playlist.
9
Decrease mpv volume by 2 percent.
0
Increase mpv volume by 2 percent.
<
Go to the previous playlist entry.
>
Go to the next playlist entry.
[
Seek 5 seconds backward.
]
Seek 5 seconds forward.
q
Quit the client.
Q
Quit the client and the mpv server.

~/.local/share/mpvc/index.json
The default mpvc index file, where artist and playlist/song data are stored and read from.
/tmp/mpvd.sock
The default mpv JSON IPC socket mpvc attempts to connect to send commands and receive data.
~/Music
The default download location where playlists and songs are downloaded to.

The mpvc utility exits 0 on success, and >0 if an error occurs. It can fail for any of these reasons:

  • It could not connect to the mpv socket.
  • It could not read the index file.
  • When MPRIS support is enabled, if MPRIS could not be configured.

mpv(1), mpvd(1), playerctl(1), youtube-dl(1)

mpv's online manual has a section JSON IPC documenting the JSON IPC protocol used by mpvc.

January 29, 2022 ilposton.com