aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 34b727a65968d94dc2839b15e98553fcad688e4a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
EMMS --- The Emacs Multi-Media System                -*-outline-*-
=====================================


* Introduction, Overview
========================

EMMS is the Emacs Multi-Media System.  It tries to be a clean and
small application to play multimedia files from Emacs using external
players.  Many of its ideas are derived from MpthreePlayer
(http://www.nongnu.org/mp3player), but it tries to be more general and
more clean.

   The basic functionality of Emms consists of three parts: The core,
the sources, and the players.

   The core resides in `emms.el', and provides a simple playlist and
the basic functionality to use all the other features of Emms.  It
provides the common user commands and interfaces for other parts.  It
thinks in tracks, where a track is the combination of a type and a
name--e.g., the track type 'file has a name that is the file name.
Other track types are possible.

   To get to tracks, the core needs sources.  The file
`emms-source-file.el' provides simple sources to interact with the
file system.

   When Emms finally has the sources in the playlist, it needs a
player to play them.  `emms-player-simple.el' defines a few useful
players, and allows you to define your own in a very simple way.

   The way Emms works is easy to customize with your own code or by
using `M-x customize RET'.


* Installation
==============

You need to put all the .el files of EMMS in a directory in your
load-path.  For example, if you put all those files into
~/elisp/emms/, then in your ~/.emacs you should do:

(add-to-list 'load-path "~/elisp/emms/")

For information about compiling Emms into byte-code see the
``Compiling Emms'' section in the Emms manual.

** Setup
--------
After adding the location of the Emms code to the load-path variable,
we invoke the following using the `emms-setup' feature which allows
for quick and simple Emms setup.

     (require 'emms-setup)
     (emms-standard)
     (emms-default-players)

After which Emms is set-up and ready to go!

   For more information about different setup levels and features see
the ``Simple Setup'' section of the Emms manual.

** Usage
--------
The basic functionality of EMMS is just to play music without being
noticed.  It provides a few commands to skip the current track and
such, but otherwise, it doesn't show up.  EMMS provides the following
basic user commands (that you might want to bind to keys):

emms-start ...... Start playing the current playlist
emms-stop ....... Stop playing
emms-next ....... Go to the next track in the playlist
emms-previous ... Go to the previous track in the playlist
emms-shuffle .... Shuffle the playlist
emms-show ....... What is playing?

But before you can use these, you need a playlist to start with.  The
following commands allow you to create a playlist from different
sources:

emms-play-file ............. Play a single file
emms-play-directory ........ Play a whole directory
emms-play-directory-tree ... Play a directory tree


* The Interactive Playlist buffer
=================================

Emms provides a visual, interactive playlist mode as well as the
ability to use playlists without ever looking at them.  This visual,
interactive mode is called the `emms-playlist-mode' and is defined in
`emms-playlist-mode.el'.

   To use the interactive playlist invoke: `M-x emms-playlist-mode-go
RET'

   When in the interactive playlist mode we can perform different
actions on the current playlist.  Here are some basic commands:

`n'....Start playing the next track in the playlist.

`p'....Start playing the previous track in the playlist.

`s'....Stop playing.

`f'....Describe the currently playing track in the minibuffer.

`c'....Display the current track in the center of the screen.

`RET'..Start playing the track under point.  Note that this is also
       available with `Mouse-2'.

`q'....Put the interactive playlist buffer at the end of the list of
       all buffers (i.e., bury it).

As always, for more commands see the mode documentation and the
``Interactive Playlists'' section of the Emms manual.


* Bare Bones Setup
==================

The following code fragment provides a minimal EMMS setup without
using the layer of `emms-default'.  It can maybe be used to better
understand the internals of EMMS.  You can see how EMMS needs to know
about players (these are defined in `emms-player-simple') and about
sources for tracks (trivial file system based sources, such as this
`emms-directory-tree', are defined in `emms-source-file').

(require 'emms-player-simple)
(require 'emms-source-file)
(require 'emms-source-playlist)
(setq emms-player-list '(emms-player-mpg321
                         emms-player-ogg123
                         emms-player-mplayer))


* Advanced configuration
========================

** Seeking
----------
In most multimedia players, you can seek forward or backward in a
track.  EMMS supports this too.  If you're using mplayer, check that
`emms-player-mplayer-parameters' contains ``slave''.  If you're using
mpg321, there is a module called emms-player-mpg321-remote.el.  To use
it, simply add the following lines to your configuration:

(require 'emms-player-mpg321-remote)
(push 'emms-player-mpg321-remote emms-player-list)

Finally, if you are using mpd, no special config is needed.

   Seeking works through the following functions:

`emms-seek' which takes a negative or positive amount of seconds.
`emms-seek-forward' which seeks ten seconds forward.
`emms-seek-backward' which seeks ten seconds backward.


* Using libtag for reading tags
===============================

There is a way to read tags using Libtag as your backend for
emms-info.  However, since it requires a binary file (source code
provided with EMMS), it isn't enabled by default.  To compile it, type
``make emms-print-metadata''.  To install it, either put
emms-print-metadata in your $PATH, or add EMMS' directory to Emacs'
exec-path.  Since libtag overwrites most of the usual methods for
providing info, it's best to keep it as the only function in
`emms-info-functions'.  Here's a way to do so:

(require 'emms-info-libtag)
(setq emms-info-functions '(emms-info-libtag))


* EMMS, Emms, emms, or what?
============================

In various contexts, this program is called EMMS, Emms or emms.  Those
are all correct, and which one you use is a matter of personal
preference.  EMMS highlights the acronym character of the name.  Emms
is akin to Emacs and Gnus, ignoring that Emms is pronounced
ee-em-em-es, and not a single name.  emms is highlighting that emms is
a case-sensitive file name and Emacs Lisp command.


* Getting help
==============

Emms has a mailing list at emms-help@gnu.org.  To subscribe to it,
visit http://lists.gnu.org/mailman/listinfo/emms-help.  If you are
familiar with the Gmane service, there is a Gmane newsgroup which
mirrors this mailing address at gmane.emacs.emms.user.

   Emms also has a website at <http://www.gnu.org/software/emms/>.


* License
=========

EMMS is available under the terms of the GNU General Public License.
Please see the file COPYING for details.