504512f Change STATUS command to put format on multiple lines
~q3cpma pushed to ~q3cpma/mus git
de2bf79 Bump udsend recv buffer size (got a cutoff with properly tagged Wagner)
~q3cpma pushed to ~q3cpma/mus git
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 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. See mus_player/IPC.txt for details. * 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: 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 at build time: * GNU11 compiler (gcc or clang) * posix-build dependencies: mktemp -d (present on GNU, *BSD, MacOS, Illumos and Tru64) and local/typeset support in /bin/sh * libao headers * libflac, vorbisfile, opusfile headers (each is optional) and some runtime dependencies: * libao * libflac, vorbisfile, opusfile (according to the build options) * On GNU/Linux, ed(1) and the util-linux package. * On OpenBSD, flock(1) from the port tree. * On MacOS, flock(1) from somewhere (e.g. [2]). mus was tested on Gentoo GNU/Linux with: * /bin/awk -> busybox: OK * /bin/awk -> mawk: OK with mawk >= 20181114 (see [3]). * /bin/sh -> busybox: OK * /bin/sh -> dash: OK 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_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