aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--emms.texinfo262
1 files changed, 142 insertions, 120 deletions
diff --git a/emms.texinfo b/emms.texinfo
index 118dda5..613ab5c 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -51,22 +51,22 @@ This is the Manual for the Emacs Multimedia System
* The GNU FDL:: The license for this documentation.
Starting out
-* Introduction:: Introduction to Emms
-* Installation:: How to install Emms on your System
-* Quick Setup:: Quick start in Emms
-* Configuration Example:: Bare bones configuration
+* Introduction:: Introduction to Emms.
+* Installation:: How to install Emms on your System.
+* Quick Setup:: Quick start in Emms.
+* Configuration Example:: Bare bones configuration.
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
+* 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.
Advanced Features
-* Info Tags:: More narrative track descriptions
-* The Playlist Buffer:: Interactive Playlist
-* Extending Emms:: How to define new players and modules
-* Streaming Audio:: Interface to streaming audio
+* Info Tags:: More narrative track descriptions.
+* The Playlist Buffer:: Interactive Playlist.
+* Extending Emms:: How to define new players and modules.
+* Streaming Audio:: Interface to streaming audio.
Indices
* Concept Index::
@@ -74,6 +74,8 @@ Indices
* Variable Index::
* Keybinding Index::
+@c FIXME: the detailed listing needs to be re-generated after the
+@c above is finished.
@detailmenu
--- The Detailed Node Listing ---
@@ -189,7 +191,7 @@ just need the following line,
which installs the core of Emms.
Now we need to do some configuration.
-
+@c FIXME: Renaming of emms-default? New user levels?
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
@@ -201,7 +203,6 @@ complexity level of the user interface. Here's an example:
@end lisp
Here is a list of the interface complexity options:
-@c FIXME: what is actually included with emms-defaults for each level?
@table @samp
@item minimalistic
Define the players and play directory but nothing more.
@@ -211,10 +212,6 @@ minimalistic installation plus a user interface to the playlists.
@item default
Features the above plus the reading the info from tagged Mp3 and Ogg
files.
-@item advanced
-@c FIXME: see above
-@item cvs
-@c FIXME: see above
@end table
Now your configuration is done.
@@ -227,9 +224,9 @@ The (optional) directory is used for
@cindex Configuration Example
-The following code fragment provides a minimal EMMS setup without
+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
+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').
@@ -346,60 +343,118 @@ Sort the current playlist. This uses
@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.
+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
-@c FIXME: go over all these first, then add new ones
-The file @file{emms.el} provides all basic functions for playing
-music, generating a playlist and defining players.
+@c FIXME: go over all these first, then add new ones. Also divide
+@c these into subsections to keep the overall size down.
+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
+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 play
-files. Unless you use @file{emms-player-simple} you have to define a
-player with @command{emms-define-player} first.
+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}. The only argument %s is the
-string returned by @command{emms-track-description}
+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 for repeating the playlist after playing the last track.
+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
-A function to be called to give a nice, user-friendly description of
-the track passed to it as an argument.
+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 `sort').
-@end defopt
-@defopt emms-playlist-changed-hook
-A hook run when the playlist of Emms has changed.
-@end defopt
-@defopt emms-playlist-current-changed-hook
-A hook run when the current track in the playlist of Emms has
-changed.
+track should be sorted before the second (see also @code{sort}).
@end defopt
+
+@node Hooks
+@section Hooks
+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.
+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
+The core file also defines all the functions important to the basic
+use of Emms.
+@c FIXME: sort these so that they make sense
+
+There are functions which deal with movement in the playlist.
@defun emms-next-noerror
-Play the next track in the playlist, but don't signal an error when
-we're at the end. This should be called when no player is playing.
-This is a suitable function to put in @var{emms-player-stopped-hook}.
+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-sort
-Sort the playlist.
+@defun emms-playlist-next
+Move to the previous track in the current buffer.
@end defun
-@defun emms-sort-track-name-less-p a b
-Return non-nil if the track name of @var{a} is before @var{b}.
+@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
@@ -410,80 +465,27 @@ Return the type of @var{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{inexistent} (or nil if not given).
+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
-A simple function to give a user-readable description of @var{track}.
-If it's a file track, it's just the filename.
-Else it's the type and the name with a colon in between.
-@end defun
-@defun emms-playlist-current
-Return a description of the currently playing track.
-This uses @var{emms-track-description-function}.
-@end defun
-@defun emms-playlist-current-track
-Return the currently playing track.
-@end defun
-@defun emms-playlist-get n
-Return a description of the @var{n}th entry of the current playlist.
-This uses `emms-track-description-function'
-@end defun
-@defun emms-playlist-get-track n
-Return the @var{n}th track of the current playlist.
-@end defun
-@defun emms-playlist-set-playlist new
-Set the playlist to @var{new}.
-This runs `emms-playlist-changed-hook'.
-@end defun
-@defun emms-playlist-get-playlist
-Return the current playlist.
-@end defun
-@defun emms-playlist-set-current n
-Set the current track in the playlist to @var{n} (a number).
-This runs `emms-playlist-current-changed-hook'.
-@end defun
-@defun emms-playlist-get-current
-Return the number of the current track, or nil if the playlist is
-empty.
-@end defun
-@defun emms-playlist-next
-Advance the current track to the next entry in the playlist and
-return non-nil. Return nil if there is no next track.
-@end defun
-@defun emms-playlist-previous
-Set the current track to the previous entry in the playlist and
-return non-nil. Return nil if there is no previous track.
-@end defun
-@defun emms-playlist-add seq &optional idx
-Add each track of the sequence @var{seq} to the current playlist.
-Insert at @var{idx}, which defaults to the end.
-@end defun
-@defun emms-playlist-remove idx
-Remove track at @var{idx} from playlist.
-@end defun
-@defun emms-playlist-shuffle
-Shuffle the current playlist.
-@end defun
-@defun emms-playlist-sort
-Sort the current playlist according to `emms-sort-lessp-function'
-@end defun
-@defun emms-playlist-shuffle-vector vector
-Shuffle @var{vector}.
-@end defun
-@defun emms-playlist-sort-vector vector
-Sort @var{vector} according to `emms-sort-lessp-function'.
-@end defun
-@defun emms-source-play lis
-Play the tracks returned by @var{lis}.
+Return a description of @var{track}. This function uses
+@var{emms-track-description-function}.
@end defun
@defun emms-player-for track
-Return the player which is responsible for @var{track}, or nil if
-there is none.
+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
@@ -491,9 +493,29 @@ Start playing @var{track}.
Stop the currently playing player.
@end defun
@defun emms-player-stopped
-Declare that the current player has finished playing.
-This should only be called by a player.
+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
+@defun emms-sort-track-name-less-p a b
+Return non-nil if the track name of @var{A} sorts before @var{B}.
+@end defun
+@defun emms-ensure-player-playing-p
+Raise an error if no player is playing right now.
+@end defun
+
+For more basic commands defined in the core file see @xref{Basic
+Commands}.
@node Sources
@chapter Sources
@@ -547,7 +569,7 @@ Return a regexp that matches everything any player (that supports
files) can play.
@end defun
@defun emms-save-playlist filename
-Export the current playlist as to @var{filename}. See also
+Export the current playlist as to @var{filename}. See also
@command{emms-source-playlist-file}.
@end defun
@defun emms-locate
@@ -876,7 +898,7 @@ should return the text to be inserted in the playlist.
@end defopt
@defopt emms-pbi-playlist-entry-max-length
The maximum length of an entry in the playlist. If this is nil, the
-entire string provided by `emms-track-description-function'. will be
+entire string provided by `emms-track-description-function'. will be
used. Beware, the output of that function is cut off to fit the
max-length before running `emms-pbi-playlist-entry-generate-function'.
@end defopt
@@ -1181,8 +1203,8 @@ interface:
@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'',
+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.