Emacs user interface for Music Player Daemon (https://www.musicpd.org/), a flexible, powerful, server-side application for playing music.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.org 11KB

2 years ago
2 years ago
2 years ago
6 months ago
2 years ago
6 months ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
6 months ago
4 months ago
6 months ago
2 years ago
6 months ago
6 months ago
2 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. * MPDel
  2. #+BEGIN_HTML
  3. <p>
  4. <a href="https://stable.melpa.org/#/mpdel">
  5. <img alt="MELPA Stable" src="https://stable.melpa.org/packages/mpdel-badge.svg"/>
  6. </a>
  7. <a href="https://melpa.org/#/mpdel">
  8. <img alt="MELPA" src="https://melpa.org/packages/mpdel-badge.svg"/>
  9. </a>
  10. <a href="https://gitlab.petton.fr/mpdel/mpdel/commits/master">
  11. <img alt="pipeline status" src="https://gitlab.petton.fr/mpdel/mpdel/badges/master/pipeline.svg" />
  12. </a>
  13. </p>
  14. #+END_HTML
  15. ** Summary
  16. MPDel is an Emacs client for [[https://www.musicpd.org/][Music Player Daemon]] (MPD), a flexible,
  17. powerful, server-side application for playing music. MPDel provides an
  18. Emacs user interface to control playback (play, pause, next, volume
  19. up…) and to display and control the current playlist as well as your
  20. stored playlists (e.g., "my favorites", "wake me up", "make me dance",
  21. …).
  22. This is a screenshot of the MPDel music browser and the current
  23. playlist buffer with the currently-playing song:
  24. [[file:media/mpdel-browser.png]]
  25. MPDel can show information about the currently playing song or any
  26. other song:
  27. [[file:media/mpdel-song.png]]
  28. With the additional package [[https://gitlab.petton.fr/mpdel/ivy-mpdel.git][ivy-mpdel]], you can navigate your music
  29. database and add songs to playlists with completion:
  30. [[file:media/ivy-mpdel.png]]
  31. ** Installing
  32. Get mpdel from [[https://melpa.org/#/mpdel][melpa]] or [[https://stable.melpa.org/#/mpdel][melpa stable]]. You also need to install
  33. [[https://gitlab.petton.fr/mpdel/libmpdel][libmpdel]].
  34. You need to install and (quickly) configure an [[https://www.musicpd.org/][MPD server]] if you don't
  35. have any yet. Don't worry, that's simple and you won't regret it.
  36. ** Using
  37. Start by adding these lines to your ~init.el~ file:
  38. #+BEGIN_SRC emacs-lisp
  39. (add-to-list 'load-path "~/.emacs.d/lib/mpdel")
  40. (require 'mpdel)
  41. (mpdel-mode)
  42. #+END_SRC
  43. Then, press ~C-x Z l~ to show the current playlist. The ~C-x Z~ global
  44. prefix is configurable with ~mpdel-prefix-key~:
  45. #+BEGIN_SRC emacs-lisp
  46. (setq mpdel-prefix-key (kbd "C-. z"))
  47. #+END_SRC
  48. The following MPDel keybindings are available globally if ~mpdel-mode~
  49. is active:
  50. | *Binding* | *Action* |
  51. |-----------+---------------------------------------------------------|
  52. | ~C-x Z SPC~ | toggle between play and pause |
  53. | ~C-x Z M-n~ | play next song |
  54. | ~C-x Z M-p~ | play previous song |
  55. | ~C-x Z P~ | restart playing current song |
  56. | ~C-x Z l~ | open the current playlist |
  57. | ~C-x Z L~ | show stored playlists |
  58. | ~C-x Z N~ | navigate your database from artists |
  59. | ~C-x Z :~ | navigate your database from the browser |
  60. | ~C-x Z v~ | view current song |
  61. | ~C-x Z s r~ | search songs by artist name |
  62. | ~C-x Z s l~ | search songs by album name |
  63. | ~C-x Z s s~ | search songs by song title |
  64. | ~C-x Z f~ | go forward current song by ~mpdel-song-normal-increment~ |
  65. | ~C-x Z F~ | go forward current song by ~mpdel-song-small-increment~ |
  66. | ~C-x Z M-f~ | go forward current song by ~mpdel-song-large-increment~ |
  67. | ~C-x Z b~ | go backward current song by ~mpdel-song-normal-decrement~ |
  68. | ~C-x Z B~ | go backward current song by ~mpdel-song-small-decrement~ |
  69. | ~C-x Z M-b~ | go backward current song by ~mpdel-song-large-decrement~ |
  70. The last component of each keybinding can also be pressed in any MPDel
  71. buffer (e.g., press ~M-n~ in a playlist buffer to play the next song)
  72. to do the same. Additionally, the following keybindings are available
  73. in all MPDel buffers where they make sense:
  74. | *Binding* | *Action* |
  75. |---------+--------------------------------------|
  76. | ~a~ | add item to current playlist |
  77. | ~A~ | add item to a stored playlist |
  78. | ~r~ | replace current playlist with item |
  79. | ~R~ | replace a stored playlist with item |
  80. | ~P~ | play selected items immediately |
  81. | ~v~ | view currently played song |
  82. | ~RET~ | open a buffer showing item at point |
  83. | ~^~ | open item's parent |
  84. | ~C-x C-j~ | open a dired buffer on item at point |
  85. | ~n~ | move to next line |
  86. | ~p~ | move to previous line |
  87. Opening a dired buffer on the item at point requires configuring
  88. ~libmpdel-music-directory~ first.
  89. *** Navigator
  90. The keybinding ~C-x Z N~ (or just ~N~ in any MPDel buffer) opens a
  91. navigator on your database. You first get a list of all artists. From
  92. there, you can press ~a~, ~A~, ~r~ or ~R~ (see above) to add the item
  93. at point to a playlist. You can also press ~RET~ (the ~enter~ key) to
  94. "dive" into the selected item and display a list of the artist's
  95. albums. On the contrary, press ~^~ to go back to the item's parent
  96. (e.g., artist of the album at point). Keybindings are also available
  97. here to add albums to a playlist or dive into an album's songs. Diving
  98. into a song displays some information about it.
  99. *** Playlists
  100. Playlist buffers display either the current playlist (~C-x Z l~ or
  101. just ~l~) or any stored playlist (~C-x Z L~ or just ~L~). A playlist
  102. buffer lists songs and can be edited.
  103. Here is a list of keybindings available for the current playlist
  104. buffer:
  105. | *Binding* | *Action* |
  106. |---------+------------------------------------------|
  107. | ~C-x C-s~ | save current playlist in a new one |
  108. | ~m~ | mark the song at point |
  109. | ~k~ | remove marked song(s) from the playlist |
  110. | ~M-up~ | move marked song(s) up in the playlist |
  111. | ~M-down~ | move marked song(s) down in the playlist |
  112. When a command acts on the marked song(s) (such as ~k~), the song at
  113. point is used if there is no marked song.
  114. Playlist buffers are refreshed automatically when the MPD server
  115. refreshes them.
  116. *** Browser
  117. The MPDel Browser offers an overview of MPDel entry points (see above
  118. for a screenshot). To access the browser's top-level buffer, press
  119. ~C-x Z :~ (or call the interactive command ~mpdel-browser-open~). By
  120. default, the top level buffer gives you access to your music
  121. directory, as well as the artist and albums navigators, playlists and
  122. available searches. Pressing ~RET~ on any line will open the
  123. corresponding item. In particular, ~Music directory~ will let you to
  124. navigate across directories: beyond local directories, some MPD
  125. servers, such as Mopidi, map remote services to virtual directories.
  126. Regular MPDel keybindings work in the browser too.
  127. *** Song
  128. Song buffers display information about a song, either the currently
  129. played one (~C-x Z v~ or just ~v~) or the song at point (with
  130. ~V~). When displaying the currently played song, the buffer also shows
  131. playback status (e.g., "Currently playing") and current playback
  132. position in song (e.g., "02:32 / 06:01"). Press ~^~ to open a
  133. navigator on the song's album.
  134. ** Customizing
  135. By default, MPDel just works and you don't have to customize
  136. anything. Nevertheless, there are a few customization options if you
  137. are that kind of person (and you probably are 😄).
  138. *** Browser
  139. It is possible to customize the layout of the browser's top-level
  140. buffer via the variable ~mpdel-browser-top-level-entries~, and to filter
  141. or rearrange how children buffers show their contents with
  142. ~mpdel-browser-list-clean-up-function~. Please see the customization
  143. group ~mpdel-browser~ for more details.
  144. *** Communication with MPD
  145. If you have only one MPD server, you can tell libmpdel how to
  146. communicate with it through the options ~libmpdel-hostname~ and
  147. ~libmpdel-port~. If you have more than one server, configure them in
  148. ~libmpdel-profiles~. In this case, change the active server profile
  149. with ~M-x libmpdel-connect-profile~.
  150. *** Keyboard
  151. As discussed above, you might want to configure ~mpdel-prefix-key~ to
  152. control which global keybinding gives you access to MPDel. This prefix
  153. key is active when ~mpdel-mode~ is active.
  154. There are several keybinding tables (i.e., keymaps) to modify to your
  155. taste:
  156. | *Keymap variable* | *Description* |
  157. |---------------------------+----------------------------------------|
  158. | ~mpdel-core-map~ | active globally |
  159. | ~mpdel-nav-mode-map~ | active in navigators |
  160. | ~mpdel-playlist-mode-map~ | active in current and stored playlists |
  161. | ~mpdel-song-mode-map~ | active in song buffers |
  162. *** Faces
  163. MPDel defines several faces to customize the playlists:
  164. | *Face name* | *Description* |
  165. |------------------------------------+-----------------------|
  166. | ~mpdel-playlist-current-song-face~ | currently-played song |
  167. | ~mpdel-tablist-song-name-face~ | song names |
  168. | ~mpdel-tablist-track-face~ | track numbers |
  169. | ~mpdel-tablist-album-face~ | album names |
  170. | ~mpdel-tablist-disk-face~ | disk numbers |
  171. | ~mpdel-tablist-date-face~ | dates |
  172. | ~mpdel-tablist-artist-face~ | artist names |
  173. *** Hooks
  174. You can add functions to the hooks below to get your code executed on
  175. a particular occasion:
  176. | *Hook name* | *Occasion* |
  177. |------------------------------------------+----------------------------------------------------|
  178. | ~libmpdel-current-playlist-changed-hook~ | when the current playlist is modified |
  179. | ~libmpdel-stored-playlist-changed-hook~ | when a stored playlist is modified |
  180. | ~libmpdel-player-changed-hook~ | when the player status changes (start, stop, seek) |
  181. | ~libmpdel-current-song-changed-hook~ | when the current song changes |
  182. *** Extras
  183. If your music files are hosted on the computer where MPDel is running,
  184. you can configure ~libmpdel-music-directory~ to navigate to a music
  185. file with ~C-x C-j~ from any MPDel buffer.
  186. ** Filter Expressions
  187. The command ~mpdel-core-search-by-filter~ can be used to search for
  188. songs using a [[https://www.musicpd.org/doc/html/protocol.html#filters][MPD filter expression]].
  189. This requires a MPD version >= 0.21.
  190. ** License
  191. See [[file:COPYING][COPYING]]. Copyright (c) 2018 Damien Cassou.
  192. #+BEGIN_HTML
  193. <a href="https://liberapay.com/DamienCassou/donate">
  194. <img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg">
  195. </a>
  196. #+END_HTML
  197. # LocalWords: MPDel MPD minibuffer dired keymap keymaps