diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 171 |
1 files changed, 171 insertions, 0 deletions
@@ -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)) + |