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 Example Hydra Configuration
  85 ---------------------------
  86
  87 The wonderful Hyrdra package (https://github.com/abo-abo/hydra) can be used to
  88 easily invoke emus commands outside of the emus-browser without needing to
  89 create more than a single emus-specific global binding.
  90
  91 The following example is from my own init.el configuration:
  92
  93     (defhydra hydra-ecmus (:color red :hint nil
  94                                     :pre (emus-display-status)
  95                                     :post (message nil))
  96         "
  97     Volume: _-_/[_+__=_] (down/up)  Tracks: _p_/_P_ (prev track/album) _n_/_N_ (next track/album)
  98     Playback: _SPC_ (play/pause) _o_ (stop) _,_/_._ (skip forward/backward)  Browser: _b_ (open browser)
  99     "
 100         ("<ESC>" "quit" :color blue)
 101         ("q" "quit" :color blue)
 102         ("RET" "quit" :color blue)
 103         ("SPC" emus-playpause-status)
 104         ("p" emus-play-prev-status)
 105         ("n" emus-play-next-status)
 106         ("P" emus-play-prev-album-status)
 107         ("N" emus-play-next-album-status)
 108         ("," emus-jump-10s-backward-status)
 109         ("." emus-jump-10s-forward-status)
 110         ("-" emus-volume-down-status)
 111         ("+" emus-volume-up-status)
 112         ("=" emus-volume-up-status)
 113         ("o" emus-stop-status)
 114         ("b" emus-browse :color blue))
 115
 116     (bind-key* (kbd "s-m") 'hydra-ecmus/body)
 117
 118
 119 License
 120 -------
 121
 122 Emus is free software and is distributed under the terms of version 3
 123 the GNU General Public License, which can be found in the file named
 124 COPYING.