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 it's 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'.


* 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 else, 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 are you 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 then. 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'

   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 (ie. 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 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 pronounce ee-em-em-es, and not a
single name. emms is highlighting that emms is a case-sensitive file
name and Emacs Lisp command.

* License
=========

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