EMMS --- The Emacs Multi-Media System                -*-outline-*-
=====================================

* Introduction
==============
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.

** 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.


* 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/")


** Setup
--------
EMMS is quite simple to set up. For the most basic needs, you will
just need the following line:

(require 'emms)

Which installs the core of EMMS. Now we need to do some configuration.

The EMMS module `emms-default' provides the function `emms-setup',
which is a way to quickly configure your EMMS. You can add any number
of directories which contain media. The first argument is the
complexity level of the user interface. Here's an example:

(require 'emms-default)
(emms-setup 'tiny "directory")

Here are the all the interface complexity options:

 * minimalistic : defines the players, play directory but nothing
                  more.

 * tiny : adds the pbi (playlist buffer interface)

 * default : adds the info reading (tags for mp3 and oggs)

 * advanced : features the tageditor and playlist manipulation

 * cvs : features playlist pop-up, pbi marking, mode-line, and
         asynchronous loading of tags.

Now your configuration is done.

The (optional) directory is used for
`emms-source-file-default-directory', in case you were wondering.


** 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


* Overview
==========
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.


* Modules
=========

To use one of the modules that come with EMMS just put:

(require 'MODULE-NAME)

in your .emacs


** Playlist buffer (emms-pbi)
-----------------------------

emms-pbi ................ Switch to playlist buffer

The playlist-buffer *Playlist* will be created and put into
emms-pbi-mode, which give you some useful key bindings.

key             binding
---             -------
?		describe-mode
<mouse-2>	emms-pbi-play-current-line
RET		emms-pbi-play-current-line
q		bury-buffer
Q		emms-pbi-quit
f		emms-pbi-show-current-line
s		emms-stop
C-y		emms-pbi-yank
C-k		emms-pbi-kill-line
c		emms-pbi-recenter
p		emms-previous
n		emms-next
C-x C-s		emms-pbi-export-playlist


** Pop-up the Playlist Buffer (emms-pbi-popup)
----------------------------------------------

emms-pbi-popup-playlist...Popup Playlist buffer

After changing manually the track with emms-pbi-play-current-line the
old window configuration is restored. It might be useful to bind that
function to a global-key in your .emacs, for example:

(global-set-key (kbd "<f3>") 'emms-pbi-popup-playlist)

* 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)
(setq emms-player-list '(emms-player-mpg321
                         emms-player-ogg123
                         emms-player-mplayer))