Suckless music player daemon

75478f9 README markdownization

~q3cpma pushed to ~q3cpma/mus git

30 days ago

475d642 README markdownization

~q3cpma pushed to ~q3cpma/mus git

a month ago


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 mus_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 your music directory arborescence is structured so that albums are at depth 2.

A lemonbar status script can be found here (superseded by this, though).

#Usage examples

Launch the server with cat as status notification command:

$ mus_daemon -s cat &

If using the album tools, initialize the database:

$ mus_album_db_create ~/Music

And pick two albums, update the database and append them to the playlist:

$ mus_album_pick ~/Music/album1/ ~/Music/album2/ | mus_client PL_APPEND
$ readlink -f ~/Music/album1/ ~/Music/album2/ | mus_client PL_APPEND  # Without album tools

Append 100 random albums (mus_album_rand implicitely updates the database) and issue some commands to the player:

$ mus_album_rand 100 | mus_client PL_APPEND
$ mus_client TOGGLE_PLAY_PAUSE
$ mus_client ALBUM_NEXT
$ mus_client PL_EDIT

#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, xargs -0 and sed -E (portability notes here)
  • awk with "/dev/stderr" extension (all notable implementations)
  • flock (util-linux, BSD base or port; cf this 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 in 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

#Environment variables

For mus:

  • MUS_SOCKET: IPC socket path (useful if you want to run several instances), defaults to /tmp/mus.sock.
  • MUS_PLAYLIST: explicit, defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/mus/playlist.
  • VISUAL or TERM+EDITOR: how to edit the playlist with mus_client PL_EDIT.

For the album tools:

  • MUS_ALBUM_DB: explicit, defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/mus/album_db.
  • MUS_MUSIC_DIR: music root directory, defaults to $HOME/Music.