Initial commit (CVS 2005-09-11)

darcs-hash:20050911200506-2189f-48a136015e33465c3cf09940ce935ec2203df463.gz

1 files changed, 171 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..8a1e97a
--- /dev/null
+++ b/README
@@ -0,0 +1,171 @@
+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))
+