README

   1 Emus
   2 ====
   3
   4 Emus aims to provde an uncomplicated mp3 music playback system
   5 for GNU Emacs.  In contrast to other systems such as EMS,
   6 emus favours simplicity and ease of configuration over large
   7 numbers of features.
   8
   9 Assuming you have a collection of mp3 files located within a
  10 directory tree, emus will:
  11
  12 - scan all files and extract ID3 tags,
  13 - provide a browser buffer with songs organized by artist
  14   and album from which songs can be selected for playback,
  15 - provide a number of playback functions which can (for example)
  16   be bound to global keys and used to select and play songs
  17   without opening the browser buffer.
  18
  19 Emus does not support custom playlists, as the author has never
  20 found them useful.
  21
  22 Emus plays nicely with Evil mode.
  23
  24
  25 Requirements
  26 ------------
  27
  28 Besides a recent version of GNU Emacs, Emus requires
  29 mpg123 (https://mpg123.de/).  All of emus' functions are
  30 implemented using the "remote" mode of this program.
  31
  32
  33 Installation
  34 ------------
  35
  36 To install emus, simply add the file "emus.el" to a directory
  37 contained in your emacs `load-path`, then add the following to your
  38 init.el file:
  39
  40     (require 'emus)
  41
  42 Emus should then be available on restarting emacs.  (You can also
  43 evaluate it directly by placing the cursor immediately following the
  44 closing parenthesis and using `C-x e` to make emus available
  45 immediately.)
  46
  47
  48 Configuration
  49 -------------
  50
  51 By default, emus expects your music to be found in "~/Music".
  52 This location can be changed by customizing the value of the
  53 `emus-directory`.
  54
  55 Similarly, emus expects to find the mpg123 program in the execution path.
  56 If your copy of mpg123 is named differently or located somewhere outside
  57 the directories listed in the PATH environment variable, you'll need to
  58 specify its location using the customization variable `emus-mpg123-program`.
  59
  60 These variables, together with the faces used for the various components
  61 of the browser buffer can be customized via the `emus` customization group.
  62 (To configure these, use `M-x customize-group RET emus RET`.)
  63
  64 Usage
  65 -----
  66
  67 To open the emus song browser, use `M-x emus-browse`.  Songs can be selected
  68 for playback from this list by clicking their titles with the mouse cursor
  69 (if available) or by moving point over the title and pressing `RET`.  Playback
  70 can be paused using the spacebar, the next/previous songs can be selected
  71 using the `n` and `p` keys.  Similarly you can navigate between albums using
  72 `N` and `P`.
  73
  74 You can see the full list of keys available for playback control by using
  75 `C-h m` with the browser buffer selected.  This help window also lists the
  76 interactive functions which control the playback.  Creating global bindings
  77 for these functions will allow you to control the playback from anywhere
  78 within emacs.
  79
  80 Outside of the browser buffer, `M-x emus-display-status` can be used
  81 to show the name of the currently selected/playing song as well as the
  82 current volume.
  83
  84 Enabling/disabling Progress Tracking
  85 ------------------------------------
  86
  87 By default, emus uses the mpg123 output to keep track of the progress
  88 through a track, and to listen to Icecast stream updates.  However,
  89 this can cause glitches in the audio on some systems if Emacs (running
  90 in GUI mode) looses focus for extended periods.  As a work-around it is
  91 possible to toggle progress tracking using `M-x emus-progress-tracking`
  92 which, inside the browser, is bound to `!`.
  93
  94 Example Hydra Configuration
  95 ---------------------------
  96
  97 The wonderful Hyrdra package (https://github.com/abo-abo/hydra) can be used to
  98 easily invoke emus commands outside of the emus-browser without needing to
  99 create more than a single emus-specific global binding.
 100
 101 The following example is from my own init.el configuration:
 102
 103    (defhydra hydra-ecmus (:color red :hint nil
 104                                  :pre (emus-display-status)
 105                                  :post (message nil))
 106      "
 107   Volume: _-_/[_+__=_] Tracks: _p_/_P_ _n_/_N_ (prev/next track/album) Progress: _#_
 108   Playback: _SPC_ (play/pause) _o_ (stop) _,_/_._ (skip +/-)  Browse: _b_ Restart: _!_
 109   "
 110       ("<ESC>" "quit" :color blue)
 111       ("q" "quit" :color blue)
 112       ("RET" "quit" :color blue)
 113       ("SPC" emus-playpause-status)
 114       ("p" emus-play-prev-status)
 115       ("n" emus-play-next-status)
 116       ("P" emus-play-prev-album-status)
 117       ("N" emus-play-next-album-status)
 118       ("," emus-jump-10s-backward-status)
 119       ("." emus-jump-10s-forward-status)
 120       ("<" emus-jump-1m-backward-status)
 121       (">" emus-jump-1m-forward-status)
 122       ("-" emus-volume-down-status)
 123       ("+" emus-volume-up-status)
 124       ("=" emus-volume-up-status)
 125       ("o" emus-stop-status)
 126       ("!" emus-restart-status)
 127       ("#" emus-toggle-progress-status)
 128       ("b" emus-browse :color blue))
 129
 130     (bind-key* (kbd "s-m") 'hydra-ecmus/body)
 131
 132 License
 133 -------
 134
 135 Emus is free software and is distributed under the terms of version 3
 136 the GNU General Public License, which can be found in the file named
 137 COPYING.