~q3cpma/mus

ref: e99afe099fd0b6cf6a4cce58902c9612ecd9fca9 mus/README -rw-r--r-- 5.1 KiB
e99afe09q3cpma Finish build.sh and README, move TODO to root 1 year, 27 days ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
                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