Emus
====

Emus aims to provde an uncomplicated mp3 music playback system
for GNU Emacs.  In contrast to other systems such as EMS,
emus favours simplicity and ease of configuration over large
numbers of features.

Assuming you have a collection of mp3 files located within a
directory tree, emus will:

- scan all files and extract ID3 tags,
- provide a browser buffer with songs organized by artist
  and album from which songs can be selected for playback,
- provide a number of playback functions which can (for example)
  be bound to global keys and used to select and play songs
  without opening the browser buffer.

Emus does not support custom playlists, as the author has never
found them useful.

Emus plays nicely with Evil mode.


Requirements
------------

Besides a recent version of GNU Emacs, Emus requires
mpg123 (https://mpg123.de/).  All of emus' functions are
implemented using the "remote" mode of this program.


Installation
------------

To install emus, simply add the file "emus.el" to a directory
contained in your emacs `load-path`, then add the following to your
init.el file:

    (require 'emus)

Emus should then be available on restarting emacs.  (You can also
evaluate it directly by placing the cursor immediately following the
closing parenthesis and using `C-x e` to make emus available
immediately.)


Configuration
-------------

By default, emus expects your music to be found in "~/Music".
This location can be changed by customizing the value of the
`emus-directory`.

Similarly, emus expects to find the mpg123 program in the execution path.
If your copy of mpg123 is named differently or located somewhere outside
the directories listed in the PATH environment variable, you'll need to
specify its location using the customization variable `emus-mpg123-program`.

These variables, together with the faces used for the various components
of the browser buffer can be customized via the `emus` customization group.
(To configure these, use `M-x customize-group RET emus RET`.)

Usage
-----

To open the emus song browser, use `M-x emus-browse`.  Songs can be selected
for playback from this list by clicking their titles with the mouse cursor
(if available) or by moving point over the title and pressing `RET`.  Playback
can be paused using the spacebar, the next/previous songs can be selected
using the `n` and `p` keys.  Similarly you can navigate between albums using
`N` and `P`.

You can see the full list of keys available for playback control by using
`C-h m` with the browser buffer selected.  This help window also lists the
interactive functions which control the playback.  Creating global bindings
for these functions will allow you to control the playback from anywhere
within emacs.

Outside of the browser buffer, `M-x emus-display-status` can be used
to show the name of the currently selected/playing song as well as the
current volume.

Enabling/disabling Progress Tracking
------------------------------------

By default, emus uses the mpg123 output to keep track of the progress
through a track, and to listen to Icecast stream updates.  However,
this can cause glitches in the audio on some systems if Emacs (running
in GUI mode) looses focus for extended periods.  As a work-around it is
possible to toggle progress tracking using `M-x emus-progress-tracking`
which, inside the browser, is bound to `!`.

Example Hydra Configuration
---------------------------

The wonderful Hyrdra package (https://github.com/abo-abo/hydra) can be used to
easily invoke emus commands outside of the emus-browser without needing to
create more than a single emus-specific global binding.

The following example is from my own init.el configuration:

   (defhydra hydra-ecmus (:color red :hint nil
                                 :pre (emus-display-status)
                                 :post (message nil))
     "
  Volume: _-_/[_+__=_] Tracks: _p_/_P_ _n_/_N_ (prev/next track/album) Progress: _#_
  Playback: _SPC_ (play/pause) _o_ (stop) _,_/_._ (skip +/-)  Browse: _b_ Restart: _!_
  "
      ("<ESC>" "quit" :color blue)
      ("q" "quit" :color blue)
      ("RET" "quit" :color blue)
      ("SPC" emus-playpause-status)
      ("p" emus-play-prev-status)
      ("n" emus-play-next-status)
      ("P" emus-play-prev-album-status)
      ("N" emus-play-next-album-status)
      ("," emus-jump-10s-backward-status)
      ("." emus-jump-10s-forward-status)
      ("<" emus-jump-1m-backward-status)
      (">" emus-jump-1m-forward-status)
      ("-" emus-volume-down-status)
      ("+" emus-volume-up-status)
      ("=" emus-volume-up-status)
      ("o" emus-stop-status)
      ("!" emus-restart-status)
      ("#" emus-toggle-progress-status)
      ("b" emus-browse :color blue))

    (bind-key* (kbd "s-m") 'hydra-ecmus/body)

License
-------

Emus is free software and is distributed under the terms of version 3
the GNU General Public License, which can be found in the file named
COPYING.