A lightweight MPD client.
This manual corresponds to mpdmacs version 1.0.0.
The Music Player Daemon (or MPD) is a “flexible, powerful, server-side application for playing music.” It offers an API for interacting with the daemon & building client applications. elmpd is a lightweight, asynchronous Emacs Lisp package for talking to an MPD instance over that protocol.
mpdmacs is an Emacs Minor Mode built on elmpd that turns Emacs into a lightweight MPD client; so lightweight, in fact, that it provides almost no user interface– merely a collection of commands & hooks that are generally available when writing code, reading mail & so forth.
Instructions for obtaining & installing the package may be found in the README. Configuration options are described below and the features offered by the minor mode are described in What the mpdmacs Minor Mode Can Do.
Before loading & enabling mpdmacs-mode, the reader will need to
configure it with the location of the MPD instance to be controlled. If
communications over TCP/IP are desired, set the following two variables:
The hostname on which MPD is listening.
The port at which MPD is listening.
If, however, the reader would prefer to communicate with MPD over its Unix socket:
The path of the Unix socket on which MPD is listening. If the TCP/IP
socket is preferred, it is best to set this to nil: mpdmacs-mode
will try the local socket first, if it exists.
mpdmacs supplies several interactive commands (see see below), with keybindings in
mpdmacs-mode-keymap;
you may want to map a chord you find
convenient to that keymap like so:
(defun my-mpdmacs-hook () (global-set-key "\C-c m" 'mpdmacs-mode-keymap)) (add-hook 'mpdmacs-mode-hook 'my-mpdmacs-hook)
Having installed & configured mpdmacs, load it as usual:
(require 'mpdmacs)
At this point, mpdmacs has done nothing: it needs to be explicitly
enabled by calling mpdmacs-mode:
Turn mpdmacs-mode on & off. Interactively, with no prefix argument, toggle the mode. A prefix argument enables the mode if the argument is positive, and disables it otherwise.
When called from Lisp, toggle the mode if the argument is toggle,
disable the mode if the argument is a non-positive integer, and enables
the mode otherwise (including if the argument is omitted or nil or a
positive integer).
Enabling the minor mode will open a connection to your MPD server, begin monitoring its state for changes, and enable the caller to begin issuing commands.
mpdmacs, in contrast to mpdel or mpc, is not a full-fledged application, but rather a global minor mode. As such, it provides no (or, at least, not a dedicated) user interface but rather a suite of commands that are available at all times; while editing code, reading email or RSS, and so on.
The most basic function of the mpdmacs minor mode is to provide a set of command for controlling MPD playback.
Begin playing the current playlist (cf. MPD command play).
Stop playback (cf. MPD command stop).
Pause or resume playback (toggles; cf. MPD command pause).
Seeks back to time zero in the current track (cf. MPD command seekcur).
Plays the next song in the current playlist (cf. MPD command next).
Plays the previous song in the current playlist (cf. MPD command previous).
Set the MPD volume to ARG, which must be an integer in the range 0-100
(cf. MPD command setvol).
Increment the MPD volume; takes a numeric prefix argument (defaults to one).
Decrement the MPD volume; takes a numeric prefix argument (defaults to one).
Toggle the state of the MPD random option.
Toggle the state of the MPD consume option.
Set the MPD crossfade option; takes a numeric prefix argument;
lacking that read the number of seconds.
Rotate through the MPD single settings: off, enabled, or
oneshot.
Rotate through the MPD replay_gain_mode settings:
Clear the current play queue.
Load the saved PLAYLIST into the queue. If invoked interactively, the stored playlist will be read interactively.
Send the current track to PLAYLIST. If invoked interactively, the target playlist will be read interactively.
mpdmacs-mode does offer a few, small, user-interface elements beyond commands & notifications.
Display information about the current song.
This command will display the information in a dedicated buffer
and display it.
mpdmacs-show-current-song-hook is run in the buffer before display.
The name of the buffer to use for current song information. The default value is “*Current Song*”.
Normal hook run before mpdmacs-show-current-song returns. The
hook will be invoked in the current song buffer.
In addition, when mpdmacs-mode is enabled, the current track will be displayed in the Emacs mode line. This can be customized or entirely disabled by customizing:
Function that will be invoked on current track change; if nil the mode line will not be updated.
mpdmacs-mode defines a few hooks that will be run on certain player changes.
Normal hook invoked when any change to the player or mixer state is detected.
Normal hook invoked when any change to the sticker database is detected.
mpdmacs was first released in late 2020 and saw intermittent development over the next few years. In the fall of 2024 I decided to finally call this “1.0”, implying a certain level of stability (and notably the project will respect semver going forward).
Bugs & feature requests are welcome in the Issues section of the project. Also, you can just reach out directly at sp1ff@pobox.com, or shoot a webmention to me at my web site.
| Jump to: | C E M N |
|---|
| Jump to: | C E M N |
|---|
| Jump to: | M P |
|---|
| Jump to: | M P |
|---|
| Jump to: | D M |
|---|
| Jump to: | D M |
|---|