mpd-scripts

---

About

Collection of scripts related to mpd & mpc.

Name	Description
lastfm-love	Love or unlove tracks on lastfm
mpd-notifier	Notify users of playing track or mpd status with artwork
Tunein Radio Script	Fetches Tunein Radio station URLs and generates M3U playlists along with associated information. Uses StreamFinder::Tunein Perl module.
iHeartRadio Script	Fetches iHeartRadio station URLs and generates M3U playlists along with associated information. Uses StreamFinder::IHeartRadio Perl module.
volume	Scripts allowing you to control the volume.
mpd-queue-shuffle	This script generates a random playlist from a local music directory and saves it as an M3U playlist file in the specified playlist directory.
somafm	This script fetches the playlist URLs of SomaFM channels with the highest quality in MP3 format and creates separate playlists for each channel in extended M3U format with the channel name.
mpd-find-dup	Contains two scripts for deduplicating MPD queues: mpd-remove-duplicates-queue.sh interactively deletes duplicates from the current MPD playlist in-place, while mpd-deduplicate-save-and-reload.sh saves the current queue as a playlist, removes duplicates, then reloads the cleaned playlist.
mpd_rewind_daemon	A background daemon for MPD that automatically rewinds playback by a few seconds when resuming from pause, improving the experience for music, mixes, podcasts, and audiobooks.
mpd-usb-automount	System-level (root) setup for a removable USB music disk: a stable udev device name, on-demand autofs mounting, and idle spindown. Has its own separate installer, not part of the top-level install.sh.
mpd-smart-shuffle	A smarter shuffle: a background monitor records play/skip history, and a cron-run script tops up the MPD queue avoiding recent repeats, with optional weighted selection, artist/album diversity, seasonal and time-of-day genre filtering, exclude lists, and more.
mpdsimilar	Fetches similar artist tracks from Last.fm for the currently playing track or every track in the queue, and adds a sample of them to the MPD queue.
rm-duplicates-playlist	Removes duplicate entries from a saved MPD playlist or the current queue, or lists available playlists, combining what the two mpd-find-dup scripts each do separately into one tool.
rm-artists-playlist	Removes songs by a list of artists from a saved MPD playlist or the current queue, or lists available playlists.
mpd-add-random-artist	Adds a random sample of a specified artist's tracks to the current MPD queue, matching exactly by default or loosely with -l.
mpd-add-random	Adds a random selection of tracks from the local music library to the current MPD queue.
mpd-random-album	Clears the queue (or appends to it) and fills it with randomly selected complete albums, with optional year/genre/artist filters, a recent-picks cache to avoid repeats, a notification hook, and saving/restoring the original queue/state if anything fails.
add-current-song	Adds the currently playing MPD song to an M3U playlist, with duplicate prevention, sorting, locking, and atomic rewrites.
mpd-tray-icon	A GTK3 tray icon showing the currently playing MPD track, with Play/Pause/Next/Previous controls.
mpd-radio-tray	A PyQt5 system tray app for managing and playing categorized internet radio station URLs with MPD, similar to RadioTray-NG.
music_queue_manager	Manages song ratings and "bad" flags via MPD stickers: rate on a 5- or 10-point scale, flag/unflag broken songs, remove or jump to a random/top-rated song, and list or rescale ratings.
mpdmark	Bookmark playback positions in MPD via stickers, with multiple named bookmarks per song, listing, loading, renaming, deleting, and pruning stale entries.
alarmpd	Playlist-named alarm clock daemon: schedule alarms by creating/renaming an MPD playlist, with multi-day/named-group and one-shot forms, per-alarm volume caps, gentle fade-in with snooze, one-time skip, and collision detection.
mpd-kb-control	Dispatches multimedia-key presses (play/pause/next/prev/volume/mute) to MPD, plus consume/random/repeat/single mode toggles for a separate keypad, for binding in a window manager's keybindings.
mpd-auto-stop	Sleep-timer daemon with a web UI: start/extend/cancel a countdown, and it fades the volume out and pauses MPD when it fires instead of cutting off abruptly.
mpd-recent-tracks	Generates an M3U playlist (newest first) of music files added or modified in the last N days, optionally capped in size and auto-loaded into MPD, paused or playing.
mpc-fade	Fades MPD playback volume smoothly to a target level over a duration, or fades out/toggles play-pause/fades back in, using either MPD's own volume or a PulseAudio sink-input stream.
playpause	Prints the currently playing MPD track prefixed with a play/pause symbol, for use in a status bar (polybar, i3blocks, xmobar, etc).

Prerequisites

Listed in each script's README.md.

Installation

Run ./install.sh once — no manual copying needed. It:

1. Migrates any existing per-script settings from the old ~/.config/<script-name>/ layout into the new unified ~/.config/mpd-scripts/<script-name>/ layout (see Configuration below).
2. Checks whether a personal bin directory is already on your PATH, and, if not, creates ~/bin and adds it for you. It also offers to create ~/bin/music and add it to your PATH too, an optional separate directory for installing this repo's scripts, kept apart from other personal scripts in ~/bin.
3. Offers to install any missing apt/pip/cpan dependencies the scripts below need (mpc, curl, jq, PyQt5, PyGObject/GTK3, pylast, python-mpd2, the Perl StreamFinder modules, etc.).
4. Copies every standalone script (and whatever companion file it needs alongside it, e.g. a .conf.example template or a station list) into the directory from step 2, and installs MPD Notifier via its own installer.
5. Offers to install the optional MPD Rewind Daemon, prompting you to choose between two methods (install-xdg-autostart.sh or install-systemd.sh, with a clear recommendation either way — see mpd_rewind_daemon/README.md for details); the optional mpd-smart-shuffle tool (history-aware smarter shuffle, with its own optional systemd --user background monitor); the optional alarmpd tool (playlist-named alarm clock daemon, with the same XDG-autostart/systemd --user install choice); the optional mpd-auto-stop tool (sleep-timer web UI daemon, same install choice again); and the optional volume control scripts, prompting you to choose between the mpc- and python-mpd2-based variants (installing only one, since both use the same filenames).

Check each script's own README for usage notes once it's installed.

Contributing

Contributions are welcome!

• Bug reports: Open an issue.
• Everything else (questions, feature requests, ideas, general discussion): Use Discussions.
• Pull requests are welcome for bug fixes or discussed features.

Acknowledgments

• The original setup of this repository is by William Jacoby. For a full list of all authors and contributors, see the contributors page.
• mpc-fade combines and builds on gists by koppi and Pablo1107.
• playpause is based on a gist by fernandotakai.
• mpdmark is based on mpdmark from Mic92/mpdtools.
• alarmpd is based on alarmpd by Ingo Becker.
• mpd-kb-control is based on mpd_kb_control by nogaems.
• mpd-auto-stop is based on mpd_auto_stop by Meenakshi Sundaram V.
• add-current-song and mpd-random-album are derived from Alejandro-Roldan/mpc-scripts; mpd-random-album's recent-albums cache was additionally inspired by ibeex/mpd_queue_random_album.
• mpd-usb-automount is based on a gist by daks.
• Documentation updates assisted by Claude.

License

This project is licensed under the GNU General Public License v3.0.

See LICENSE for more information.