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 answer 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)
    * posix-build dependencies (mktemp -d and local/typeset support in /bin/sh)
    * 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"


[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