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.
