The Emacs Multimedia System
Emacs Lisp C
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 181 commits behind emacsmirror:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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
(, 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)

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

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

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

   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

* 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  To subscribe to it,
visit  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 <>.

* License

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