summaryrefslogtreecommitdiffstats
path: root/README.md
blob: 78574bb7ae465b8279b509df4b1e0cad41695bdb (plain)
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
# clerk - mpd client, based on rofi (or dmenu)

# Functions:

* Play random album
* Play x random tracks
* Browse Library (Artist > Album > Tracks)
* Browse local filesystem (needs unix socket in mpd.conf)
* Show current Playback Queue
* Show Albums/Tracks by currently playing Artist
* Enable or disable scrobbling (with support for remote mpdscribble)
* Love current song on lastfm (Using lastfm-mpd-cli)
* Rate albums (Stored in flat files for portability & mpds sticker database)
* Rate tracks (Stored in flat files for portability & mpds sticker database)
* Load rated albums/tracks
* Play Similar Songs (based on lastfm)
* Control mpd options (modes, replaygain, crossfade)
* Lookup artist/album/lyrics in webbrowser

Written completely functional, nearly every option is accessible
from command line.
For example `clerk --random track` will play random songs.

see `clerk -h` for all default arguments.


# Dependencies:

* dmenu2 (https://bitbucket.org/melek/dmenu2) OR
* rofi (https://github.com/DaveDavenport/rofi)
* mpc
* mppc (https://github.com/carnager/mppc) (for features, mpc does not provide)

Hint: When using rofi, you can use Shift+Enter to execute several commands
e.g. adding more than one song.

# Optional Dependencies

* surfraw (for lookup)
* lastfm-mpd-cli for loving tracks (https://github.com/morendi/lastfm-mpd-cli)
* mpd-sima (for Similar Artists playback)

# Installation

1. Install dependecies (each binary needs to be in your $PATH)
2. Copy config.example to $HOME/.config/clerk/config and edit it.
3. Copy clerk and clerk_updater to $PATH
4. Run clerk

For arch linux there is a package in [AUR](https://aur.archlinux.org/packages/clerk-git/)

# Important

clerk is heavily depending on a well structured database.
All your files need these tags in order for clerk to work as intended:
* albumartist
* artist
* date
* album
* tracknumber
* title

Some software (beets, I look at you!) loves to add duplicate tags.
For example beets adds track and tracknumber tags, no matter what file format
is handled. MPD will return tracknumber twice for such files.
Make sure to clean your tags, if you used beets to tag them.

#### A word on album ratings
mpd's sticker database is very limited and only allows stickers to be associated
with files. Originally it was planned to extend stickers for other types too
(and documentation even claims it does), but this hasn't happened yet.
So what clerk does is to associate an album rating with first file of an album,
to keep the database clean and duplicate-free.
It's a somewhat ugly workaround, but it works pretty good.

Also mpd deletes stickers instantly, when files move or get renamed.
For this reason I keep flat files in directory of the album for both track and
album ratings. With those files and a tiny bash script it's possible to rebuild
the sticker database in very little time.

So if you plan to use ratings, it's a good idea to have music_path option
in config file. If your music is on a different machine just mount it locally.