{"id":13407485,"url":"https://github.com/carnager/clerk","last_synced_at":"2026-02-23T05:15:49.625Z","repository":{"id":18901371,"uuid":"22119662","full_name":"carnager/clerk","owner":"carnager","description":"clerk - mpd client, based on rofi/fzf","archived":false,"fork":false,"pushed_at":"2024-02-20T11:36:55.000Z","size":1356,"stargazers_count":214,"open_issues_count":5,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-07-31T20:27:27.040Z","etag":null,"topics":["bash","mpd","rofi"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carnager.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-22T20:33:03.000Z","updated_at":"2024-05-08T08:23:24.000Z","dependencies_parsed_at":"2024-01-16T15:44:56.891Z","dependency_job_id":"386b7e36-5a88-45d5-b5ce-74e01d27cfa4","html_url":"https://github.com/carnager/clerk","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carnager%2Fclerk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carnager%2Fclerk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carnager%2Fclerk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carnager%2Fclerk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carnager","download_url":"https://codeload.github.com/carnager/clerk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243577768,"owners_count":20313697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","mpd","rofi"],"created_at":"2024-07-30T20:00:41.070Z","updated_at":"2026-02-23T05:15:49.576Z","avatar_url":"https://github.com/carnager.png","language":"Perl","funding_links":[],"categories":["Other"],"sub_categories":[],"readme":"# clerk\n\nMPD client using rofi or fzf\n\n## Screenshot (V4)\n![Screenshot](https://pic.53280.de/clerk.png)\n\n## Features:\n\n* Play random album/tracks\n* Add/Replace albums/songs\n* Filter lists by rating\n* Customizable hotkeys\n* Rofi and fzf interfaces\n* Optional tmux interface for fzf mode\n* Rate albums/tracks\n* Optionally store ratings in file tags\n\n## Dependencies:\n\n* rofi (https://github.com/DaveDavenport/rofi)\n* fzf\n* tmux\n* perl-net-mpd\n* perl-data-messagepack\n* perl-data-section-simple\n* perl-file-slurper\n* perl-config-simple\n* perl-try-tiny\n* perl-ipc-run\n* perl-http-date\n\nfor the tagging_client:\n* metaflac (flac)\n* vorbiscomment (vorbis-tools)\n* mid3v2 (mutagen)\n\n\n## Installation\n\n### Arch Linux\n\n* install [clerk-git from AUR](https://aur.archlinux.org/packages/clerk-git/)\n\n### Debian/Ubuntu\n\n* install deb package from [release page](https://github.com/carnager/clerk/releases)\n\n### Others\n\n#### For user only:\n\n* Install tmux, fzf and rofi\n* Install local::lib module (Most distributions should have it)\n* Install cpanm\n* Put `eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib=~/perl5)` to your shell config and restart your terminal\n* Clone this repository and change to clerk directory\n* Run `cpanm --installdeps .`\n* Move clerk.pl and clerk_rating_client to PATH\n\n#### Globally:\n\n* Install cpanm\n* Clone this repository and change to clerk directory\n* Run `cpanm --installdeps .` as root\n* Move clerk.pl and clerk_rating_client to PATH\n\n## Ratings\n\nClerk can rate albums and tracks, which will be saved in MPDs sticker database as rating or albumrating.\nTrack ratings should be compatible with all other MPD clients that support them.\nAlbumratings are a unique feature to clerk, as far as I know.\n\n### clerk_rating_client\n\nIt's also possible to store ratings in file tags. Currently this is supported for flac, ogg and mp3 files.\nFor this to work, simply set `tagging=true` in clerk.conf file and set your music_path.\n\nIt’s even possible to tag files not on the same machine (On MPD setups with remote clients).\nSimply copy your `clerk.conf` and `clerk_rating_client` to the machine hosting your audio files, edit `music_path`\nin config and start `clerk_rating_client`. A systemd user service is available.\n\nFor the moment I use metaflac, mid3v2 and vorbiscomment to tag files, because I haven't found a good perl library\nfor this task.\n\n### Filtering\n\nclerk integrates ratings fully into its database and exposes the ratings in track and album lists.\nTo filter by a specific rating use `r=n` as part of your input. Sadly filtering for `r=1` will also show `r=10`.\nin rofi interface you can work around this by filtering for `r=1\\s`. in fzf interface `r=1$` works.\n\nIf you don't like to see ratings in your track/album listings, simply increase the album_l setting in config.\n\n## Usage\n\n```\nUsage:\n    clerk [command] [-f]\n\n      Commands:\n        -a           Add/Replace album(s) to queue.\n        -l           Add/Replace album(s) to queue (sorted by mtime)\n        -t           Add/Replace track(s) to queue.\n        -p           Add stored playlist to queue\n        -r [-A, -T]  Replace current playlist with random songs/album\n        -u           Update caches\n\n      Options:\n        -f           Use fzf interface\n\n      Without further arguments, clerk starts a tabbed tmux interface\n      Hotkeys for tmux interface can be set in $HOME/.config/clerk/clerk.tmux\n\n    clerk version 4.0\n```\n\n## Hotkeys\n\n### Global\n\n```\nTab:   select item(s)\nEnter: perform action on item\n```\n\n### Hotkeys for tmux interface\n\n```\nF1:    albums view\nF2:    tracks view\nF3:    albums view (sorted by mtime)\nF4:    playlist view\nF5:    queue view (uses ncmpcpp by default, can be changed in clerk.conf)\nF10:   random pane\nC-F5:  previous song\nC-F6:  toggle playback\nC-F7:  stop playback\nC-F8:  next song\nC-F1:  show hotkeys\nC-q:   quit clerk tmux interface\n```\n\nAll tmux hotkeys can be changed in `clerk.tmux` file.\n\n## Files and Variables\n\nclerk uses `$XDG_CONFIG_HOME` and `$XDG_DATA_HOME` for its files. Both variables are usually unset\nand default to `$HOME/.config` and `$HOME/.local/share`. These files are stored by clerk:\n\n### XDG_CONFIG_HOME\n\n* `clerk.conf`:   config file.\n* `clerk.tmux`:   clerk's tmux config\n\n### XDG_DATA_HOME\n\n* `database.mpk`: clerk's local database\n\nUse `CLERK_CONF`, `CLERK_TMUX` and `CLERK_DATABASE` variables to override file locations.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarnager%2Fclerk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarnager%2Fclerk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarnager%2Fclerk/lists"}