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 `emus.el` to a directory contained
  37 in your emacs `load-path`, then add the following to your `init.el`:
  38
  39     (require 'emus)
  40
  41 Emus should then be available on restarting emacs.  (You can also
  42 evaluate it directly by placing the cursor immediately following the
  43 closing parenthesis and using `C-x e` to make emus available
  44 immediately.)
  45
  46
  47 Configuration
  48 -------------
  49
  50 By default, emus expects your music to be found in "~/Music".
  51 This location can be changed by customizing the value of the
  52 `emus-directory`.
  53
  54 Similarly, emus expects to find the mpg123 program in the execution path.
  55 If your copy of mpg123 is named differently or located somewhere outside
  56 the directories listed in the PATH environment variable, you'll need to
  57 specify its location using the customization variable `emus-mpg123-program`.
  58
  59 These variables, together with the faces used for the various components
  60 of the browser buffer can be customized via the `emus` customization group.
  61 (To configure these, use `M-x customize-group RET emus RET`.)
  62
  63 Usage
  64 -----
  65
  66 To open the emus song browser, use `M-x emus-browse`.  Songs can be selected
  67 for playback from this list by clicking their titles with the mouse cursor
  68 (if available) or by moving point over the title and pressing "RET".  Playback
  69 can be paused using the spacebar, the next/previous songs can be selected
  70 using the "n" and "p" keys.  Similarly you can navigate between albums using
  71 "N" and "P".
  72
  73 You can see the full list of keys available for playback control by using
  74 `C-h m` with the browser buffer selected.  This help window also lists the
  75 interactive functions which control the playback.  Creating global bindings
  76 for these functions will allow you to control the playback from anywhere
  77 within emacs.
  78
  79 Outside of the browser buffer, `M-x emus-display-status` can be used
  80 to show the name of the currently selected/playing song as well as the
  81 current volume.
  82
  83 Example Hydra Configuration
  84 ---------------------------
  85
  86 The wonderful Hyrdra package (https://github.com/abo-abo/hydra) can be used to
  87 easily invoke emus commands outside of the emus-browser without needing to
  88 create more than a single emus-specific global binding.
  89
  90 The following example is from my own init.el configuration:
  91
  92     (defhydra hydra-ecmus (:color red :hint nil
  93                                     :pre (emus-display-status)
  94                                     :post (message nil))
  95         "
  96     Volume: _-_/[_+__=_] (down/up)  Tracks: _p_/_P_ (prev track/album) _n_/_N_ (next track/album)
  97     Playback: _SPC_ (play/pause) _o_ (stop) _,_/_._ (skip forward/backward)  Browser: _b_ (open browser)
  98     "
  99         ("<ESC>" "quit" :color blue)
 100         ("q" "quit" :color blue)
 101         ("RET" "quit" :color blue)
 102         ("SPC" emus-playpause-status)
 103         ("p" emus-play-prev-status)
 104         ("n" emus-play-next-status)
 105         ("P" emus-play-prev-album-status)
 106         ("N" emus-play-next-album-status)
 107         ("," emus-jump-10s-backward-status)
 108         ("." emus-jump-10s-forward-status)
 109         ("-" emus-volume-down-status)
 110         ("+" emus-volume-up-status)
 111         ("=" emus-volume-up-status)
 112         ("o" emus-stop-status)
 113         ("b" emus-browse :color blue))
 114
 115     (bind-key* (kbd "s-m") 'hydra-ecmus/body)
 116
 117
 118 License
 119 -------
 120
 121 Emus is free software and is distributed under the terms of version 3
 122 the GNU General Public License, which can be found in the file named
 123 COPYING.