Added readme.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..78e56cf
--- /dev/null
+++ b/README
@@ -0,0 +1,123 @@
+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 `emus.el` to a directory contained
+in your emacs `load-path`, then add the following to your `init.el`:
+
+    (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.
+
+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: _-_/[_+__=_] (down/up)  Tracks: _p_/_P_ (prev track/album) _n_/_N_ (next track/album)
+    Playback: _SPC_ (play/pause) _o_ (stop) _,_/_._ (skip forward/backward)  Browser: _b_ (open browser)
+    "
+        ("<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-volume-down-status)
+        ("+" emus-volume-up-status)
+        ("=" emus-volume-up-status)
+        ("o" emus-stop-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.