Added some missing docstrings.
[emus.git] / 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.