diff options
Diffstat (limited to 'emms.texinfo')
| -rw-r--r-- | emms.texinfo | 2419 |
1 files changed, 0 insertions, 2419 deletions
diff --git a/emms.texinfo b/emms.texinfo deleted file mode 100644 index 5c9b5b0..0000000 --- a/emms.texinfo +++ /dev/null @@ -1,2419 +0,0 @@ -\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 |