A brain-dead music player that uses POSIX shell and mpv to play MP3, MP4, Ogg Vorbis, FLAC, and online radio streams.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Matthew Graybosch 61892a250d forgot to update the synopsis in the manual page 2 months ago
LICENSE Added man page stub and switched to BSD license 2 months ago
README.md forgot to update the synopsis in the manual page 2 months ago
makefile updated make help message 2 months ago
manual.html forgot to update the synopsis in the manual page 2 months ago
manual.pdf forgot to update the synopsis in the manual page 2 months ago
rockout changed switch order on getopt line 2 months ago
rockout.1 forgot to update the synopsis in the manual page 2 months ago


ROCKOUT(1) - General Commands Manual


rockout - a front-end & launcher for mpv written in POSIX shell


rockout [-dhlpqrs] 'expression'


The rockout script uses shell utilities and mpv to generate a plain-text music library, search it using extended regular expressions, and play selections in your console.

rockout searches $MUSIC_DIR, which is ${HOME}/music by default, for all files that are not image files (JPG, PNG, or GIF) to build a music library that isn't cluttered with cover art files. The library, once generated with -l is located at ${HOME}/.local/rockout/library.m3u. Since library.m3u uses absolute file paths, it is compatible with other applications that use M3U playlists.

Because rockout uses grep -E in its egrep alias, it can query its library with grep-compatible extended regular expressions.

By default, rockout provides a count of tracks found for 'expression' , saves the result as /tmp/rockout-${USERNAME}.m3u, and immediately loads the playlist into mpv. However, by using the -q option, the operator can do a dry run. The operator can also use the -p option to reuse the previous playlist.

Once rockout has generated a playlist and piped it to mpv, the operator can control playback using mpv's keybindings.

rockout can handle any music format supported by mpv; it doesn't matter if your music directory contains MP3, MP4, FLAC, Ogg Vorbis, Ogg Opus, MIDI, or M3U files.

The options are as follows:


force mpv to run in windowed mode and show album art when available


dump a brief tutorial to the console


generate a plain-text music library


use the previously generated playlist located in $PLAYLIST


search the library for tracks matching 'expression' and send results to standard output


repeat/loop playlist


shuffle playlist during playback



the directory in which the operator keeps their music collection. This defaults to ${HOME}/music based on the author's setup.


the file where rockout keeps the results of the previous search. This is /tmp/rockout-${USERNAME}.m3u by default, and the permissions are set to 600 to provide a modicum of privacy.



a standard M3U file representing one's entire music collection


a standard M3U file containing cached search results


The rockout utility exits 0 on success, and >0 if an error occurs.


Generate your library after installation:

$ rockout -l

Generate your library after installation on GNU/Linux or GNU/systemd:

$ MUSIC_DIR=$HOME/Music rockout -l

Search for songs released in 1980:

$ rockout -q 1980

Play songs by Frank Zappa in random order without looping:

$ rockout -s Zappa

Loop a classic Judas Priest album:

$ rockout -r Stained_Class

Put some classic Dio albums on repeat and shuffle:

$ rockout -rs 'Dio.*Holy_Diver|Sacred_Heart|Dream_Evil'


find(1) grep(1) egrep(1) sort(1) wc(1) mpv(1)


rockout exists because the author got tired of writing ad-hoc find queries and piping those to mpv.


Matthew Graybosch <contact@matthewgraybosch.com>


rockout depends on having a reasonably well-organized music collection at the filesystem level since it does not attempt to deal with ID3 tags or their equivalent in Ogg Vorbis and FLAC files. Its utility depends entirely on the operator's facility with extended regular expressions.

While the playlist file in /tmp/rockout-${USERNAME}.m3u is read-write for its owner and inaccessible to non-root users, root (and users with equivalent access via doas/sudo) can still read and alter the file on a shared system.

rockout depends on mpv, which must be installed separately using your operating system's package manager.


rockout is both less intelligent and more literal-minded than its author, and cannot tell a Dio album from a Dio tribute album unless provided a properly crafted search expression.

rockout handles switches in the order provided. If the operator wants to use -p with switches that control the windowed, repeat, and shuffle modes, they should use -p last.

Should any other bugs occur, please report them to the author.

OpenBSD 6.9 - April 13, 2021