mus - A simple album playlist based music player
================================================
Overview
--------
mus is a simple CLI client/daemon music player consuming a plaintext album
directory path playlist.
File support is limited to 16 bits mono/stereo FLAC, Vorbis and Opus on
GNU/Linux and {Free,Net,Dragonfly}BSD, out of the box. It can work easily on
OpenBSD and MacOS by installing a port for flock(1).
Features include gapless playback, replaygain support and event reporting, see
mus_player/TODO for stuff in the work.
mus is formed of several independant parts:
* mus_daemon:
Play albums from a playlist via mus_player.
* mus_client:
Send commands to the player and receive its answers, read or modify the
playlist.
* 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.
* mus_player:
Play audio files and answering to mus_client's commands.
* mus_udsend:
The helper program to communicate with UNIX domain sockets (thanks
POSIX). Mandatory if you want to use the IPC feature.
A lemonbar status script can be found at [1]
Dependencies and portability
----------------------------
In addition to everything specified by the latest POSIX, you'll need
the following for mus_player:
* C11 compiler (build)
* gperf (build)
* pthread
* libao
* libflac (build, optional)
* vorbisfile (build, optional), often part of the libvorbis package
* opusfile (build, optional)
and some runtime dependencies:
* GNU/Linux:
ed(1) (POSIX requirement but often absent) and the util-linux package.
* FreeBSD, NetBSD, DragonflyBSD:
None.
* OpenBSD:
flock(1) from the port tree.
* MacOS:
flock(1) from somewhere (e.g. [2]) and a readlink implementation with
the -f option (e.g. GNU readlink).
mus was tested on Gentoo GNU/Linux with:
* /bin/awk -> busybox
OK
* /bin/awk -> mawk
Works with mawk >= 20181114 (see [3]).
* /bin/sh -> busybox
OK
* /bin/sh -> dash
OK
Building and installation
-------------------------
To build and install mus (default values shown); you'll have to specify a
different CC like gcc or clang, since mus_player is C11:
$ [CC=c99] [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_PAUSE_PLAY
$ mus_client ALBUM_NEXT
$ mus_client PL_EDIT
...
Important 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.
Audio configuration tips and trivia
-----------------------------------
Setting a libao config file can solve some usual problems like
`Unknown PCM cards.pcm.front` from ALSA:
$ cat /etc/libao.conf
# Avoid trying pulseaudio
default_driver=alsa
# Avoid problems with front being tried first
dev=default
The default linear resampling algorithm of ALSA's dmix should be changed for
something better (whatever the audibility of such change), see [4]:
$ cat /etc/asound.conf
# Use speexrate_best for entirely transparent resampling
defaults.pcm.!rate_converter "speexrate_medium"
Even with the best hardware, your room is probably the biggest sound factor,
which is why room compensation is almost mandatory.
See DRC-FIR [5] [6] and Brutefir [7] [8] to solve the problem with free (and
mostly suckless) software.
[1] https://git.sr.ht/~q3cpma/dotfiles/tree/master/.config/lemonbar/mus_status.sh
[2] https://github.com/discoteq/flock
[3] https://github.com/ThomasDickey/original-mawk/issues/56
[4] https://wiki.archlinux.org/index.php/Talk:Advanced_Linux_Sound_Architecture#On_high_quality_resampling
[5] http://drc-fir.sourceforge.net
[6] http://drc-fir.sourceforge.net/doc/drc.html
[7] https://www.ludd.ltu.se/~torger/brutefir.html
[8] http://digitalroomcorrection.hk/http___www.digitalroomcorrection.hk_/BruteFIR.html