ampc

Homepage: https://elpa.gnu.org/packages/ampc.html

Author: Christopher Schmidt

Updated:

Summary

Asynchronous Music Player Controller

Commentary

* description
ampc is a controller for the Music Player Daemon (https://mpd.wikia.com/).

** installation
If you use GNU ELPA, install ampc via M-x package-list-packages RET or
(package-install 'ampc).  Otherwise, grab the files in this repository and
put the Emacs Lisp ones somewhere in your load-path or add the directory the
files are in to it, e.g.:

(add-to-list 'load-path "~/.emacs.d/ampc")
(autoload 'ampc "ampc" nil t)

Byte-compile ampc (M-x byte-compile-file RET /path/to/ampc.el RET) to improve
its performance!

*** tagger
ampc is not only a frontend to MPD but also a full-blown audio file tagger.
To use this feature you have to build the backend application, `ampc_tagger',
which in turn uses TagLib (https://taglib.github.com/), a dual-licended
(LGPL/MPL) audio meta-data library written in C++.  TagLib has no
dependencies on its own.

To build `ampc_tagger', locate ampc_tagger.cpp.  The file can be found in the
directory in which this file, ampc.el, is located.  Compile the file and
either customize `ampc-tagger-executable' to point to the binary file or move
the executable in a suitable directory so Emacs finds it via consulting
`exec-path'.

g++ -O2 ampc_tagger.cpp -oampc_tagger -ltag && sudo cp ampc_tagger /usr/local/bin && rm ampc_tagger

You have to customize `ampc-tagger-music-directories' in order to use the
tagger.  This variable should be a list of directories in which your music
files are located.  Usually this list should have only one entry, the value
of your mpd.conf's `music_directory'.

If `ampc-tagger-backup-directory' is non-nil, the tagger saved copies of all
files that are about to be modified to this directory.  Emacs's regular
numeric backup filename syntax is used for the backup file names.  By default
`ampc-tagger-backup-directory' is set to "~/.emacs.d/ampc-backups/".

** usage
To invoke ampc call the command `ampc', e.g. via M-x ampc RET.  The first
argument to `ampc' is the host, the second is the port.  Both values default
to nil.  If nil, ampc will use the value specified in `ampc-default-server',
by default localhost:6600.  To make ampc use the full frame rather than the
selected window for its window setup, customise `ampc-use-full-frame' to a
non-nil value.

ampc offers independent views which expose different parts of the user
interface.  The current playlist view, the default view at startup, may be
accessed using the `J' key (that is `S-j').  The playlist view may be
accessed using the `K' key.  The outputs view may be accessed by pressing
`L'. The search view may be accessed using the `F' key (find).

*** current playlist view
The playlist view looks like this:

.........................
. 1      . 3  . 4  . 5  .
..........    .    .    .
. 2      .    .    .    .
.        .    .    .    .
.        .    .    .    .
.        ................
.        . 6            .
.        .              .
.........................

Window one exposes basic information about the daemon, such as the current
state (stop/play/pause), the song currently playing or the volume.

All windows, except the status window, contain a tabular list of items.  Each
item may be selected/marked.  There may be multiple selections.

To mark an entry, move the point to the entry and press `m' (ampc-mark).  To
unmark an entry, press `u' (ampc-unmark).  To unmark all entries, press `U'
(ampc-unmark-all).  To toggle marks, press `t' (ampc-toggle-marks).  Pressing
`' with the mouse mouse cursor on a list entry will move point
to the entry and toggle the mark.  To navigate to the next entry, press `n'
(ampc-next-line).  Analogous, pressing `p' (ampc-previous-line) moves the
point to the previous entry.

Window two shows the current playlist.  The song that is currently played by
the daemon, if any, is highlighted.  To delete the selected songs from the
playlist, press `d' (ampc-delete).  Pressing `' will move the
point to the entry under cursor and delete it from the playlist.  To move the
selected songs up, press `' (ampc-up).  Analogous, press `'
(ampc-down) to move the selected songs down.  Pressing `RET'
(ampc-play-this) or `' will play the song at point/cursor.

Windows three to five are tag browsers.  You use them to narrow the song
database to certain songs.  Think of tag browsers as filters, analogous to
piping `grep' outputs through additional `grep' filters.  The property of the
songs that is filtered is displayed in the header line of the window.

Window six shows the songs that match the filters defined by windows three to
five.  To add the selected song to the playlist, press `a' (ampc-add).
Pressing `' will move the point to the entry under the cursor
and execute `ampc-add'.  These key bindings works in tag browsers as well.
Calling `ampc-add' in a tag browser adds all songs filtered up to the
selected browser to the playlist.

The tag browsers of the current playlist view (accessed via `J') are `Genre'
(window 3), `Artist' (window 4) and `Album' (window 5).  The key `M' may be
used to fire up a slightly modified current playlist view.  There is no
difference to the default current playlist view other than that the tag
browsers filter to `Genre' (window 3), `Album' (window 4) and `Artist'
(window 5).  Metaphorically speaking, the order of the `grep' filters defined
by the tag browsers is different.

*** playlist view
The playlist view resembles the current playlist view.  The window, which
exposes the playlist content, is replaced by three windows, vertically
arragned, though.  The top one still shows the current playlist.  The bottom
one shows a list of stored playlists.  The middle window exposes the content
of the selected (stored) playlist.  All commands that used to work in the
current playlist view and modify the current playlist now modify the selected
(stored) playlist unless the point is within the current playlist buffer.
The list of stored playlists is the only view in ampc that may have only one
marked entry.

To queue a playlist, press `l' (ampc-load) or `'.  To delete a
playlist, press `d' (ampc-delete-playlist) or `'.  The command
`ampc-rename-playlist', bound to `r', can be used to rename a playlist.

Again, the key `<' may be used to setup a playlist view with a different
order of tag browsers.

*** outputs view
The outputs view contains a single list which shows the configured outputs of
MPD.  To toggle the enabled property of the selected outputs, press `a'
(ampc-toggle-output-enabled) or `'.

*** search view
The search view contains the result of the last performed search. You can
start a new search with the `s' key while in the search view or use M-x
ampc-start-search. Use the `a' key to add a song displayed in result list.

** tagger
To start the tagging subsystem, press `I' (ampc-tagger).  This key binding
works in every buffer associated with ampc.  First, the command tries to
determine which files you want to tag.  The files are collected using either
the selected entries within the current buffer, the file associated with the
entry at point, or, if both sources did not provide any files, the audio file
that is currently played by MPD.  Next, the tagger view is created.  On the
right there is the buffer that contain the tag data.  Each line in this
buffer represents a tag with a value.  Tag and value are separated by a
colon.  Valid tags are "Title", "Artist", "Album", "Comment", "Genre", "Year"
and "Track".  The value can be an arbitrary string.  Whitespaces in front and
at the end of the value are ignored.  If the value is "", the tag line
is ignored.

To save the specified tag values back to the files, press `C-c C-c'
(ampc-tagger-save).  To exit the tagger and restore the previous window
configuration, press `C-c C-q'.  `C-u C-c C-c' saved the tags and exits the
tagger.  Only tags that are actually specified within the tagger buffer
written back to the file.  Other tags will not be touched by ampc.  For
example, to clear the "Commentary" tag, you need to specify the line

Commentary:

In the tagger buffer.  Omitting this line will make the tagger not touch the
"Commentary" tag at all.

On the right there is the files list buffer.  The selection of this buffer
specifies which files the command `ampc-tag-save' will write to.  If no file
is selected, the file at point in the file list buffer is used.

To reset the values of the tags specified in the tagger buffer to the common
values of all selected files specified by the selection of the files list
buffer, press `C-c C-r' (ampc-tagger-reset).  With a prefix argument,
`ampc-tagger-reset' restores missing tags as well.

You can use tab-completion within the tagger buffer for both tags and tag
values.

You can also use the tagging subsystem on its own without a running ampc
instance.  To start the tagger, call `ampc-tag-files'.  This function accepts
one argument, a list of absolute file names which are the files to tag.  ampc
provides a minor mode for dired, `ampc-tagger-dired-mode'.  If this mode is
enabled within a dired buffer, pressing `C-c C-t' (ampc-tagger-dired) will
start the tagger on the current selection.

The following ampc-specific hooks are run during tagger usage:

`ampc-tagger-grab-hook': Run by the tagger before grabbing tags of a file.
Each function is called with one argument, the file name.

`ampc-tagger-grabbed-hook': Run by the tagger after grabbing tags of a file.
Each function is called with one argument, the file name.

`ampc-tagger-store-hook': Run by the tagger before writing tags back to a
file.  Each function is called with two arguments, FOUND-CHANGED and DATA.
FOUND-CHANGED is non-nil if the tags that are about to be written differ from
the ones in the file.  DATA is a cons.  The car specifies the full file name
of the file that is about to be written to, the cdr is an alist that
specifies the tags that are about to be (over-)written.  The car of each
entry in this list is a symbol specifying the tag (one of the ones in
`ampc-tagger-tags'), the cdr a string specifying the value.  The cdr of DATA
may be modified.  If FOUND-CHANGED is nil and the cdr of DATA is not modified
throughout the hook is run, the file is not touched.
`ampc-tagger-stored-hook' is still run, though.

`ampc-tagger-stored-hook': Run by the tagger after writing tags back to a
file.  Each function is called with two arguments, FOUND-CHANGED and DATA.
These are the same arguments that were already passed to
`ampc-tagger-store-hook'.  The car of DATA, the file name, may be modified.

These hooks can be used to handle vc locking and unlocking of files.  For
renaming files according to their (new) tag values, ampc provides the
function `ampc-tagger-rename-artist-title' which may be added to
`ampc-tagger-stored-hook'.  The new file name generated by this function is
"Artist"_-_"Title"."extension".  Characters within "Artist" and "Title" that
are not alphanumeric are substituted with underscores.

** global keys
Aside from `J', `M', `K', `<' and `L', which may be used to select different
views, and `I' which starts the tagger, ampc defines the following global
keys.  These binding are available in every buffer associated with ampc:

`k' (ampc-toggle-play): Toggle play state.  If MPD does not play a song,
start playing the song at point if the current buffer is the playlist buffer,
otherwise start at the beginning of the playlist.  With numeric prefix
argument 4, stop player rather than pause if applicable.

`l' (ampc-next): Play next song.
`j' (ampc-previous): Play previous song

`c' (ampc-clear): Clear playlist.
`s' (ampc-shuffle): Shuffle playlist.

`S' (ampc-store): Store playlist.
`O' (ampc-load): Load selected playlist into the current playlist.
`R' (ampc-rename-playlist): Rename selected playlist.
`D' (ampc-delete-playlist): Delete selected playlist.

`y' (ampc-increase-volume): Increase volume.
`M-y' (ampc-decrease-volume): Decrease volume.
`C-M-y' (ampc-set-volume): Set volume.
`h' (ampc-increase-crossfade): Increase crossfade.
`M-h' (ampc-decrease-crossfade): Decrease crossfade.
`C-M-h' (ampc-set-crossfade): Set crossfade.

`e' (ampc-toggle-repeat): Toggle repeat state.
`r' (ampc-toggle-random): Toggle random state.
`f' (ampc-toggle-consume): Toggle consume state.

`P' (ampc-goto-current-song): Select the current playlist window and move
point to the current song.
`G' (ampc-mini): Select song to play via `completing-read'.

`T' (ampc-trigger-update): Trigger a database update.
`Z' (ampc-suspend): Suspend ampc.
`q' (ampc-quit): Quit ampc.

The keymap of ampc is designed to fit the QWERTY United States keyboard
layout.  If you use another keyboard layout, feel free to modify
`ampc-mode-map'.  For example, I use a regular QWERTZ German keyboard
(layout), so I modify `ampc-mode-map' in my init.el like this:

(eval-after-load 'ampc
  '(flet ((substitute-ampc-key
           (from to)
           (define-key ampc-mode-map to (lookup-key ampc-mode-map from))
           (define-key ampc-mode-map from nil)))
     (substitute-ampc-key (kbd "z") (kbd "Z"))
     (substitute-ampc-key (kbd "y") (kbd "z"))
     (substitute-ampc-key (kbd "M-y") (kbd "M-z"))
     (substitute-ampc-key (kbd "C-M-y") (kbd "C-M-z"))
     (substitute-ampc-key (kbd "<") (kbd ";"))))

If ampc is suspended, you can still use every interactive command that does
not directly operate on or with the user interface of ampc.  For example it is
perfectly fine to call `ampc-increase-volume' or `ampc-toggle-play' via M-x
RET.  Especially the commands `ampc-status' and `ampc-mini' are predesignated
to be bound in the global keymap and called when ampc is suspended.
`ampc-status' messages the information that is displayed by the status window
of ampc.  `ampc-mini' lets you select a song to play via `completing-read'.
To start ampc suspended, call `ampc' with the third argument being non-nil.
To check whether ampc is connected to the daemon and/or suspended, call
`ampc-is-on-p' or `ampc-suspended-p'.

(global-set-key (kbd "")
                (lambda ()
                  (interactive)
                  (unless (ampc-on-p)
                    (ampc nil nil t))
                  (ampc-status)))
(global-set-key (kbd "")
                (lambda ()
                  (interactive)
                  (unless (ampc-on-p)
                    (ampc nil nil t))
                  (ampc-mini)))

Dependencies