Small C utilities for controlling MPD through libmpdclient. List inputs contain one MPD URI per line; empty lines and lines starting with # are ignored. Use - for stdin.

Commands #

Command	Usage	Purpose
`mpd_add_to_queue`	`[--verbose] [FILE\|-]`	Append tracks to the queue.
`mpd_add_to_playlist`	`[--verbose] PLAYLIST [FILE\|-]`	Add tracks from FILE or stdin (`-`) to a stored playlist; without FILE, add the current song.
`mpd_edit_queue`	`[--force]`	Edit the queue with `$VISUAL`, `$EDITOR`, or `vi`.
`mpd_edit_playlist`	`[--force] PLAYLIST`	Edit a stored playlist.
`mpd_insert_next`	`[--verbose] [FILE\|-]`	Insert tracks after the current song, or at the front.
`mpd_now_playing`	`[--watch] [--json]`	Print the current song; watch mode uses MPD idle events.
`mpd_trim_queue`	`[--keep N]`	Remove played entries, optionally retaining the previous `N`.
`mpd_update_queue`	`[--force] [FILE\|-]`	Replace the queue while preserving playback where possible.
`mpd_update_library`	`[--no-wait] [--rescan] [FILE\|-]`	Update unique top-level directories, or the whole database with terminal stdin.
`mpd_report`	`[OPTIONS]`	Find database entries by `Last-Modified` time window.
`mpd_report_monthly`	`[MONTH [YEAR]] [MPD_REPORT_OPTION ...]`	Write the first four weekly reports for a month.
`mpd_report_daily`	`[MONTH [YEAR]] [MPD_REPORT_OPTION ...]`	Write daily reports for each day of a month.

Queue editing detects concurrent changes and attempts to restore the previous queue after a replacement failure. Playlist edits stage non-empty replacements before moving the old playlist aside. --force bypasses concurrency checks.

mpd_report accepts repeatable --window START,END epoch-second ranges; - means unbounded. Directories are emitted by default; --files includes songs, --path URI limits the search, and --relative strips that prefix. Multiple windows produce INDEX<TAB>URI, including every matching overlapping window. Results atomically replace all.txt by default; --output FILE chooses another path and --output - explicitly writes them to stdout. --tracks-output FILE atomically writes all song URIs during the same scan.

mpd_report_monthly is a Ruby helper for the four weekly reports created by diggah -m MM -w. Run mpd_report_monthly (or mpd_report_monthly 07 2026) to write 1_07_2026.txt through 4_07_2026.txt; append --files, --path URI, or other mpd_report options after --. It uses the current month and year when omitted. accepts -o DIRECTORY, and replaces reports atomically after a successful MPD query.

mpd_report_daily is a Ruby helper for daily reports. Run mpd_report_daily (or mpd_report_daily 07 2026) to write 01_07_2026.txt through 31_07_2026.txt; append --files, --path URI, or other mpd_report options after --. It uses the current month and year when omitted. accepts -o DIRECTORY, and replaces reports atomically after a successful MPD query.

Configuration #

Variable	Default	Purpose
`MPD_HOST`	`localhost`	Hostname, Unix socket, or `password@host`.
`MPD_PORT`	`6600`	Server port.
`MPD_TIMEOUT`	libmpdclient default	Connection timeout in seconds.
`MPD_CONFIG_HELPER`	unset	Helper program to run. Set to `off` to skip `$HOME/bin/amen`.
`MPD_CONFIG_HELPER_TIMEOUT`	`10`	Helper timeout in seconds (1–3600).

If MPD_CONFIG_HELPER is unset, the tools try $HOME/bin/amen. If it is not executable, they connect using MPD_HOST and MPD_PORT as usual. The helper must print one MPD_HOST=value line and one MPD_PORT=value line. It is run without a shell and only once per process.

Exit status is 0 for success, 1 for runtime errors, and 2 for invalid arguments.

Development #

just build mpd_report mpd_report_monthly mpd_report_daily
python3 -m unittest discover -s mpd/tests -v