tools

various tools I have been using throughout the years
Log | Files | Refs | README | LICENSE

README.md (4054B)

      1 # mpd
      2 
      3 Small C utilities for controlling [MPD](https://www.musicpd.org/) through
      4 libmpdclient. List inputs contain one MPD URI per line; empty lines and lines
      5 starting with `#` are ignored. Use `-` for stdin.
      6 
      7 ## Commands
      8 
      9 | Command | Usage | Purpose |
     10 |---------|-------|---------|
     11 | `mpd_add_to_queue` | `[--verbose] [FILE\|-]` | Append tracks to the queue. |
     12 | `mpd_add_to_playlist` | `[--verbose] PLAYLIST [FILE\|-]` | Add tracks from FILE or stdin (`-`) to a stored playlist; without FILE, add the current song. |
     13 | `mpd_edit_queue` | `[--force]` | Edit the queue with `$VISUAL`, `$EDITOR`, or `vi`. |
     14 | `mpd_edit_playlist` | `[--force] PLAYLIST` | Edit a stored playlist. |
     15 | `mpd_insert_next` | `[--verbose] [FILE\|-]` | Insert tracks after the current song, or at the front. |
     16 | `mpd_now_playing` | `[--watch] [--json]` | Print the current song; watch mode uses MPD idle events. |
     17 | `mpd_trim_queue` | `[--keep N]` | Remove played entries, optionally retaining the previous `N`. |
     18 | `mpd_update_queue` | `[--force] [FILE\|-]` | Replace the queue while preserving playback where possible. |
     19 | `mpd_update_library` | `[--no-wait] [--rescan] [FILE\|-]` | Update unique top-level directories, or the whole database with terminal stdin. |
     20 | `mpd_report` | `[OPTIONS]` | Find database entries by `Last-Modified` time window. |
     21 | `mpd_report_monthly` | `[MONTH [YEAR]] [MPD_REPORT_OPTION ...]` | Write the first four weekly reports for a month. |
     22 | `mpd_report_daily` | `[MONTH [YEAR]] [MPD_REPORT_OPTION ...]` | Write daily reports for each day of a month. |
     23 
     24 Queue editing detects concurrent changes and attempts to restore the previous
     25 queue after a replacement failure. Playlist edits stage non-empty replacements
     26 before moving the old playlist aside. `--force` bypasses concurrency checks.
     27 
     28 `mpd_report` accepts repeatable `--window START,END` epoch-second ranges; `-`
     29 means unbounded. Directories are emitted by default; `--files` includes songs,
     30 `--path URI` limits the search, and `--relative` strips that prefix. Multiple
     31 windows produce `INDEX<TAB>URI`, including every matching overlapping window.
     32 Results atomically replace `all.txt` by default; `--output FILE` chooses another
     33 path and `--output -` explicitly writes them to stdout. `--tracks-output FILE`
     34 atomically writes all song URIs during the same scan.
     35 
     36 `mpd_report_monthly` is a Ruby helper for the four weekly reports created by
     37 `diggah -m MM -w`. Run `mpd_report_monthly` (or `mpd_report_monthly 07 2026`) to write
     38 `1_07_2026.txt` through `4_07_2026.txt`; append `--files`, `--path URI`, or
     39 other `mpd_report` options after `--`. It uses the current month and year when omitted.
     40 accepts `-o DIRECTORY`, and replaces reports atomically after a successful MPD
     41 query.
     42 
     43 `mpd_report_daily` is a Ruby helper for daily reports. Run `mpd_report_daily` (or `mpd_report_daily 07 2026`) to
     44 write `01_07_2026.txt` through `31_07_2026.txt`; append `--files`, `--path URI`, or
     45 other `mpd_report` options after `--`. It uses the current month and year when omitted.
     46 accepts `-o DIRECTORY`, and replaces reports atomically after a successful MPD
     47 query.
     48 
     49 ## Configuration
     50 
     51 | Variable | Default | Purpose |
     52 |----------|---------|---------|
     53 | `MPD_HOST` | `localhost` | Hostname, Unix socket, or `password@host`. |
     54 | `MPD_PORT` | `6600` | Server port. |
     55 | `MPD_TIMEOUT` | libmpdclient default | Connection timeout in seconds. |
     56 | `MPD_CONFIG_HELPER` | unset | Helper program to run. Set to `off` to skip `$HOME/bin/amen`. |
     57 | `MPD_CONFIG_HELPER_TIMEOUT` | `10` | Helper timeout in seconds (1–3600). |
     58 
     59 If `MPD_CONFIG_HELPER` is unset, the tools try `$HOME/bin/amen`. If it is not
     60 executable, they connect using `MPD_HOST` and `MPD_PORT` as usual. The helper
     61 must print one `MPD_HOST=value` line and one `MPD_PORT=value` line. It is run
     62 without a shell and only once per process.
     63 
     64 Exit status is `0` for success, `1` for runtime errors, and `2` for invalid
     65 arguments.
     66 
     67 ## Development
     68 
     69 ```sh
     70 just build mpd_report mpd_report_monthly mpd_report_daily
     71 python3 -m unittest discover -s mpd/tests -v
     72 ```