added the emms browser to the manual

darcs-hash:20060820124739-85c19-933b5171ab5d6636ef9c2fbe494a0f8a39fde146.gz

1 files changed, 406 insertions, 7 deletions

diff --git a/emms.texinfo b/emms.texinfo
index 9fe99d3..e4cc874 100644
--- a/emms.texinfo
+++ b/emms.texinfo
@@ -61,10 +61,11 @@ Emms basics
 * Playlists::           How Emms organizes media
 
 Advanced Features
-* Track Information::           More narrative track descriptions.
+* Track Information::        More narrative track descriptions.
 * Interactive Playlists::    Interactive Playlists.
 
 Modules and Extensions
+* The Browser::         Advanced metadata browsing.
 * Sorting Playlists::   Sorting the order of the tracks.
 * Emms Mode Line::      Emms information on the mode line.
 * Music Player Daemon:: Interface to Music Player Daemon.
@@ -938,9 +939,8 @@ 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:
+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)
@@ -1013,13 +1013,13 @@ with the filename and set a filter.
 @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 send the
-output ``@@P 0'' (the signal of mpg321 that the song ended) to 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 "@@P 0" output)
+  (when (string-match "(at-sign)P 0" output)
     (emms-mpg321-remote-stop)))
 @end lisp
 @noindent
@@ -1048,6 +1048,405 @@ from @file{emms-player-simple.el}
 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 powerfull 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