From 13bc139bc57863387d13d574e6a7a7bdab250233 Mon Sep 17 00:00:00 2001 From: Tim Vaughan Date: Wed, 11 Dec 2019 21:10:30 +0100 Subject: [PATCH] Added readme. --- README | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 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) + " + ("" "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. -- 2.20.1