Overview
--------
mus is a simple CLI client/daemon music player consuming a newline separated plaintext path (files
or directories) playlist. It is formed of several independent parts:
* mus_daemon:
Consume the playlist and play its items via mus_player.
* mus_client:
Send commands to the player and receive its answers, read or modify the
playlist.
* mus_player:
Play audio files and answer to mus_client's commands. Notable features
include gapless playback, ReplayGain support and event reporting.
Format support: FLAC (16 bits), Vorbis and Opus; mono/stereo only
* mus_album_* and fair_shuf:
Optional album tools for random but fair album picking. These assume
that the music directory arborescence is structured so that albums are
at depth 2.
A lemonbar sh status script can be found at [1] (superseded by [2], though).
Dependencies and portability
----------------------------
In addition to the latest POSIX environment, you'll need the following:
* GNU11 compiler (gcc or clang) at build time
* libao
* libflac, vorbisfile, opusfile (each optional)
* socat
* /bin/sh with local/typeset extension (all notable implementations)
* awk with "/dev/stderr" extension (all notable implementations)
* xargs -0 and sed -E (GNU, *BSD, MacOS and Illumos; soon in POSIX, cf [3] & [4])
* flock (util-linux, base or port; cf [5] for other platforms)
* ed (POSIX requirement, but often missing from GNU/Linux distros)
In brief, at least GNU/Linux, *BSD, MacOS and Illumos should work.
Building and installation
-------------------------
To build and install mus (default values shown between brackets):
$ [CC=gcc] [LTO=false] [NATIVE=false] [USE_FLAC=true] [USE_OGG_VORBIS=false] \
[USE_OGG_OPUS=false] ./build.sh
# [DESTDIR=] [PREFIX=/usr/local] ./build.sh install
To install the optional album tools:
# [DESTDIR=] [PREFIX=/usr/local] ./build.sh albumtools_install
To uninstall:
# [DESTDIR=] [PREFIX=/usr/local] ./build.sh uninstall
# [DESTDIR=] [PREFIX=/usr/local] ./build.sh albumtools_uninstall
Usage examples
--------------
Launch the server with cat as status notification command:
$ mus_daemon -s cat [OPTIONS] &
If using the album tools, initialize the database:
$ mus_album_db_create [MUSIC_DIRECTORY...]
And pick two albums, update the database and append them to the playlist:
$ mus_album_pick album1/ album2/ | mus_client PL_APPEND
Same as above, without needing the album tools:
$ readlink -f album1/ album2/ | mus_client PL_APPEND
Append 100 random albums (mus_album_rand implicitely updates the database):
$ mus_album_rand 100 | mus_client PL_APPEND
Then you can issue commands via mus_client:
$ mus_client TOGGLE_PLAY_PAUSE
$ mus_client ALBUM_NEXT
$ mus_client PL_EDIT
...
Environment variables
---------------------
For mus:
* MUS_SOCKET
Defaults to /tmp/mus.sock. Useful if you want to run several instances.
* MUS_PLAYLIST
Defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/mus/playlist.
* VISUAL or TERM and EDITOR
How to edit the playlist with `mus_client PL_EDIT`.
For the album tools:
* MUS_ALBUM_DB
Defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/mus/album_db.
* MUS_MUSIC_DIR
Defaults to $HOME/Music.
Troubleshooting
---------------
Setting a libao config file can solve some common problems like the
`Unknown PCM cards.pcm.front` message from ALSA:
$ cat /etc/libao.conf
# Avoid trying pulseaudio
default_driver=alsa
# Avoid problems with front being tried first
dev=default
[1] https://git.sr.ht/~q3cpma/dotfiles/tree/40862a33735673e47f6dafece545887f7a7040ab/item/.config/lemonbar/mus_status.sh
[2] https://git.sr.ht/~q3cpma/lemonbar-tcl
[3] https://austingroupbugs.net/view.php?id=243
[4] https://austingroupbugs.net/view.php?id=528
[5] https://github.com/discoteq/flock