#+TITLE: mpdmacs
#+DESCRIPTION: A lightweight, ergonomic MPD client for Emacs
#+DATE: <2026-10-02 Fri 10:41>
#+AUTODATE: t
#+AUTHOR: sp1ff
#+EMAIL: <sp1ff@pobox.com>
#+OPTIONS: toc:nil org-md-headline-style:setext *:t num:nil ^:{}
#+LATEX_HEADER: \usepackage{float}
#+LATEX_HEADER: \usepackage{amsthm}
#+STARTUP: overview

[[https://melpa.org/#/mpdmacs][file:https://melpa.org/packages/mpdmacs-badge.svg]]
[[https://stable.melpa.org/#/mpdmacs][file:https://stable.melpa.org/packages/mpdmacs-badge.svg]]
[[https://github.com/sp1ff/mpdmacs/workflows/melpazoid/badge.svg][file:https://github.com/sp1ff/mpdmacs/workflows/melpazoid/badge.svg]]


* Introduction

[[https://github.com/sp1ff/mpdmacs][mpdmacs-mode]] is a global minor-mode that turns Emacs into a lightweight, ergonomic [[https://www.musicpd.org/][MPD]] client.
* License

This package is released under the [[https://www.gnu.org/licenses/gpl-3.0.en.html][GPL v3]].
* Prerequisites

Emacs 29.1 & [[https://melpa.org/#/elmpd][elmpd]] latest.
* Installing

The simplest way to install mpdmacs is from [[https://melpa.org][MELPA]], something like:

#+BEGIN_SRC elisp
  (use-package mpdmacs
    :ensure t
    :demand t
    :custom
    (mpdmacs-host "127.0.0.1")
    (mpdmacs-port 6600)
    :config
    (mpdmacs-mode))
#+END_SRC

There's also an Emacs package available with each release: download the .tar file from [[https://github.com/sp1ff/mpdmacs/releases][Github]] or my personal [[https://www.unwoundstack/distros.html][page]] and say:

#+BEGIN_SRC elisp
  (package-install-file "mpdmacs-1.0.2.tar")
#+END_SRC

The Github [[https://github.com/sp1ff/mpdmacs/releases][releases]] also include Autotools source tarballs:

#+BEGIN_SRC bash
  curl -L -O https://github.com/sp1ff/mpdmacs/releases/download/1.0.2/mpdmacs-1.0.2.tar.gz
  tar xf mpdmacs-1.0.2.tar.gz && cd mpdmacs-1.0.2
  ./configure && make all check
  sudo make install
#+END_SRC
* Getting Started

Pull in =mpdmacs= as usual via =require=: =(require 'mpdmacs)=. Configure =mpdmacs= to connect to your MPD server by customizing the variables =mpdmacs-host=, =mpdmacs-port= and/or =mpdmacs-socket=.

At this point, =mpdmacs= has done nothing: you need to explicitly enable it by calling =(mpdmacs-mode)=. This will open a connection to your MPD server, begin monitoring its state for changes, and enable you to begin issuing commands.

If you ever want to turn =mpdmacs= off, you can invoke =(mpdmacs-mode)= again. User documentation is provided with the package, and HTML documentation may be found [[https://unwoundstack.com/doc/mpdmacs/curr][here]].
* Motivation & Design Philosophy

There are already capable MPD clients out there such as [[https://gitea.petton.fr/mpdel/mpdel][mpdel]] & [[https://github.com/emacs-mirror/emacs/blob/master/lisp/mpc.el][mpc]] so why another? I've tried both & like them fine, but they're full-featured MPD clients. I hope that =mpdmacs= will fill a different role, that of an unobtrusive assistant while you're using Emacs for other things. If you want to, say, display & edit the current play queue, you would go to one of them. If you just want to skip to the next track with a quick key sequence while doing something else, use =mpdmacs=.
* Status & Roadmap

The package has intermittently evolved since 2020, but in the fall of 2024 I called this "1.0". Comments, suggestions & bug reports welcome in the [[https://github.com/sp1ff/mpdmacs/issues][issues]] or at [[mailto:sp1ff@pobox.com][sp1ff@pobox.com]].
