* MPDel

#+BEGIN_HTML
    <p>
      <a href="https://stable.melpa.org/#/mpdel">
        <img alt="MELPA Stable" src="https://stable.melpa.org/packages/mpdel-badge.svg"/>
      </a>

      <a href="https://melpa.org/#/mpdel">
        <img alt="MELPA" src="https://melpa.org/packages/mpdel-badge.svg"/>
      </a>

      <a href="https://github.com/mpdel/mpdel/actions">
        <img alt="pipeline status" src="https://github.com/mpdel/mpdel/actions/workflows/test.yml/badge.svg" />
      </a>
    </p>
#+END_HTML

** Summary

MPDel is an Emacs client for [[https://www.musicpd.org/][Music Player Daemon]] (MPD), a flexible,
powerful, server-side application for playing music. MPDel provides an
Emacs user interface to control playback (play, pause, next, volume
up…) and to display and control the current playlist as well as your
stored playlists (e.g., "my favorites", "wake me up", "make me dance",
…).

This is a screenshot of the MPDel music browser and the current
playlist buffer with the currently-playing song:

[[file:media/mpdel-browser.png]]

MPDel can show information about the currently playing song or any
other song:

[[file:media/mpdel-song.png]]

With the additional package [[https://github.com/mpdel/ivy-mpdel.git][ivy-mpdel]] or [[https://github.com/mpdel/mpdel-embark][mpdel-embark]] you can navigate
your music database and add songs to playlists with completion:

[[file:media/ivy-mpdel.png]]

** Installing

Get mpdel from [[https://melpa.org/#/mpdel][melpa]] or [[https://stable.melpa.org/#/mpdel][melpa stable]]. You also need to install
[[https://github.com/mpdel/libmpdel][libmpdel]].

You need to install and (quickly) configure an [[https://www.musicpd.org/][MPD server]] if you don't
have any yet. Don't worry, that's simple and you won't regret it.

** Using

Start by adding these lines to your ~init.el~ file:

#+BEGIN_SRC emacs-lisp
  (add-to-list 'load-path "~/.emacs.d/lib/mpdel")
  (require 'mpdel)
  (mpdel-mode)
#+END_SRC

Then, press ~C-x Z l~ to show the current playlist. The ~C-x Z~ global
prefix is configurable with ~mpdel-prefix-key~:

#+BEGIN_SRC emacs-lisp
  (setq mpdel-prefix-key (kbd "C-. z"))
#+END_SRC

The following MPDel keybindings are available globally if ~mpdel-mode~
is active:

| *Binding*   | *Action*                                                  |
|-------------+-----------------------------------------------------------|
| ~C-x Z SPC~ | toggle between play and pause                             |
| ~C-x Z M-n~ | play next song                                            |
| ~C-x Z M-p~ | play previous song                                        |
| ~C-x Z P~   | restart playing current song                              |
| ~C-x Z l~   | open the current playlist                                 |
| ~C-x Z L~   | show stored playlists                                     |
| ~C-x Z N~   | navigate your database from artists                       |
| ~C-x Z :~   | navigate your database from the browser                   |
| ~C-x Z v~   | view current song                                         |
| ~C-x Z s r~ | search songs by artist name                               |
| ~C-x Z s l~ | search songs by album name                                |
| ~C-x Z s s~ | search songs by song title                                |
| ~C-x Z f~   | go forward current song by ~mpdel-song-normal-increment~  |
| ~C-x Z F~   | go forward current song by ~mpdel-song-small-increment~   |
| ~C-x Z M-f~ | go forward current song by ~mpdel-song-large-increment~   |
| ~C-x Z b~   | go backward current song by ~mpdel-song-normal-decrement~ |
| ~C-x Z B~   | go backward current song by ~mpdel-song-small-decrement~  |
| ~C-x Z M-b~ | go backward current song by ~mpdel-song-large-decrement~  |

The last component of each keybinding can also be pressed in any MPDel
buffer (e.g., press ~M-n~ in a playlist buffer to play the next song)
to do the same.  Additionally, the following keybindings are available
in all MPDel buffers where they make sense:

| *Binding* | *Action*                             |
|-----------+--------------------------------------|
| ~a~       | add item to current playlist         |
| ~A~       | add item to a stored playlist        |
| ~r~       | replace current playlist with item   |
| ~R~       | replace a stored playlist with item  |
| ~P~       | play selected items immediately      |
| ~v~       | view currently played song           |
| ~RET~     | open a buffer showing item at point  |
| ~^~       | open item's parent                   |
| ~C-x C-j~ | open a dired buffer on item at point |
| ~n~       | move to next line                    |
| ~p~       | move to previous line                |
| ~+~       | increase playback volume             |
| ~-~       | decrease playback volume             |
| ~C~       | connect to a different profile       |

Opening a dired buffer on the item at point requires configuring
~libmpdel-music-directory~ first.

*** Navigator

The keybinding ~C-x Z N~ (or just ~N~ in any MPDel buffer) opens a
navigator on your database. You first get a list of all artists. From
there, you can press ~a~, ~A~, ~r~ or ~R~ (see above) to add the item
at point to a playlist. You can also press ~RET~ (the ~enter~ key) to
"dive" into the selected item and display a list of the artist's
albums. On the contrary, press ~^~ to go back to the item's parent
(e.g., artist of the album at point). Keybindings are also available
here to add albums to a playlist or dive into an album's songs. Diving
into a song displays some information about it.

*** Playlists

Playlist buffers display either the current playlist (~C-x Z l~ or
just ~l~) or any stored playlist (~C-x Z L~ or just ~L~). A playlist
buffer lists songs and can be edited.

Here is a list of keybindings available for the current playlist
buffer:

| *Binding* | *Action*                                 |
|-----------+------------------------------------------|
| ~C-x C-s~ | save current playlist in a new one       |
| ~m~       | mark the song at point                   |
| ~k~       | remove marked song(s) from the playlist  |
| ~M-up~    | move marked song(s) up in the playlist   |
| ~M-down~  | move marked song(s) down in the playlist |

When a command acts on the marked song(s) (such as ~k~), the song at
point is used if there is no marked song.

Playlist buffers are refreshed automatically when the MPD server
refreshes them.

*** Browser

The MPDel Browser offers an overview of MPDel entry points (see above
for a screenshot).  To access the browser's top-level buffer, press
~C-x Z :~ (or call the interactive command ~mpdel-browser-open~).  By
default, the top level buffer gives you access to your music
directory, as well as the artist and albums navigators, playlists and
available searches.  Pressing ~RET~ on any line will open the
corresponding item. In particular, ~Music directory~ will let you to
navigate across directories: beyond local directories, some MPD
servers, such as Mopidi, map remote services to virtual directories.

Regular MPDel keybindings work in the browser too.

*** Song

Song buffers display information about a song, either the currently
played one (~C-x Z v~ or just ~v~) or the song at point (with
~V~). When displaying the currently played song, the buffer also shows
playback status (e.g., "Currently playing") and current playback
position in song (e.g., "02:32 / 06:01"). Press ~^~ to open a
navigator on the song's album.

** Customizing

By default, MPDel just works and you don't have to customize
anything. Nevertheless, there are a few customization options if you
are that kind of person (and you probably are 😄).

*** Browser

It is possible to customize the layout of the browser's top-level
buffer via the variable ~mpdel-browser-top-level-entries~, and to filter
or rearrange how children buffers show their contents with
~mpdel-browser-list-clean-up-function~.  Please see the customization
group ~mpdel-browser~ for more details.

*** Communication with MPD

If you have only one MPD server, you can tell libmpdel how to
communicate with it through the options ~libmpdel-hostname~ and
~libmpdel-port~. If you have more than one server, configure them in
~libmpdel-profiles~. In this case, change the active server profile
with ~M-x libmpdel-connect-profile~.

*** Keyboard

As discussed above, you might want to configure ~mpdel-prefix-key~ to
control which global keybinding gives you access to MPDel. This prefix
key is active when ~mpdel-mode~ is active.

There are several keybinding tables (i.e., keymaps) to modify to your
taste:

| *Keymap variable*         | *Description*                          |
|---------------------------+----------------------------------------|
| ~mpdel-core-map~          | active globally                        |
| ~mpdel-nav-mode-map~      | active in navigators                   |
| ~mpdel-playlist-mode-map~ | active in current and stored playlists |
| ~mpdel-song-mode-map~     | active in song buffers                 |

*** Faces

MPDel defines several faces to customize the playlists:

| *Face name*                        | *Description*         |
|------------------------------------+-----------------------|
| ~mpdel-playlist-current-song-face~ | currently-played song |
| ~mpdel-tablist-song-name-face~     | song names            |
| ~mpdel-tablist-track-face~         | track numbers         |
| ~mpdel-tablist-album-face~         | album names           |
| ~mpdel-tablist-disk-face~          | disk numbers          |
| ~mpdel-tablist-date-face~          | dates                 |
| ~mpdel-tablist-artist-face~        | artist names          |

*** Hooks

You can add functions to the hooks below to get your code executed on
a particular occasion:

| *Hook name*                              | *Occasion*                                         |
|------------------------------------------+----------------------------------------------------|
| ~libmpdel-current-playlist-changed-hook~ | when the current playlist is modified              |
| ~libmpdel-stored-playlist-changed-hook~  | when a stored playlist is modified                 |
| ~libmpdel-player-changed-hook~           | when the player status changes (start, stop, seek) |
| ~libmpdel-current-song-changed-hook~     | when the current song changes                      |

*** Extras

If your music files are hosted on the computer where MPDel is running,
you can configure ~libmpdel-music-directory~ to navigate to a music
file with ~C-x C-j~ from any MPDel buffer.

** Filter Expressions

The command ~mpdel-core-search-by-filter~ can be used to search for
songs using a [[https://www.musicpd.org/doc/html/protocol.html#filters][MPD filter expression]].

This requires a MPD version >= 0.21.
** License

See [[file:COPYING][COPYING]]. Copyright (c) 2018-2023  Damien Cassou.

  #+BEGIN_HTML
  <a href="https://liberapay.com/DamienCassou/donate">
    <img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg">
  </a>
  #+END_HTML

#  LocalWords:  MPDel MPD minibuffer dired keymap keymaps