= Bongo

Bongo is a flexible and usable media player for GNU Emacs.  If you
store your music collection locally and use structured file names,
then Bongo is a great way for you to play music from within Emacs.

== Getting started

Once your media collection is good to go (see below), getting started
with Bongo is easy.  Add the Bongo directory to your
‘<tt>load-path</tt>’, and then run “<tt>M-x load-library RET bongo
RET</tt>”.  Here’s what you’ll want to put in your <tt>~/.emacs</tt>:

  ;; Change this to the correct directory name for you.
  (add-to-list 'load-path "~/src/bongo")
  (autoload 'bongo "bongo"
    "Start Bongo by switching to a Bongo buffer." t)

The first thing you might want to do is skim through the customization
group for Bongo (run “<tt>M-x customize-group RET bongo RET</tt>”).
It might be fun to browse through all of it, but right now the most
important option is ‘<tt>bongo-enabled-backends</tt>’.  This option
determines what external programs Bongo will use to play stuff.
Bongo will try to find a reasonable set of default backends by looking
for the programs <tt>vlc</tt>, <tt>mpg123</tt>, <tt>ogg123</tt>,
<tt>speexdec</tt>, <tt>timidity</tt>, and <tt>mikmod</tt>.  Check to
make sure that this looks good before moving on.  You can skip most
other stuff for now.

== Your media collection

For the best Bongo user experience, your media files
should have hierarchical file names.  That is, they should
be named according to one of the following templates:

* <tt>Artist Name - 2005 - Album Title - 01 - Track Title.ogg</tt>
* <tt>Artist Name - Album Title - 01 - Track Title.ogg</tt>
* <tt>Artist Name - 2005 - Album Title - Track Title.ogg</tt>
* <tt>Artist Name - Album Title - Track Title.ogg</tt>
* <tt>Artist Name - Album Title - Track Title.ogg</tt>
* <tt>Artist Name - Track Title.ogg</tt>
* <tt>Track Title.ogg</tt>

In other words, any reasonable combination of artist name, album year,
album title, track index, and track title, in the right order (less
specific to more specific), should be okay.  Embedding the metadata in
the file name is not only very practical, but speeds up the process of
fetching it.

You don’t have to use “<tt>ogg</tt>” as the file name extension for
all your media, of course, and you don’t have to use “<tt> - </tt>” as
the separator.  However, you can’t use slash as the separator and just
have your files in nested directories.  The information needs to be in
the basename of each file.

(XXX: This restriction should be relaxed.  Maybe by adding a variable
called ‘<tt>bongo-file-name-roots</tt>’, which would define one or
more sets of file names that were to be parsed as if “<tt>/</tt>” were
the field separator.)

Many people use tags (e.g., ID3v2 tags or Ogg tags) for their metadata
and don’t care about file names.  Luckily, Bongo comes with a tool
called <tt>tree-from-tags.rb</tt> (located in the <tt>contrib/</tt>
directory), which can be used to create a hierarchy of nicely-named
symlinks into your tagged media collection.

== Commands

To start Bongo, run “<tt>M-x bongo</tt>”.  To insert a file or a whole
directory of files, type “<tt>i</tt>”.  Then hit <tt>RET</tt> to play
one of them.

To see a list of available commands, run ‘<tt>describe-mode</tt>’
(usually bound to “<tt><f1> m</tt>” or “<tt>C-h m</tt>”).
Here are some common ones, for your convenience:

<tt>RET</tt>::
  Start playing the track at point, and continue playing tracks when
  that track finishes.
<tt>3 RET</tt>::
  Start playing the track under point, and continue playing tracks,
  but stop after playing the third track below point.
<tt>C-c C-s</tt>::
  Stop playback (or start, if already stopped).
<tt>3 C-c C-s</tt>::
  Stop playback after the next three tracks finish playing.
<tt>C-u C-c C-s</tt>::
  Stop playback after each track finishes playing (this is good when
  playing movies, for example).
<tt>C-u C-u C-c C-s</tt>::
  Stop playback after the track at point finishes playing.
<tt>C-c C-n</tt>::
  Start playing the next track.
<tt>2 C-c C-n</tt>::
  Skip the next track and start playing the one after that.
<tt>C-u C-c C-n</tt>::
  Play the next track after each track finishes playing (this undoes
  the effect of <tt>C-u C-c C-s</tt>).
<tt>C-c C-r</tt>::
  Start playing a random track.
<tt>C-u C-c C-r</tt>::
  Play tracks in random order.
<tt>SPC</tt>::
  Pause playback, if supported by the backend.
<tt>s</tt>::
  Seek backward or forward, if supported by the backend.
<tt>M-p</tt>, <tt>M-n</tt>::
  Move point to the previous or next header line.
<tt>I u RET</tt>::
  Insert a URI.
<tt>I c RET</tt>::
  Insert the tracks of an audio CD.
<tt>I TAB</tt>::
  List other kinds of tracks.
<tt>l</tt>::
  Move point to the current track and recenter.
<tt>c</tt>::
  Copy the track or section under point.
<tt>k</tt>::
  Kill the track or section under point.
<tt>C-w</tt>::
  Kill all tracks and sections in the region.
<tt>y</tt>::
  Reinsert the last copied or killed stuff.
<tt>q</tt>::
  Quit Bongo by selecting another buffer.

Here are some commands that are nice if you use library
buffers:

<tt>e</tt>::
  Append the track under point or the region (if active) to the end of
  the playlist buffer.
<tt>E</tt>::
  Insert the track under point or the region (if active) into the
  playlist buffer, directly below the track that’s currently playing.
<tt>3 e</tt>, <tt>3 E</tt>::
  Enqueue the track at point and the two after that to the
  playlist buffer.
<tt>h</tt>::
  Switch from playlist to library, or vice versa.
<tt>C-u h</tt>::
  Switch from playlist to library, or vice versa, leaving the original
  buffer visible in another window.
<tt>C-x C-s</tt>::
  Save the current buffer (use “<tt><em>foo</em>.bongo-library</tt>”
  file names for library buffers).

Finally, here are another few handy commands:

<tt>r</tt>::
  Rename the file corresponding to the track under point.
<tt>d</tt>::
  Open a Dired buffer containing the track under point.
<tt>v</tt>::
  Change the audio volume (requires http://github.com/dbrock/volume-el).
