Emms directory structure change/cleanup

I've been thinking about moving some parts of Emms to their own
directories in order to tidy up the distribution. Attached is a patch
which does this for the documentation. What do you people think?

>From 61459ce16456b31b119faefc6333007a023436d5 Mon Sep 17 00:00:00 2001
From: Yoni Rabkin <yonirabkin@member.fsf.org>
Date: Thu, 8 May 2008 23:58:07 +0300
Subject: [PATCH] Moved Emms documentation to a newly created doc directory.

As a first step in cleaning up the Emms distribution directory
structure, I've moved all the documentation to its own
directory. Makefiles have been created/updated accordingly.

Signed-off-by: Yoni Rabkin <yonirabkin@member.fsf.org>

1 files changed, 2419 insertions, 0 deletions

diff --git a/doc/emms.texinfo b/doc/emms.texinfo
new file mode 100644
index 0000000..5c9b5b0
--- /dev/null
+++ b/doc/emms.texinfo
@@ -0,0 +1,2419 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename emms.info
+@settitle The Emms Manual
+@c %**end of header
+
+@c History: The Emms manual was almost entirely rewritten for the
+@c release of Emms version 2.
+
+@c As a rule, modules which are stable enough to be included into the
+@c `emms-all' setup level should be documented. That is, any feature
+@c which is considered stable should be included.
+
+@dircategory Emacs
+@direntry
+* Emms: (emms).           The Emacs Multimedia System
+@end direntry
+
+@copying
+ @copyright{} 2004, 2005, 2006, 2007
+   Free Software Foundation, Inc.
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled "GNU Free
+Documentation License".
+@end quotation
+@end copying
+
+@c For printed material
+@titlepage
+@title The Emms Manual
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+@c END For printed material
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emms Manual
+
+This is the Manual for the Emacs Multimedia System
+@menu
+Starting out
+* Introduction::        Introduction to Emms.
+* Installation::        How to install Emms on your System.
+* Simple Setup::        Quick, basic default Emms setup.
+* Configuration::       More detailed setup and configuration.
+* Quickstart Guide::    First steps with EMMS for new users.
+* Getting Help::        Where to get help with Emms and make suggestions.
+
+Emms basics
+* Basic Commands::      How to control Emms with ease.
+* The Core File::       The inner core of Emms.
+* Sources::             Sources for playlists-creation.
+* Simple Players::      Some simple players.
+* Playlists::           How Emms organizes media.
+
+Advanced Features
+* Track Information::        More narrative track descriptions.
+* Interactive Playlists::    Interactive Playlists.
+* Markable Playlists::       Allow tracks to be marked.
+
+Modules and Extensions
+* The Browser::          Advanced metadata browsing.
+* Sorting Playlists::    Sorting the order of the tracks.
+* Persistent Playlists:: Restoring playlists on emacs startup.
+* Editing Tracks::       Editing track information from within Emms.
+* Emms Mode Line::       Emms information on the mode line.
+* Music Player Daemon::  Interface to Music Player Daemon.
+* Streaming Audio::      Interface to streaming audio.
+* Lyrics::               Displaying lyrics synchronously.
+* Volume::               Changing the volume.
+* Last.fm::              Interact with http://www.last.fm's services.
+* Extending Emms::       How to define new players and modules.
+
+Copying and license
+* Copying::             The GNU General Public License gives you permission to
+                            redistribute Emms on certain terms; it also explains
+                            that there is no warranty.
+* The GNU FDL::         The license for this documentation.
+
+Indices
+* Concept Index::
+* Function Index::
+* Variable Index::
+* Keybinding Index::
+
+@detailmenu
+--- The Detailed Node Listing ---
+
+Here are some other nodes which are really inferiors of the ones
+already listed, mentioned here so you can get to them in one step:
+
+Installation
+* Compiling Emms::      Compiling Emms into Byte-Code.
+
+The Core File
+* User Variables::     Variables for the user to tweak.
+* Hooks::              Hooks for important Emms functions.
+* Core Functions::     Providing the basic functionality of Emms.
+
+Track Information
+* Defining Info Methods::    Defining new info methods.
+
+Last.fm
+* Submitting track informations:: How to submit track information to last.fm.
+* Last.fm radio::                 How to listen to last.fm radio.
+
+Extending Emms
+* New Player::               How to define a new player.
+* Simple Player for `play':: Example player using @command{play}.
+* More Complex Player::      Example of a complex player using @command{mpg321}.
+@end detailmenu
+@end menu
+
+@end ifnottex
+
+
+@node Introduction
+@chapter Introduction
+
+@cindex 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 its ideas are derived from
+@uref{http://www.nongnu.org/mp3player, MpthreePlayer}, but it tries to
+be more general and more clean.
+
+This manual tries to be the definitive source of information about
+Emms, an online version of the manual is available at:
+@uref{http://www.gnu.org/software/emms/manual/}.
+
+The basic functionality of Emms consists of three parts: The core, the
+sources, and the players.
+
+The core resides in @file{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 @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. @file{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'.
+
+@node Installation
+@chapter Installation
+
+@cindex 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:
+
+@lisp
+(add-to-list 'load-path "~/elisp/emms/")
+@end lisp
+@noindent
+
+@menu
+* Compiling Emms::      Compiling Emms into Byte-Code.
+@end menu
+
+@node Compiling Emms
+@section Compiling Emms
+
+@cindex compiling
+
+If you are using XEmacs, you will need to edit @file{Makefile} as
+follows before continuing.
+
+@example
+EMACS=xemacs
+SITEFLAG=-no-site-file
+@end example
+
+You can byte-compile Emms by first entering the directory containing the
+Emms source code, followed by invoking:
+
+@command{make}
+
+Which will byte compile Emms. You can then invoke:
+
+@command{make install}
+
+Which will install Emms into your Emacs directories (provided you have
+the appropriate permissions to do so on your system).
+
+Note that Emms is a light-weight and agile program, you can therefore
+run Emms just fine without byte compiling it.
+
+@node Simple Setup
+@chapter Simple Setup
+
+@cindex simple setup
+@cindex setting up Emms
+@cindex quick setup
+
+After adding the location of the Emms code to the @var{load-path}
+variable, see @xref{Installation}. We invoke the following using the
+`emms-setup' feature which allows for quick and simple Emms setup.
+
+@lisp
+(require 'emms-setup)
+(emms-standard)
+(emms-default-players)
+@end lisp
+
+After which Emms is set-up and ready to go!
+
+The above will setup Emms with standard features (interactive
+playlists, audio track tag reading etc.) and a default list of players
+(ogg, mp3, mplayer etc.).
+
+The `emms-setup' feature is provided by the file
+@file{emms-setup.el}. It is essentially a collection of shortcuts for
+setting up Emms quickly and simply. Everything you can do with
+`emms-setup' can also be done manually.
+
+We use `emms-setup' by calling one of the setup functions. Each of the
+functions sets up Emms to include a number of features.
+
+@defun emms-minimalistic
+An Emms setup script.
+Invisible playlists and all the basics for playing media.
+@end defun
+
+@defun emms-standard
+An Emms setup script.
+Everything included in the @code{emms-minimalistic} setup, the Emms
+interactive playlist mode and reading information from tagged
+audio files.
+@end defun
+
+@defun emms-all
+An Emms setup script.
+Everything included in the @code{emms-standard} setup and adds all the
+stable features which come with the Emms distribution.
+@end defun
+
+@defun emms-devel
+An Emms setup script.
+Everything included in the @code{emms-all} setup and adds all of the
+features which come with the Emms distribution regardless of if they
+are considered stable or not.  Use this if you like living on the
+edge.
+@end defun
+
+`emms-setup' also comes with a convenience function to set a default
+list of media players.
+
+@defun emms-default-players
+Set @var{emms-player-list} to @var{emms-setup-default-player-list}.
+@end defun
+
+It is also worth noting that you can write your own Emms setup
+functions like the above by looking at the existing function
+definitions in @file{emms-setup.el}.
+
+@node Configuration
+@chapter Configuration
+
+@cindex Configuration
+
+This chapter discusses the configuration of Emms in more detail.
+
+The following code fragment provides a minimal Emms setup without
+using the layer of `emms-setup'. 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').
+
+@lisp
+(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))
+@end lisp
+
+For a discussion on how to define additional players, see @xref{Simple
+Players}.
+
+Much of the behaviour of Emms can be changed by setting
+variables. For example:
+
+@lisp
+(setq emms-info-asynchronously nil)
+(setq emms-playlist-buffer-name "*Music*")
+@end lisp
+
+The first @code{setq} turns off the asynchronous updating of info tags. The
+second sets the default name of the Emms playlist buffer.
+
+Another way to change Emms variables is to use the M-x
+@command{customize} mechanism provided by Emacs.
+
+@menu
+* Finding files and speed::     Finding files quickly or portably.
+@end menu
+
+@node Finding files and speed
+@section Finding files and speed
+
+@cindex files
+@cindex speed
+
+Emms needs to traverse directories in order to find playable
+media. The default method Emms uses to achive this is
+@code{emms-source-file-directory-tree-internal} as defined in
+@file{emms-source-file.el}.  The above method is written portably and
+will always work, but might be too slow if we want to load several
+hundred tracks (or more).
+
+@file{emms-source-file.el} defines another method for finding files,
+@code{emms-source-file-directory-tree-find} which uses
+GNU/find. @code{emms-source-file-directory-tree-find} is usually an
+order of magnitude faster, but of course will not work if you do not
+have GNU/find installed.
+
+The method Emms will use is defined in the customisable variable
+@var{emms-source-file-directory-tree-function}.
+
+@node Quickstart Guide
+@chapter Quickstart Guide
+
+This chapter demonstrates how to setup EMMS so that you can start
+listening to your music without having to read all of the documentation
+first.
+
+The first thing you have to do is telling Emacs where the sources of
+EMMS are located. Let's say you have them in @file{~/elisp/emms/}. So
+add this line to your @file{.emacs}.
+
+@lisp
+(add-to-list 'load-path "~/elisp/emms")
+@end lisp
+
+Further informations about installing EMMS can be found in the
+installation chapter, @xref{Installation}.
+
+Let's say you want to enable all features which are considered stable by
+the EMMS developers. To achieve this you invoke the @code{emms-all}
+setup function by adding the following three lines to your @file{.emacs}.
+
+@lisp
+(require 'emms-setup)
+(emms-all)
+(emms-default-players)
+@end lisp
+
+The function @code{emms-default-players} in the last line sets up the
+list of default players. The list contains lightweight specialized
+players like ogg123 or mpg321 and we-play-everything-players like
+mplayer or xine. To be sure that emms can play all your music you should
+check that the needed players are installed.
+
+Further informations about the several setup scripts can be found in the
+simple setup chapter, @xref{Simple Setup}.
+
+Of course EMMS tries to display the tags of the music files you listen
+to. For this to work you have to make sure that the appropriate programs
+are installed. For mp3 files you need `mp3info', and for ogg files you
+need `ogginfo'.
+
+The last thing to do is to tell EMMS the root directory of our music
+collection. Let's say all your music is in @file{~/Music} or in
+subdirectories thereof.
+
+@lisp
+(setq emms-source-file-default-directory "~/Music/")
+@end lisp
+
+OK, now we've set up EMMS. Reload your @file{.emacs} or restart Emacs to
+let the changes have an effect.
+
+Now we will add all our music to a playlist by invoking @kbd{M-x
+emms-add-directory-tree RET ~/Music/ RET}. We do this because then EMMS
+will read the tags of all your music files and cache them. This is
+required for the browser, @xref{The Browser}.
+
+To switch to the playlist buffer, invoke @kbd{M-x emms-playlist-mode-go}
+or simply @kbd{M-x emms}. You can see that most tracks are displayed
+with their file name, but track by track the filename gets replaced with
+the artist and track name of the file's tag.
+
+Hit @kbd{RET} on a track to start playback.
+
+Now you can start exploring EMMS. It's probably best to begin with the
+basic commands (@pxref{Basic Commands}), the interactive playlists
+(@pxref{Interactive Playlists}), and the browser (@pxref{The Browser}).
+
+@node Getting Help
+@chapter Getting Help
+
+@cindex mailing list
+@cindex website
+
+If you have a bug to report, need help, or wish to suggest a feature,
+please feel free to use the Emms mailing list.  The address of the list
+is emms-help@@gnu.org.  To subscribe to it, visit
+@url{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 @url{http://www.gnu.org/software/emms/}.
+
+@node Basic Commands
+@chapter Basic Commands
+
+@cindex basic commands
+@cindex commands, basic
+
+Before you can use the interface commands, you need a playlist to
+start with. The following commands allow you to add to the current
+playlist from different sources:
+
+Note that the commands with the ``emms-add-'' prefix add the source to
+the playlist but do not start playing it immediately. Conversely, the
+commands with the ``emms-play-'' prefix begin playing the track
+immediately.
+
+@defun emms-play-file file
+A source for a single file - either @var{file}, or queried from the
+user. If called with a prefix the file will be added like
+@command{emms-add-file}.
+@end defun
+@defun emms-add-file file
+A source for a single file - either @var{file}, or queried from
+the user. If called with a prefix the file will be played like
+@command{emms-play-file}.
+@end defun
+@defun emms-play-directory dir
+A source for a whole directory tree - either @var{dir}, or queried
+from the user.
+@end defun
+@defun emms-add-directory dir
+A source for a whole directory tree - either @var{dir}, or queried
+from the user.
+@end defun
+@defun emms-play-directory-tree dir
+A source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-add-directory-tree dir
+A source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-play-url url
+A source for an @var{url} - for example, for streaming.
+@end defun
+@defun emms-add-url url
+A source for an @var{url} - for example, for streaming.
+@end defun
+@defun emms-play-playlist playlist
+A source for the M3u or PLS playlist format from the file @var{playlist}.
+@end defun
+@defun emms-add-playlist playlist
+A source for the M3u or PLS playlist format from the file @var{playlist}.
+@end defun
+@defun emms-play-find dir regexp
+A source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} which match @var{regexp}.
+@end defun
+@defun emms-add-find dir regexp
+A source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} which match @var{regexp}.
+@end defun
+
+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 other than that it doesn't show up. Emms provides the
+following basic user commands (which you might want to bind to
+keystrokes):
+
+@defun emms-start
+Start playing the current playlist
+@end defun
+@defun emms-stop
+Stop playing
+@end defun
+@defun emms-next
+Start playing the next track in the playlist
+@end defun
+@defun emms-previous
+Start playing previous track in the playlist
+@end defun
+@defun emms-shuffle
+Shuffle the current playlist. This uses
+@var{emms-playlist-shuffle-function}.
+@end defun
+@defun emms-sort
+Sort the current playlist. This uses
+@var{emms-playlist-sort-function}.
+@end defun
+@defun emms-show &optional insertp
+Describe the current Emms track in the minibuffer. If @var{insertp} is
+non-nil, insert the description into the current buffer instead. This
+function uses @var{emms-show-format} to format the current track.
+@end defun
+
+@node The Core File
+@chapter The Core File
+
+@cindex core file
+@cindex heart of Emms
+@cindex primitive functions
+
+The core file @file{emms.el} provides the all basic functions for
+playing music, generating playlists and defining players.
+
+@menu
+* User Variables::     Variables for the user to tweak.
+* Hooks::              Hooks for important Emms functions.
+* Core Functions::     Providing the basic functionality of Emms.
+@end menu
+
+@node User Variables
+@section User Variables
+
+@cindex user variables
+@cindex options
+
+The core file defines a number of user variables.
+
+@defopt emms-player-list
+A list of players Emms can use. You need to set this in order to use
+Emms to play media.
+@end defopt
+@defopt emms-show-format
+The format to use for @command{emms-show}. Any "%s" is replaced by
+what @var{emms-track-description-function} returns for the currently
+playing track.
+@end defopt
+@defopt emms-repeat-playlist
+Non-nil if the Emms playlist should automatically repeat the playlist.
+If nil, playback will stop when the last track finishes playing.
+@end defopt
+@defopt emms-track-description-function
+Function for describing an Emms track in a user-friendly way.
+@end defopt
+@defopt emms-sort-lessp-function
+A function that compares two tracks, and returns non-nil if the first
+track should be sorted before the second (see also @code{sort}).
+@end defopt
+
+@node Hooks
+@section Hooks
+
+@cindex hooks
+@cindex adding functionality
+
+The core file provides hook variables for the basic functionality of
+Emms.
+
+@defopt emms-player-started-hook
+A hook run when an Emms player started playing.
+@end defopt
+@defopt emms-player-stopped-hook
+A hook run when an Emms player stopped playing. See also
+@var{emms-player-finished-hook}.
+@end defopt
+@defopt emms-playlist-source-inserted-hook
+Hook run when a source got inserted into the playlist. The buffer is
+narrowed to the new tracks.
+@end defopt
+@defopt emms-playlist-selection-changed-hook
+Hook run after another track is selected in the Emms playlist.
+@end defopt
+@defopt emms-playlist-cleared-hook
+Hook run after the current Emms playlist is cleared. This happens both
+when the playlist is cleared and when a new buffer is created for it.
+@end defopt
+@defopt emms-player-finished-hook
+Hook run when an Emms player finishes playing a track. Please pay
+attention to the differences between @var{emms-player-finished-hook}
+and @var{emms-player-stopped-hook}. The former is called only when the
+player is stopped interactively; the latter, only when the player
+actually finishes playing a track.
+@end defopt
+@defopt emms-player-paused-hook
+Hook run when a player is paused or resumed. Use
+@var{emms-player-paused-p} to find the current state.
+@end defopt
+
+@node Core Functions
+@section Core Functions
+
+@cindex core functions
+@cindex basic functions
+
+The core file also defines all the functions important to the basic
+use of Emms.
+
+There are functions which deal with movement in the playlist.
+
+@defun emms-next-noerror
+Start playing the next track in the Emms playlist. Unlike
+@code{emms-next}, this function doesn't signal an error when called at
+the end of the playlist. This function should only be called when no
+player is playing. This is a good function to put in
+@code{emms-player-finished-hook}.
+@end defun
+@defun emms-playlist-next
+Move to the previous track in the current buffer.
+@end defun
+@defun emms-playlist-previous
+Move to the previous track in the current buffer.
+@end defun
+@defun emms-random
+Jump to a random track.
+@end defun
+@defun emms-toggle-repeat-playlist
+Toggle whether emms repeats the playlist after it is done. See
+@var{emms-repeat-playlist}.
+@end defun
+@defun emms-toggle-repeat-track
+Toggle whether emms repeats the current track. See
+@var{emms-repeat-track}.
+@end defun
+
+Some functions deal with the getting and setting track information.
+
+@defun emms-track type name
+Create a track with type @var{type} and name @var{name}.
+@end defun
+@defun emms-track-type track
+Return the type of @var{track}.
+@end defun
+@defun emms-track-name track
+Return the name of @var{track}.
+@end defun
+@defun emms-track-get name track &optional inexistent
+Return the value of @var{name} for @var{track}. If there is no value,
+return @var{default} (or nil, if not given).
+@end defun
+@defun emms-track-set track name value
+Set the value of @var{name} for @var{track} to @var{value}.
+@end defun
+@defun emms-track-description track
+Return a description of @var{track}. This function uses
+@var{emms-track-description-function}.
+@end defun
+@defun emms-player-for track
+Return an Emms player capable of playing @var{track}. This will be the
+first player whose PLAYABLEP function returns non-nil, or nil if no
+such player exists.
+@end defun
+@defun emms-playlist-current-selected-track
+Return the currently selected track in the current playlist.
+@end defun
+
+There are also functions which deal with the playing itself.
+
+@defun emms-player-start track
+Start playing @var{track}.
+@end defun
+@defun emms-player-stop
+Stop the currently playing player.
+@end defun
+@defun emms-player-stopped
+Declare that the current Emms player is finished.
+This should only be done by the current player itself.
+@end defun
+@defun emms-seek seconds
+Seek the current player @var{seconds} seconds. This can be a floating
+point number for sub-second fractions. It can also be negative to
+seek backwards.
+@end defun
+@defun emms-seek-forward
+Seek ten seconds forward.
+@end defun
+@defun emms-seek-backward
+Seek ten seconds backward.
+@end defun
+
+For more basic commands defined in the core file see @xref{Basic
+Commands}.
+
+@node Sources
+@chapter Sources
+
+@cindex Sources
+
+Sources allow Emms to add and play tracks. Emms comes with a number of
+sources of its own. Sources are designed so that creating new ones
+will be easy.
+
+For examples of Emms sources for files and directories see
+@file{emms-source-file.el}.
+
+@defopt emms-source-file-default-directory
+The default directory to look for media files.
+@end defopt
+@defun emms-play-find
+Play all files in @var{emms-source-file-default-directory} that match
+a specific regular expression.
+@end defun
+@defun emms-source-file &optional file
+An Emms source for a single file - either @var{file}, or queried from the
+user.
+@end defun
+@defun emms-source-files files
+An Emms source for a list of @var{files}.
+@end defun
+@defun emms-source-directory &optional dir
+An Emms source for a whole directory tree - either @var{dir}, or queried
+from the user
+@end defun
+@defun emms-source-directory-tree & optional dir
+An Emms source for multiple directory trees - either @var{dir}, or the
+value of @var{emms-source-file-default-directory}.
+@end defun
+@defun emms-source-playlist file
+An EMMS source for playlists.  See `emms-source-playlist-formats' for
+a list of supported formats.
+@end defun
+@defun emms-source-playlist-native file
+An EMMS source for a native EMMS playlist file.
+@end defun
+@defun emms-source-playlist-m3u file
+An EMMS source for an m3u playlist file.
+@end defun
+@defun emms-source-playlist-pls file
+An EMMS source for a pls playlist file.
+@end defun
+@defun emms-source-find &optional dir regex
+An Emms source that will find files in @var{dir} or
+@var{emms-source-file-default-directory} that match @var{regexp}.
+@end defun
+@defun emms-source-file-directory-tree &optional dir
+Return a list of all files under @var{dir} which match @var{regex}.
+@end defun
+@defun emms-source-dired
+Play all marked files of a dired buffer
+@end defun
+@defun emms-source-file-regex
+Return a regexp that matches everything any player (that supports
+files) can play.
+@end defun
+@defun emms-locate regexp
+Search for @var{regexp} and display the results in a locate buffer
+@end defun
+
+@node Simple Players
+@chapter Simple Players
+
+@cindex players, simple
+
+@defmac define-emms-simple-player name types regex command &rest args
+Define a simple player with the use of `emms-define-player'.
+@var{name} is used to construct the name of the function like
+emms-player-@var{name}. @var{types} is a list of track types
+understood by this player. @var{regex} must be a regexp that matches
+the filenames the player can play. @var{command} specifies the command
+line argument to call the player and @var{args} are the command line
+arguments.
+@end defmac
+
+For a discussion on how to define new players see @xref{New Player}.
+
+@defun emms-player-simple-stop
+Stop the currently playing process, if indeed there is one.
+@end defun
+@defun emms-player-simple-start filename cmdname params
+Starts a process playing @var{filename} using the specified @var{cmdname} with
+the specified @var{params}.
+@end defun
+@defun emms-player-simple-sentinel proc str
+Sentinel for determining the end of process for the process @var{proc}
+and the sentinel string @var{str}.
+@end defun
+
+@node Playlists
+@chapter Playlists
+
+@cindex organizing tracks and media
+
+Emms uses Emacs buffers to store the media tracks for playing. We call
+one such buffer a ``playlist buffer'' or an ``Emms playlist
+buffer''. Emms then proceeds to play the media tracks in the buffer
+from top to bottom until the end of the playlist.
+
+The name of the playlist buffer is defined in the variable
+@var{emms-playlist-buffer-name} and is set to be an invisible Emacs
+buffer by default. You can change to any name you want. For an example
+configuration see @xref{Configuration}.
+
+You can create any number of playlist buffers you wish. At any time
+Emms has a single ``current'' buffer through which it proceeds track
+by track.
+
+@defun emms-playlist-new &optional name
+Create a new playlist buffer.
+The buffer is named @var{name}, but made unique. @var{name} defaults
+to `emms-playlist-buffer-name'. If called interactively, the new
+buffer is also selected.
+@end defun
+
+@defun emms-playlist-save &optional format file
+Store the current playlist to FILE as the type FORMAT.  The default
+format is specified by `emms-source-playlist-default-format'.
+@end defun
+
+The current Emms playlist buffer is stored in the variable
+@var{emms-playlist-buffer}.
+
+@node Track Information
+@chapter Track Information
+
+@cindex track information
+@cindex info tags
+
+Emms is distributed with two predefined methods for retrieving info,
+provided by @file{emms-info-mp3info.el} and
+@file{emms-info-ogginfo.el}. Both packages are front-ends for
+command-line tools. Ogg track information is retrieved using the
+@uref{http://directory.fsf.org/audio/ogg/vorbistools.html, ogginfo}
+software. Likewise, mp3 track information is available using
+@uref{http://www.ibiblio.org/mp3info/, mp3info}.
+
+Automatic track information retrieval is enabled by default in the
+`emms-standard', `emms-all' and `emms-devel' setup levels provided by
+@file{emms-setup.el}. For more information about @file{emms-setup.el}
+see @xref{Simple Setup}.
+
+If you would like to know how Emms track retreival works and how we
+can define new methods for track retrieval see @xref{Defining Info
+Methods}.
+
+There are a number of user variables which control the behaviour of
+`emms-info'.
+
+@defopt emms-info-auto-update
+Non-nil when Emms should update track information if the file changes.
+This will cause hard drive activity on track loading. If this is too
+annoying for you, set this variable to nil.
+@end defopt
+@defopt emms-info-asynchronously
+Non-nil when track information should be loaded asynchronously. This
+requires the feature `later-do' which is provided by the file
+@file{later-do.el}, which should come with Emms.
+@end defopt
+@defopt emms-info-functions
+Functions which add information to tracks.  Each is called with a
+track as argument.
+@end defopt
+
+@menu
+* Defining Info Methods::    Defining new info methods.
+@end menu
+
+@node Defining Info Methods
+@section Defining Info Methods
+
+@cindex defining info methods
+
+An info method essentially consists of a function which given an Emms
+track returns the appropriate info for that track.
+
+We can for example look at the predefined method for retrieving
+information about audio tracks in the Ogg format.
+
+The function @command{emms-info-ogginfo} provided by
+@file{emms-info-ogginfo.el} accepts an Emms track as a single
+argument and returns the appropriate information string.
+
+We then register our info function with Emms by adding it to the
+@var{emms-info-functions} list. The function will then be called at
+the right time to provide track info.
+
+@lisp
+(add-to-list 'emms-info-functions 'emms-info-ogginfo)
+@end lisp
+
+@node Interactive Playlists
+@chapter Interactive Playlists
+
+@cindex Interactive Playlists
+
+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
+@file{emms-playlist-mode.el}.
+
+The interactive playlist mode is enabled by default in the
+`emms-standard', `emms-all' and `emms-devel' setup levels. For more
+information about Emms setup levels see @xref{Simple Setup}.
+
+@defun emms-playlist-mode-go
+Switch to the current emms-playlist buffer and use emms-playlist-mode.
+@end defun
+
+If you wish to make this the default EMMS playlist mode, add the
+following to your @file{.emacs}.
+
+@lisp
+(setq emms-playlist-default-major-mode 'emms-playlist-mode)
+@end lisp
+
+The interactive playlist buffer shows the tracks in the current Emms
+playlist in the order in which they will be played. The current track
+will be highlighted.
+
+When in the interactive playlist mode we can perform different actions
+on the current playlist.
+
+@table @kbd
+@item a
+@findex emms-playlist-mode-add-contents
+Add files in the playlist at point to the current playlist buffer.
+If we are in the current playlist, make a new playlist buffer and
+set it as current.
+@item b
+@findex emms-playlist-set-playlist-buffer
+Set the current playlist buffer.
+@item n
+@findex emms-next
+Start playing the next track in the playlist.
+@item p
+@findex emms-next
+Start playing the previous track in the playlist.
+@item s
+@findex emms-stop
+Stop playing.
+@item P
+@findex emms-pause
+Pause.
+@item >
+@findex emms-seek-forward
+Seek ten seconds forward.
+@item <
+@findex emms-seek-backward
+Seek ten seconds backward.
+@item f
+@findex emms-show
+Describe the currently playing track in the minibuffer.
+@item c
+@findex emms-playlist-mode-center-current
+Display the current track in the center of the screen.
+@item RET
+@findex emms-playlist-mode-play-current-track
+Start playing the track under point. Note that this is also available
+with @kbd{<mouse-2>}.
+@item SPC
+@findex scroll-up
+Scroll up a near full page.
+@item M-<
+@findex emms-playlist-mode-first
+Go to the first track in the playlist. @kbd{M->} completes this
+command by going to the last track in the playlist using
+@command{emms-playlist-mode-last}.
+@item r
+@findex emms-random
+Go to a randomly selected track in the playlist.
+@item q
+@findex bury-buffer
+Put the interactive playlist buffer at the end of the list of all
+buffers.
+@item C-x C-s
+@findex emms-playlist-save
+Save the current playlist buffer to a file.
+@item ?
+@findex describe-mode
+Describe the mode.
+@end table
+
+We can also edit the playlist using familiar GNU/Emacs commands:
+
+@table @kbd
+@item C-k
+@findex emms-playlist-mode-kill-track
+Remove the track under point from the playlist buffer. Also available
+using the @kbd{d} key.
+@item C-y
+@findex emms-playlist-mode-yank
+See the command @command{yank}
+@item C-w
+@findex emms-playlist-mode-kill
+See the command @command{kill-region}
+@item M-y
+@findex emms-playlist-mode-yank-pop
+See the command @command{yank-pop}.
+@item C-j
+@findex emms-playlist-mode-insert-newline
+Insert a newline at point.
+@end table
+
+We can use the regular GNU/Emacs killing and yanking commands to move
+and copy tracks in between playlist buffers. We can use the same
+commands to insert arbitrary text into the playlist buffers together
+with the playlist tracks. Text which is not a track is ignored by the
+program and can therefore be used to include titles and annotations
+within the playlist.
+
+@node Markable Playlists
+@chapter Markable Playlists
+
+@cindex Markable Playlists
+
+The Markable Playlists provided by the file @file{emms-mark.el} are an
+alternative to the default interactive playlists, @xref{Interactive
+Playlists}. They allow marking tracks with keybindings familiar to users
+of dired.
+
+To enable the Markable Playlists you have to add
+
+@lisp
+(require 'emms-mark)
+@end lisp
+
+to your @file{.emacs}. Then you can activate @command{emms-mark-mode} by
+executing @command{M-x emms-mark-mode} in a playlist buffer. You can
+return to the default interactive playlist mode with @command{M-x
+emms-mark-mode-disable}.
+
+If you wish to make this the default EMMS playlist mode, add the
+following to your @file{.emacs}.
+
+@lisp
+(setq emms-playlist-default-major-mode 'emms-mark-mode)
+@end lisp
+
+@table @kbd
+@item m
+@findex emms-mark-forward
+Marks the current track and sets point one line forward. If a prefix
+argument ARG is given, it will mark the next ARG tracks and set point
+accordingly. A negative argument marks backward.
+@item U
+@findex emms-mark-unmark-all
+Unmarks all tracks in the playlist.
+@item t
+@findex emms-mark-toggle
+Toggles mark on the current track.
+@item u
+@findex emms-mark-unmark-forward
+Unmarks same way as @command{emms-mark-forward} marks.
+@item % m
+@findex emms-mark-regexp
+Marks all tracks in the playlist matching the given regular
+expression. A prefix argument means to unmark them instead.
+@end table
+
+When tracks are marked you can operate on them:
+
+@table @kbd
+@item D
+@findex emms-mark-delete-marked-tracks
+Deletes the marked tracks from the playlist.
+@item K
+@findex  emms-mark-kill-marked-tracks
+Deletes the marked tracks from the playlist and places them in the
+kill-ring, so that you can @command{yank} in into another playlist.
+@item W
+@findex emms-mark-copy-marked-tracks
+Adds the marked tracks to the kill-ring, so that you can @command{yank}
+them into another playlist.
+@end table
+
+emms-mark is also intent to provide a way for user to select tracks
+for other command to operate on them. Currently,
+@file{emms-tag-editor.el} used the emms-mark to edit tags of selected
+tracks. Two function is useful for elisp programer to handle marked
+tracks.
+
+@defun emms-mark-do-with-marked-track
+This function take a function to perform on all marked tracks. A
+optional argument `move-flag' to tell the function to move forward
+line after calling given function. If the given function didn't change
+position, the second argument should set to non-nil.
+@end defun
+
+@defun emms-mark-mapcar-marked-track
+This function is very similar to `emms-mark-do-with-marked-track'
+except it collects result of given function (that's why named with
+`mapcar').
+@end defun
+
+@node Extending Emms
+@chapter Extending Emms
+
+@cindex new players
+@cindex defining players
+@cindex new players, defining
+
+Emms introduces a high abstraction layer for playing music so you can
+customise it to your needs.
+
+@menu
+* New Player::               How to define a new player.
+* Simple Player for `play':: An example player using @command{play}.
+* More Complex Player::      Example of a complex player using @command{mpg321}.
+@end menu
+
+@node New Player
+@section New Player
+
+@cindex new player
+@cindex defining new players
+
+The file @file{emms-player-simple.el} defines some easy players to
+start with, but it shouldn't be hard to provide a function for your
+favourite player. We will start with an easy example that shows how
+we can use the @command{play} command under Unix to play our WAV files.
+
+@node Simple Player for `play'
+@section Simple Player for `play'
+
+@cindex simple player
+@cindex primitive player
+@cindex basic player
+
+Play is a very easy command line player for various format. If you
+want your emms to play WAV files just put the following lines in you
+@file{.emacs}:
+
+@lisp
+(require 'emms-player-simple)
+(define-emms-simple-player play '(file) "\\.wav$" "play")
+@end lisp
+@noindent
+
+Huh! Wasn't that easy?
+
+The macro function @command{define-emms-simple-player} takes a minimum
+of three arguments. The first argument (@emph{play} in our example)
+defines the name of the player. It's used to name the player
+functions. The second is a regexp, that defines which files to play
+with our player. @emph{\\.wav$} matches any filename ending with a dot
+and the string wav. The last argument is the actual command line
+command we use to play our files. You can also add the path but we
+just assume that the command is in your path. All arguments you add to
+these three are optional. They define the command line arguments you
+want to add to your argument. If you want to hear the wav file of your
+favourite artist in the most possible volume use the following line:
+
+@lisp
+(require 'emms-player-simple)
+
+(define-emms-simple-player play
+                           '(file)
+                           "\\artist-*.wav$"
+                           "play"
+                           "--volume=100")
+@end lisp
+@noindent
+
+Please notice that you have to add the arguments as strings!
+
+The command line tool you use for @command{define-emms-simple-player}
+has to take one song as argument and stop after playing that
+particular song. For any other concept you will need to customise
+emms a bit more...
+
+@node More Complex Player
+@section More Complex Player
+
+@cindex complex player
+@cindex advanced player
+
+The most players you use will be simple players so you don't need to
+read this chapter. But if you are curious how you can use (almost) every
+player in emms read further...
+
+In this chapter we will use mpg321 to construct a player that
+actually can pause a track, restart it and show rest time. We won't
+implement all of that, but after that chapter you will know how to
+define it.
+
+The command @command{define-emms-simple-player} is just a abstraction
+layer for @command{define-emms-player}, which is a little bit more
+complicated but much more powerful!
+
+@lisp
+(define-emms-player "emms-mpg321-remote"
+  :start 'emms-mpg321-remote-start
+  :stop 'emms-mpg321-remote-stop
+  :playablep 'emms-mpg321-remote-playable-p)
+@end lisp
+@noindent
+
+So, that is almost all! @command{define-emms-player} takes a minimum
+of three arguments. The first is the name of the player. The rest are
+methods with functions to call. Three methods are required: start,
+stop and playable. Start says Emms how to start a track (sic!), stop
+how to stop a player and playablep should return non-nil if the player
+can play the track.
+
+So we just need these three functions to get our mpg321-remote:
+
+First we code the start function. We will check if there's a open
+process and start one otherwise. Then we send a string to the process
+with the filename and set a filter.
+
+@lisp
+(defun emms-mpg321-remote-start ()
+  (unless (get-process ``mpg321-remote'')
+    (setq emms-mpg321-remote-process
+	  (start-process "mpg321-remote-process"
+			 "*mpg321*" "mpg321" "-R" "abc"))
+  (process-send-string "mpg321-remote-process"
+		       (concat "l " (emms-track-name track)))
+  (set-process-filter emms-mpg321-remote-process 'emms-mpg321-remote-filter)))
+@end lisp
+@noindent
+
+We need the filter, as mpg321-remote won't quit after playing the
+track as the simple player do. We wait until the process sends the
+output ``(at-sign)P 0'' (the signal of mpg321 that the song ended) to the
+filter and call emms-mpg321-remote-stop.
+
+@lisp
+(defun emms-mpg321-remote-filter (process output)
+  (when (string-match "(at-sign)P 0" output)
+    (emms-mpg321-remote-stop)))
+@end lisp
+@noindent
+
+@command{emms-mpg321-remote-stop} won't do anything interesting. It
+just test if there are other files to play and close the process otherwise.
+
+@lisp
+(defun emms-mpg321-remote-stop ()
+  (unless emms-playlist
+    (process-send-string "mpg321-remote-process" "Q\n"))
+@end lisp
+@noindent
+
+And to make that a playable example I also added
+@command{emms-mpg321-remote-playablep}, which I really just steal
+from @file{emms-player-simple.el}
+
+@lisp
+(defun emms-mpg321-remote-playablep (track)
+       "Return non-nil when we can play this track."
+       (and (eq 'file (emms-track-type track))
+@end lisp
+@noindent
+
+Now we have a ready player and we could add commands like
+@command{emms-mpg321-remote-pause} for example.
+
+@node The Browser
+@chapter The Browser
+
+The Browser allows you to browse the metadata cache and add tracks to
+your playlist. It includes a powerful interactive mode.
+
+The Browser is defined in @file{emms-browser.el} and is included in
+the @command{emms-all} setup level. For more information about Emms
+setup levels see @xref{Simple Setup}.
+
+You can also manually add the Browser to your Emms setup by loading it
+explicitly with:
+
+@lisp
+(require 'emms-browser)
+@end lisp
+
+To be properly useful, you should do M-x
+@command{emms-add-directory-tree} to all the files you own at least
+once so that the cache is fully populated.
+
+@menu
+* Browser Interface::     The interactive browser interface.
+* Filtering Tracks::      Displaying a subset of the tracks.
+* Displaying Covers::     Displaying album covers in the browser interface.
+* Changing Looks::        Changing the tree structure, display format and faces.
+@end menu
+
+@node Browser Interface
+@section Browser Interface
+
+The browser interface allows you to display and interact with your
+tracks in many different ways. There are a number of ways to start the
+browser.
+
+@defun emms-smart-browse
+Display browser and playlist. Toggle between selecting browser,
+playlist or hiding both. Tries to behave sanely if the user has
+manually changed the window configuration.
+@end defun
+
+@defun emms-browse-by-artist
+Display the browser and order the tracks by artist.
+@end defun
+
+@defun emms-browse-by-album
+Display the browser and order the tracks by album.
+@end defun
+
+@defun emms-browse-by-genre
+Display the browser and order the tracks by genre.
+@end defun
+
+@defun emms-browse-by-year
+Display the browser and order the tracks by year.
+@end defun
+
+Once the Browser is displayed you can use it to managed your track
+collection and playlists. The Browser is interactive and has its own
+keybindings.
+
+@table @kbd
+
+@item C-j
+@kindex C-j (emms-browser)
+@findex emms-browser-add-tracks-and-play
+Add all tracks at point, and play the first added track.
+
+@item RET
+@kindex RET (emms-browser)
+@findex emms-browser-add-tracks
+Add all tracks at point.
+
+@item SPC
+@kindex SPC (emms-browser)
+@findex emms-browser-toggle-subitems
+Show or hide (kill) subitems under the current line.
+
+@item 1
+@kindex 1 (emms-browser)
+@findex emms-browser-collapse-all
+Collapse everything.
+
+@item 2
+@kindex 2 (emms-browser)
+@findex emms-browser-expand-to-level-2
+Expand all top level items one level.
+
+@item 3
+@kindex 3 (emms-browser)
+@findex emms-browser-expand-to-level-3
+Expand all top level items two levels.
+
+@item 4
+@kindex 4 (emms-browser)
+@findex emms-browser-expand-to-level-4
+Expand all top level items three levels.
+
+@item C
+@kindex C (emms-browser)
+@findex emms-browser-clear-playlist
+Clear the playlist.
+
+@item E
+@kindex E (emms-browser)
+@findex emms-browser-expand-all
+Expand everything.
+
+@item d
+@kindex d (emms-browser)
+@findex emms-browser-view-in-dired
+View the current directory in dired.
+
+@item q
+@kindex q (emms-browser)
+@findex emms-browser-bury-buffer
+Bury the browser buffer.
+
+@item r
+@kindex r (emms-browser)
+@findex emms-browser-goto-random
+Jump to a random track.
+
+@item /
+@kindex / (emms-browser)
+@findex emms-isearch-buffer
+Isearch through the buffer.
+
+@item <
+@kindex < (emms-browser)
+@findex emms-browser-previous-filter
+Redisplay with the previous filter.
+
+@item >
+@kindex > (emms-browser)
+@findex emms-browser-next-filter
+Redisplay with the next filter.
+
+@item ?
+@kindex ? (emms-browser)
+@findex describe-mode
+See the Emacs documentation for the function.
+
+@item C-/
+@kindex C-/ (emms-browser)
+@findex emms-playlist-mode-undo
+Undo the previous playlist action.
+
+@item <C-return>
+@kindex <C-return> (emms-browser)
+@findex emms-browser-add-tracks-and-play
+Add all tracks at point, and play the first added track.
+
+@item <backtab>
+@kindex <backtab> (emms-browser)
+@findex emms-browser-prev-non-track
+Jump to the previous non-track element.
+
+@item <tab>
+@kindex <tab> (emms-browser)
+@findex emms-browser-next-non-track
+Jump to the next non-track element.
+
+@item s A
+@kindex s A (emms-browser)
+@findex emms-browser-search-by-album
+Search the collection by album.
+
+@item s a
+@kindex s a (emms-browser)
+@findex emms-browser-search-by-artist
+Search the collection by artist.
+
+@item s s
+@kindex s s (emms-browser)
+@findex emms-browser-search-by-names
+Search the collection by names.
+
+@item s t
+@kindex s t (emms-browser)
+@findex emms-browser-search-by-title
+Search the collection by title.
+
+@item b 1
+@kindex b 1 (emms-browser)
+@findex emms-browse-by-artist
+Browse the collection by artist.
+
+@item b 2
+@kindex b 2 (emms-browser)
+@findex emms-browse-by-album
+Browse the collection by album.
+
+@item b 3
+@kindex b 3 (emms-browser)
+@findex emms-browse-by-genre
+Browse the collection by genre.
+
+@item b 4
+@kindex b 4 (emms-browser)
+@findex emms-browse-by-year
+Browse the collection by year.
+
+@item W a p
+@kindex W a p (emms-browser)
+@findex emms-browser-lookup-album-on-pitchfork
+Lookup the album using Pitchfork.
+
+@item W a w
+@kindex W a w (emms-browser)
+@findex emms-browser-lookup-album-on-wikipedia
+Lookup the album using Wikipedia.
+@end table
+
+@node Filtering Tracks
+@section Filtering Tracks
+
+If you want to display a subset of your collection (such as a
+directory of 80s music, only avi files, etc.) then you can extend the
+Browser by defining ``filters''.
+
+Show everything:
+
+@lisp
+(emms-browser-make-filter "all" 'ignore)
+@end lisp
+
+Set "all" as the default filter:
+
+@lisp
+(emms-browser-set-filter (assoc "all" emms-browser-filters))
+@end lisp
+
+Show all files (no streamlists, etc):
+
+@lisp
+(emms-browser-make-filter
+ "all-files" (emms-browser-filter-only-type 'file))
+@end lisp
+
+Show only tracks in one folder:
+
+@lisp
+(emms-browser-make-filter
+ "80s" (emms-browser-filter-only-dir "~/Mp3s/80s"))
+@end lisp
+
+Show all tracks played in the last month:
+
+@lisp
+(emms-browser-make-filter
+ "last-month" (emms-browser-filter-only-recent 30))
+@end lisp
+
+After executing the above commands, you can use M-x
+emms-browser-show-all, emms-browser-show-80s, etc to toggle between
+different collections. Alternatively you can use '<' and '>' to cycle
+through the available filters.
+
+The second argument to make-filter is a function which returns t if a
+single track should be filtered. You can write your own filter
+functions to check the type of a file, etc.
+
+Show only tracks not played in the last year:
+
+@lisp
+(emms-browser-make-filter "not-played"
+ (lambda (track)
+  (not (funcall (emms-browser-filter-only-recent 365) track))))
+@end lisp
+
+Show all files that are not in the pending directory:
+
+@lisp
+(emms-browser-make-filter
+ "all"
+ (lambda (track)
+   (or
+    (funcall (emms-browser-filter-only-type 'file) track)
+    (not (funcall
+          (emms-browser-filter-only-dir "~/Media/pending") track)))))
+@end lisp
+
+@node Displaying Covers
+@section Displaying Covers
+
+The browser will attempt to display cover images if they're
+available. By default it looks for images cover_small.jpg,
+cover_med.jpg, etc. Customize @var{emms-browser-covers} to use your
+own covers. Note that you'll probably want to resize your existing
+covers to particular sizes. Suggested sizes are 100x100 for small, and
+200x200 for medium.
+
+Also, Emacs by default will jump around a lot when scrolling a buffer
+with images. In order to prevent that, you can set
+@var{scroll-up-aggressively} and @var{scroll-down-aggressively} to the
+number ``0.0''.
+
+To show a 'no cover' image for albums which don't have a cover, add
+the following code to your .emacs:
+
+@lisp
+(setq emms-browser-default-covers
+  (list "/path/to/cover_small.jpg" nil nil)
+@end lisp
+
+The medium and large images can be set as well.
+
+You can download an example @uref{http://repose.cx/cover_small.jpg,
+`no cover' image}.
+
+@node Changing Looks
+@section Changing Looks
+
+The Browser's look can be customised. You can change the way the tree
+structure looks, the display format and display faces.
+
+@subheading Changing Tree Structure
+
+You can change the way the tree is displayed by modifying the function
+@command{emms-browser-next-mapping-type}.
+
+The following code displays artist->track instead of
+artist->album->track when you switch to the 'singles' filter:
+
+@lisp
+(defadvice emms-browser-next-mapping-type
+                                (after no-album (current-mapping))
+  (when (eq ad-return-value 'info-album)
+    (setq ad-return-value 'info-title)))
+@end lisp
+
+@lisp
+(defun toggle-album-display ()
+  (if (string= emms-browser-current-filter-name "singles")
+      (ad-activate 'emms-browser-next-mapping-type)
+    (ad-deactivate 'emms-browser-next-mapping-type)))
+
+(add-hook 'emms-browser-filter-changed-hook 'toggle-album-display)
+@end lisp
+
+@subheading Changing Display Format
+
+Format strings govern the way items are displayed in the browser and
+playlist. You can customize these if you wish.
+
+@var{emms-browser-default-format} controls the format to use when no
+other format has been explicitly defined. By default, only track and
+albums deviate from the default.
+
+To customise the format of a particular type, find the name of the
+field you want to use (eg `info-artist', `info-title', etc), and
+insert that into emms-browser-<type>-format or
+emms-browser-playlist-<type>-format. For example, if you wanted to
+remove track numbers from tracks in both the browser and playlist, you
+could do:
+
+@lisp
+(defvar emms-browser-info-title-format "%i%n")
+(defvar emms-browser-playlist-info-title-format
+  emms-browser-info-title-format)
+@end lisp
+
+The format specifiers available include:
+
+@itemize @w
+@item
+%i    indent relative to the current level
+@item
+%n    the value of the item - eg -info-artist might be ``pink floyd''
+@item
+%y    the album year
+@item
+%A    the album name
+@item
+%a    the artist name of the track
+@item
+%t    the title of the track
+@item
+%T    the track number
+@item
+%cS   a small album cover
+@item
+%cM   a medium album cover
+@item
+%cL   a big album cover
+@end itemize
+
+Note that if you use track-related items like %t, it will take the
+data from the first track.
+
+@subheading Changing Display Faces
+
+The faces used to display the various fields are also customizable.
+They are in the format emms-browser-<type>-face, where type is one of
+"year/genre", "artist", "album" or "track". Note that faces lack the
+initial "info-" part. For example, to change the artist face, type M-x
+@command{customize-face} @command{emms-browser-artist-face}.
+
+@node Sorting Playlists
+@chapter Sorting Playlists
+
+@cindex sort
+@cindex track order
+
+The `emms-playlist-sort' module, defined in the
+@file{emms-playlist-sort.el} package provides functions for sorting
+Emms playlists. `emms-playlist-sort' can be loaded by invoking:
+
+@lisp
+(require 'emms-playlist-sort)
+@end lisp
+
+@defun emms-playlist-sort-by-name
+Sort playlist by name in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-artist
+Sort playlist by artist in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-title
+Sort playlist by title in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-album
+Sort playlist by album in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-year
+Sort playlist by year in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-info-note
+Sort playlist by notes in ascending order.
+@end defun
+
+@defun emms-playlist-sort-by-score
+Sort emms playlist by score in descending order.
+@end defun
+
+@node Persistent Playlists
+@chapter Persistent Playlists
+
+The Emms module @file{emms-history.el} makes playlists persistent over
+emacs sessions.  To make use of this feature put this into your
+~/.emacs.
+
+@lisp
+(require 'emms-history)
+@end lisp
+
+When you kill emacs all playlists will be saved in the file given by the
+variable:
+
+@defopt emms-history-file
+The file to save playlists in.  It defaults to
+"~/.emacs.d/emms-history".
+@end defopt
+
+After you started up emacs again, you can restore all saved playlists
+with this function.
+
+@defun emms-history-load
+Restore all playlists in `emms-history-file'.
+@end defun
+
+If that should be done automatically on each startup, put these lines
+into your ~/.emacs.
+
+@lisp
+(require 'emms-history)
+(emms-history-load)
+@end lisp
+
+Normally @code{emms-history} only restores playlists.  If you want it to
+start playback afterwards, you can tweak this variable.
+
+@defopt emms-history-start-playing
+If non-nil emms starts playing the current track after
+`emms-history-load' was invoked.  The default value is nil.
+@end defopt
+
+@node Editing Tracks
+@chapter Editing Tracks
+
+@cindex track editor
+
+Using @file{emms-tag-editor.el}, emms can set tag informations of tracks
+and write them back to the file with the help of external programs, such
+as `mp3info', `vorbiscomment'.
+
+Use the keybinding @kbd{E} to edit the tags of track under point in the
+playlist or all marked tracks (@pxref{Markable Playlists} for how to
+mark tracks).  The track's tag informations are listed in a special
+buffer `*EMMS-TAGS*' in text format.  Field names are marked in bold
+face and are not editable.  Any tag information is placed behind an
+equal sign and is changable.  A special field `name' is the track's file
+name.  If any change is made in this field, the track's file will be
+renamed to the new name.  When you finished editing the tag infos use
+@kbd{C-c C-c} (which calls @code{emms-tag-editor-submit-and-exit}) to
+submit the changes and close the `*EMMS-TAGS*' buffer.
+
+There are a few commands to perform changes on all tracks.
+
+@defun emms-tag-editor-set-all tag value
+Set TAG to VALUE in all tracks.
+
+If transient-mark-mode is turned on, you can apply the command to a
+selected region.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-replace-in-tag tag from to
+Query and replace text in selected TAG.
+
+For example, if the info-title tag is selected, then only perform
+replacement in title tags.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-transpose-tag tag1 tag2
+Transpose value of TAG1 and TAG2.
+
+If `transient-mark-mode' is on and the mark is active, the changes will
+only take effect on the tracks in the region.
+@end defun
+
+@defun emms-tag-editor-submit arg
+Make modified tags take affect.
+
+With prefix argument, bury the tag edit buffer.
+@end defun
+
+If you want to extend the tag editor to work with file formats other
+than `mp3' and `ogg', have a look at these variables.
+
+@defvr {Variable} emms-tag-editor-formats
+This variable determine how to insert track fields to
+`emms-tag-editor-edit-buffer'.  Emms tag info editable fields is usually
+determined by the extension of track name.  The variable
+`emms-tag-editor-tags' contains all tags that emms track may have.  A
+single charactar is assigned to the tag to make the
+`emms-tag-editor-formats' easier to generate.
+@end defvr
+
+@defvr {Variable} emms-tag-editor-tagfile-functions
+To write tags to track file, an extern program should specified in this
+variable.
+
+If the external program has an interface like `mp3info', you don't have
+to write a function.  Take `mp3' and `ogg' as example.
+@end defvr
+
+@heading Renaming Files
+
+The tag editor is also capable to rename the file of the track at point
+or all files of the marked tracks according to the value this variable.
+
+@defopt emms-tag-editor-rename-format
+When `emms-tag-editor-rename' is invoked the track's file will be
+renamed according this format specification.  The file extension will be
+added automatically.
+
+It uses the format specs defined in @code{emms-tag-editor-tags}.
+
+The default value is "%a - %l - %n - %t", so that files are named
+
+  <Artist> - <Album> - <Tracknumber> - <Title>.<extension>
+
+after renaming.
+@end defopt
+
+To perform the renaming put point on the track you want to rename or
+mark some tracks.  Then hit @kbd{R} which calls this function:
+
+@defun emms-tag-editor-rename
+Rename the file corresponding to track at point or all marked tracks
+according to the value of @code{emms-tag-editor-rename-format}.
+@end defun
+
+@node Emms Mode Line
+@chapter Emms Mode Line
+
+@cindex mode line
+@cindex display emms information
+
+We can display information about the currenty playing track on the
+Emacs mode line using the package `emms-mode-line' which is provided
+by the file @file{emms-mode-line.el}.
+
+To activate this feature invoke:
+
+@lisp
+(require 'emms-mode-line)
+(emms-mode-line 1)
+@end lisp
+
+It is also possible to display the amount of time a track has been
+playing. This feature is defined in the `emms-playing-time' package
+which is provided by the file @file{emms-playing-time.el}.
+
+To use this feature invoke:
+
+@lisp
+(require 'emms-playing-time)
+(emms-playing-time 1)
+@end lisp
+
+Note: `(emms-playing-time -1)' will disable emms-playing-time module
+completely, and is not recommended. (since some other emms modules may
+rely on it, such as `emms-lastfm.el')
+
+Instead, to toggle displaying playing time on mode line, one could call
+`emms-playing-time-enable-display' and
+`emms-playing-time-disable-display'."
+
+@defun emms-playing-time-enable-display
+Display playing time on mode line.
+@end defun
+
+@defun emms-playing-time-disable-display
+Remove playing time from mode line.
+@end defun
+
+@node Music Player Daemon
+@chapter Music Player Daemon
+
+@cindex music player daemon
+@cindex remote interface
+@cindex mpd
+
+Emms provides an interface to the @uref{http://www.musicpd.org/, Music
+Player Daemon}(MusicPD) software. The package is called `emms-player-mpd' and
+is provided by the file @file{emms-player-mpd.el}.
+
+The advantages of using MusicPD as an EMMS backend include the
+following.
+
+@itemize @bullet
+@item minimal CPU usage
+@item fast access of track information
+@item optional crossfade
+@end itemize
+
+@subheading Setup
+
+To load `emms-player-mpd' invoke:
+
+@lisp
+(require 'emms-player-mpd)
+@end lisp
+
+Set the variables @var{emms-player-mpd-server-name} and
+@var{emms-player-mpd-server-port} to the location and port
+(respectively) of your MusicPD server. For example:
+
+@lisp
+(setq emms-player-mpd-server-name "localhost")
+(setq emms-player-mpd-server-port "6600")
+@end lisp
+
+If your MusicPD setup requires a password, you will to set
+@var{emms-player-mpd-server-password} as follows.
+
+@lisp
+(setq emms-player-mpd-server-password "mypassword")
+@end lisp
+
+To get track information from MusicPD, invoke the following:
+
+@lisp
+(add-to-list 'emms-info-functions 'emms-info-mpd)
+@end lisp
+
+Adding `emms-player-mpd' to your Emms player list is accomplished by
+invoking:
+
+@lisp
+(add-to-list 'emms-player-list 'emms-player-mpd)
+@end lisp
+
+If you use absolute file names in your m3u playlists (which is most
+likely), make sure you set @var{emms-player-mpd-music-directory} to
+the value of "music_directory" from your MusicPD config.  There are
+additional options available as well, but the defaults should be
+sufficient for most uses.
+
+You can set @var{emms-player-mpd-sync-playlist} to nil if your master
+EMMS playlist contains only stored playlists.
+
+@subheading Commands provided
+
+@defun emms-player-mpd-connect
+Connect to MusicPD and retrieve its current playlist. Afterward, the
+status of MusicPD will be tracked.
+@end defun
+
+@defun emms-player-mpd-disconnect
+Terminate the MusicPD client process and disconnect from MusicPD.
+@end defun
+
+@defun emms-player-mpd-show &optional insertp
+Describe the current EMMS track in the minibuffer. If INSERTP is
+non-nil, insert the description into the current buffer instead. This
+function uses @var{emms-show-format} to format the current track. It
+differs from @command{emms-show} in that it asks MusicPD for the
+current track, rather than Emms.
+@end defun
+
+@subsubheading Updating the MusicPD database
+
+@defun emms-player-mpd-update-directory dir
+Cause the tracks in DIR to be updated in the MusicPD database.
+@end defun
+
+@defun emms-player-mpd-update-all
+Cause all tracks in the MusicPD music directory to be updated in
+the MusicPD database.
+@end defun
+
+@subsubheading emms-cache.el integration
+
+@defun emms-cache-set-from-mpd-directory dir
+Dump all MusicPD data from DIR into the EMMS cache.
+This is useful to do when you have recently acquired new music.
+@end defun
+
+@defun emms-cache-set-from-mpd-all
+Dump all MusicPD data into the EMMS cache.
+This is useful to do once, just before using emms-browser.el, in
+order to prime the cache.
+@end defun
+
+@subsubheading emms-volume.el integration
+
+To activate this, add the following to your .emacs.
+
+@lisp
+(require 'emms-volume)
+(setq emms-volume-change-function 'emms-volume-mpd-change)
+@end lisp
+
+@node Lyrics
+@chapter Lyrics
+
+@cindex lyrics
+
+We can display the lyrics of a song in time with the music using the
+`emms-lyrics' package provided by the file @file{emms-lyrics.el}.
+
+The lyrics files should have the extention ``.lrc'', and can be placed
+under either the same directory as the music files or
+@var{emms-lyrics-dir}.
+
+To add this feature we invoke:
+
+@lisp
+(require 'emms-lyrics)
+(emms-lyrics 1)
+@end lisp
+
+There are a number of variables we can set to define the way that
+`emms-lyrics' behaves, we can set these directly or by using the
+Customize feature in Emacs.
+
+@defvr {User Option} emms-lyrics-display-on-minibuffer
+If non-nil, display lyrics on minibuffer.
+@end defvr
+
+@defvr {User Option} emms-lyrics-display-on-modeline
+If non-nil, display lyrics on modeline.
+@end defvr
+
+@defvr {User Option} emms-lyrics-dir
+Local lyrics repository.
+@command{emms-lyrics-find-lyric} will look for lyrics in current
+directory(i.e., same as the music file) and this directory.
+@end defvr
+
+@defvr {User Option} emms-lyrics-display-format
+Format for displaying lyrics. "%s" will be replaced by the lyrics
+string.
+@end defvr
+
+@defvr {User Option} emms-lyrics-coding-system
+Coding system used in the output of lyrics.
+@end defvr
+
+@defvr {User Option} emms-lyrics-scroll-p
+Non-nil value will enable lyrics scrolling.
+@end defvr
+
+@defvr {User Option} emms-lyrics-scroll-timer-interval
+Interval between scroller timers. The shorter, the faster.
+@end defvr
+
+We can control `emms-lyrics' with the help of the following functions:
+
+@defun emms-lyrics-start
+Start displaying lyrics.
+@end defun
+
+@defun emms-lyrics-stop
+Stop displaying lyrics.
+@end defun
+
+@defun emms-lyrics-toggle-display-on-minibuffer
+Toggle display lyrics on minibufer.
+@end defun
+
+@defun emms-lyrics-toggle-display-on-modeline
+Toggle display lyrics on mode line.
+@end defun
+
+@defun emms-lyrics-enable
+Enable displaying Emms lyrics.
+@end defun
+
+@defun emms-lyrics-disable
+Disable displaying Emms lyrics.
+@end defun
+
+@defun emms-lyrics-toggle
+Toggle displaying Emms lyrics.
+@end defun
+
+@node Volume
+@chapter Volume
+
+@cindex volume
+
+We can use the `emms-volume' package, as provided by the
+@file{emms-volume.el} file, to manipulate the volume.
+
+@defopt emms-volume-change-amount
+The amount to use when raising or lowering the volume using the
+emms-volume interface.
+
+This should be a positive integer.
+@end defopt
+
+@defun emms-volume-raise
+Increase the volume.
+@end defun
+
+@defun emms-volume-lower
+Decrease the volume.
+@end defun
+
+If you feel like binding those two functions to global keys --- don't do
+it or you'll miss the convenience of `emms-volume-minor-mode'. Instead,
+bind the following two commands to some keys that you like.
+
+@defun emms-volume-mode-plus
+Raise volume and enable or extend the `emms-volume-minor-mode' timeout.
+@end defun
+
+@defun emms-volume-mode-minus
+Lower volume and enable or extend the `emms-volume-minor-mode' timeout.
+@end defun
+
+Example:
+
+@lisp
+(global-set-key (kbd "C-c +") 'emms-volume-mode-plus)
+(global-set-key (kbd "C-c -") 'emms-volume-mode-minus)
+@end lisp
+
+Whenever you use one of these keys or call these functions with
+@kbd{M-x}, Emms will be put into `emms-volume-minor-mode' for a short
+period defined by `emms-volume-mode-timeout'.
+
+@defopt emms-volume-mode-timeout
+The timeout in amount of seconds used by `emms-volume-minor-mode'.
+@end defopt
+
+In this interval you can raise/lower the volume simply by pressing
+@kbd{+} or @kbd{-}, which will also reset the timer to its initial
+value. So instead of pressing @kbd{C-c +} six times to increase volume
+by six steps of @code{emms-volume-change-amount}, you would simply type
+@kbd{C-c + + + + + +}.
+
+
+@node Last.fm
+@chapter Last.fm
+
+@cindex last.fm
+
+Currently the `emms-lastfm' package provided by the file
+@file{emms-lastfm.el} offers the two most important last.fm services.
+
+@enumerate
+@item
+It can submit informations of tracks (artist, title, album) you listen
+to to last.fm to enhance your music profile.
+
+@item
+You can listen to the Last.fm radio. Those are the streams beginning
+with lastfm://.
+@end enumerate
+
+For both services you need a last.fm account and you have to set up
+two variables.
+
+@defopt emms-lastfm-username
+Your last.fm username.
+@end defopt
+
+@defopt emms-lastfm-password
+Your last.fm password.
+@end defopt
+
+To set them in your @file{.emacs} add something like this.
+
+@lisp
+(setq emms-lastfm-username "my-user-name"
+      emms-lastfm-password "very-secret!")
+@end lisp
+
+You can edit them with the `customize' interface, too.
+
+@menu
+* Submitting track informations:: How to submit track information to last.fm.
+* Last.fm radio::                 How to listen to last.fm radio.
+@end menu
+
+@node Submitting track informations
+@section Submitting track informations
+
+These functions enable/disable submission of track informations to
+last.fm.
+
+@defun emms-lastfm-enable
+Start submitting to last.fm. Note that submission will start with the
+next track, not the current one.
+@end defun
+
+@defun emms-lastfm-disable
+Stop submission of track informations.
+@end defun
+
+If you want to enable submission of tracks by default, put this into
+your @file{.emacs}.
+
+@lisp
+(emms-lastfm-activate)
+@end lisp
+
+@node Last.fm radio
+@section Last.fm radio
+
+On http://www.last.fm you'll find lots of links referencing last.fm
+radio stations like lastfm://artist/Metallica/fans. You can listen to
+them using these functions.
+
+@defun emms-lastfm-radio lastfm-url
+Starts playing the stream referenced by @var{lastfm-url}. When run
+interactively you will be prompted for a last.fm URL.
+@end defun
+
+You can also insert Last.fm streams into playlists (or use
+emms-streams.el to listen to them) by activating the player as follows.
+
+@lisp
+(add-to-list 'emms-player-list 'emms-player-lastfm-radio)
+@end lisp
+
+To add a Last.fm stream into the current playlist, do the following:
+@kbd{M-x emms-add-lastfm RET lastfm://rest-of-url RET}. To directly
+start playing use @command{emms-play-lastfm}.
+
+To read more about the concept of the ``current'' playlist
+@xref{Playlists}. To add a last.fm stream to the playlist buffer that's
+currently browsed (which might not be the ``current'' playlist), use
+@command{emms-insert-lastfm} instead.
+
+For your convenience there are some functions which let you choose a
+common radio station without having to remember or type its last.fm URL.
+
+@defun emms-lastfm-radio-similar-artists artist
+Starts playing the similar artist radio of @var{artist}. When run
+interactively you will be prompted for an artist name.
+@end defun
+
+@defun emms-lastfm-radio-global-tag tag
+Starts playing the global tag radio of @var{tag}. When run interactively
+you will be prompted for a tag name.
+@end defun
+
+@defun emms-lastfm-radio-artist-fan artist
+Starts playing the artist fan radio of @var{artist}. When run
+interactively you will be prompted for an artist name.
+@end defun
+
+While listening to a last.fm radio station `emms-lastfm' will try to
+fetch some meta-informations (artist and title) of the currently playing
+song. That's controlled by the following variable:
+
+@defopt emms-lastfm-radio-metadata-period
+When listening to Last.fm Radio every how many seconds should
+emms-lastfm poll for metadata? If set to nil, there won't be any
+polling at all.
+
+The default is 15: That means that the mode line will display the
+wrong (last) track's data for a maximum of 15 seconds. If your
+network connection has a big latency this value may be too
+high. (But then streaming a 128KHz mp3 won't be fun anyway.)
+@end defopt
+
+Even if you set this variable to nil (no polling) you can fetch the
+meta-informations with one of the following functions.
+
+@defun emms-lastfm-radio-request-metadata
+Request the metadata of the current song and display it in the
+mode-line if the `emms-mode-line' package is enabled.
+@end defun
+
+@defun emms-lastfm-np
+Show the currently-playing lastfm radio tune.
+
+If you prefixed the command with @kbd{C-u}, the current song information
+is inserted at point.
+
+Otherwise, display a message with the current song information.
+@end defun
+
+When you listen to last.fm radio you can rate or skip the current song.
+
+@defun emms-lastfm-radio-love
+Inform Last.fm that you love the currently playing song.
+@end defun
+
+@defun emms-lastfm-radio-skip
+Inform Last.fm that you want to skip the currently playing song.
+@end defun
+
+@defun emms-lastfm-radio-ban
+Inform Last.fm that you want to ban the currently playing song.
+@end defun
+
+Ok, that's all.
+
+
+@node Streaming Audio
+@chapter Streaming Audio
+
+@cindex streaming audio
+@cindex internet radio
+
+Emms provides a friendly interface for managing and playing streaming
+audio in addition to the Emms playlist interface. The interface is
+defined in the @file{emms-streams.el} package and can be loaded by
+invoking:
+
+@lisp
+(require 'emms-streams)
+@end lisp
+
+The Emms interface for streaming audio is enabled by default in the
+`emms-all' and `emms-devel' setup levels. For more information about
+Emms setup levels see @xref{Simple Setup}.
+
+Enter the emms-streams interface by invoking @kbd{M-x}
+@command{emms-streams}. The emms-streams interface comes with a
+built-in, eclectic list of streaming audio channels from throughout the
+Web. Emms can of-course play other streams than the ones listed by
+default, you are free to remove any or all of them and add your
+own.@footnote{If you enjoy a particular streaming audio station on the
+Web and think that it belongs in the default list, please send us a
+link and we will gladly add it!}
+
+If you want to play Last.fm streams, invoke the following and use the
+``lastfm'' type when adding a bookmark to a Last.fm stream.
+
+@lisp
+(require 'emms-lastfm)
+@end lisp
+
+The following is a list of the key-bindings for the emms-streams
+interface:
+
+@table @kbd
+@item RET
+@kindex RET (emms-streams)
+@vindex emms-stream-default-action
+Perform the default action when you press RET in the Emms Stream
+interface. Can be either ``add'' or ``play''. The default is ``add'',
+which adds the station under point to the Emms playlist. When
+@var{emms-stream-default-action} is ``play'' then Emms will play the
+streaming audio channel under point.
+@item q
+@kindex q (emms-streams)
+@findex emms-stream-quit
+Quit the emms-streams interface.
+@item a
+@kindex a (emms-streams)
+@findex emms-stream-add-bookmark
+Add a bookmark to a streaming audio URL to the list.
+@item d
+@kindex d (emms-streams)
+@findex emms-stream-delete-bookmark
+Remove a bookmark to a streaming audio URL from the list.
+@item e
+@kindex e (emms-streams)
+@findex emms-stream-edit-bookmark
+Edit the details of the bookmark under point.
+@item h
+@kindex h (emms-streams)
+@findex describe-mode
+Describe the emms-streams mode.
+@item n
+@kindex n (emms-streams)
+@findex emms-stream-next-line
+Move to the next line in the emms-streams buffer (same as C-n).
+@item p
+@kindex p (emms-streams)
+@findex emms-stream-previous-line
+Move to the previous line in the emms-streams buffer (same as C-p).
+@item s
+@kindex s (emms-streams)
+@findex emms-stream-save-bookmarks-file
+Save the bookmarks in the emms-streams interface to disk. The
+bookmarks will be to the location designated in the variable
+@var{emms-stream-bookmarks-file}.
+@item i
+@kindex i (emms-streams)
+@findex emms-stream-info-bookmark
+Return information about the streaming audio at the URL of the
+bookmark under point. Note that this will only work if the
+`emms-stream-info' has already been loaded.
+@end table
+
+@c including the relevant licenses
+@include gpl.texi
+@include fdl.texi
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@node Function Index
+@unnumbered Function Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
+@node Keybinding Index
+@unnumbered Keybinding Index
+@printindex ky
+
+@bye