mus - A simple album playlist based music player
================================================
Overview
--------
A simple client/server music player consuming a plaintext album playlist.
As I primarly made it for myself, it only supports FLAC, Vorbis and Opus (for
now) on GNU/Linux and {Free,Net,Dragonfly}BSD, out of the box. It can work on
OpenBSD/MacOS by installing a port for flock(1).
mus is formed of four 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 arborescence is structured so that albums are at depth 2.
This is the structure I use, for reference:
Music
├── Black Sabbath
│ ├── (1970-1) Black Sabbath
│ └── (1970-2) Paranoid
├── Solstice
│ └── (1995) Pray
├── Solstice (2)
│ └── (1998) New Dark Age
└── Uli Jon Roth
└── (2000) Transcendental Sky Guitar
├── Disc 1: The Phoenix
└── Disc 2: The Dragon
* mus_player:
The player doing all the job and answering to mus_client's commands.
Supports replaygain and gapless playback. Limited to mono/stereo
16 bits FLAC, Vorbis and Opus.
A lemonbar status script can be found at https://git.sr.ht/~q3cpma/dotfiles/tree/master/.config/lemonbar/mus_status.sh
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. [1]) 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 [2]).
* /bin/sh -> busybox
OK
* /bin/sh -> dash
OK
[1] https://github.com/discoteq/flock
[2] https://github.com/ThomasDickey/original-mawk/issues/56
Building and installation
-------------------------
To build and install mus (default values shown); you'll have to specify a
different CC, 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:
$ mus_daemon [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:
$ readlink -f album1/ album2/ | tr '\n' '\0' | xargs -0 mus_album_pick | 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 pause_play
$ mus_client album_next
$ mus_client pl_edit
...
Important environment variables
-------------------------------
For mus:
* MUS_PLAYLIST: defaults to $HOME/.config/mus/playlist
* VISUAL or TERM and EDITOR: how to edit the playlist with
`mus_client pl_edit`
For the album tools:
* MUS_DB: defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/mus/album_db
* MUS_MUSIC_DIR: defaults to ~/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, see [1]:
$ 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 [2] [3] and Brutefir [4] [5] to solve the problem with free (and
mostly suckless) software.
[1] https://wiki.archlinux.org/index.php/Talk:Advanced_Linux_Sound_Architecture#On_high_quality_resampling
[2] http://drc-fir.sourceforge.net
[3] http://drc-fir.sourceforge.net/doc/drc.html
[4] https://www.ludd.ltu.se/~torger/brutefir.html
[5] http://digitalroomcorrection.hk/http___www.digitalroomcorrection.hk_/BruteFIR.html