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 ‘load-path’, and then run “M-x load-library RET bongo RET”. Here’s what you’ll want to put in your ~/.emacs:

;; 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 “M-x customize-group RET bongo RET”). It might be fun to browse through all of it, but right now the most important option is ‘bongo-enabled-backends’. 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 vlc, mpg123, ogg123, speexdec, timidity, and mikmod. 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:

• Artist Name - 2005 - Album Title - 01 - Track Title.ogg

• Artist Name - Album Title - 01 - Track Title.ogg

• Artist Name - 2005 - Album Title - Track Title.ogg

• Artist Name - Album Title - Track Title.ogg

• Artist Name - Album Title - Track Title.ogg

• Artist Name - Track Title.ogg

• Track Title.ogg

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 “ogg” as the file name extension for all your media, of course, and you don’t have to use “ - ” 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 ‘bongo-file-name-roots’, which would define one or more sets of file names that were to be parsed as if “/” 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 tree-from-tags.rb (located in the contrib/ directory), which can be used to create a hierarchy of nicely-named symlinks into your tagged media collection.

Commands¶ ↑

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

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

RET

Start playing the track at point, and continue playing tracks when that track finishes.

3 RET

Start playing the track under point, and continue playing tracks, but stop after playing the third track below point.

C-c C-s

Stop playback (or start, if already stopped).

3 C-c C-s

Stop playback after the next three tracks finish playing.

C-u C-c C-s

Stop playback after each track finishes playing (this is good when playing movies, for example).

C-u C-u C-c C-s

Stop playback after the track at point finishes playing.

C-c C-n

Start playing the next track.

2 C-c C-n

Skip the next track and start playing the one after that.

C-u C-c C-n

Play the next track after each track finishes playing (this undoes the effect of C-u C-c C-s).

C-c C-r

Start playing a random track.

C-u C-c C-r

Play tracks in random order.

SPC

Pause playback, if supported by the backend.

s

Seek backward or forward, if supported by the backend.

M-p, M-n

Move point to the previous or next header line.

I u RET

Insert a URI.

I c RET

Insert the tracks of an audio CD.

I TAB

List other kinds of tracks.

l

Move point to the current track and recenter.

c

Copy the track or section under point.

k

Kill the track or section under point.

C-w

Kill all tracks and sections in the region.

y

Reinsert the last copied or killed stuff.

q

Quit Bongo by selecting another buffer.

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

e

Append the track under point or the region (if active) to the end of the playlist buffer.

E

Insert the track under point or the region (if active) into the playlist buffer, directly below the track that’s currently playing.

3 e, 3 E

Enqueue the track at point and the two after that to the playlist buffer.

h

Switch from playlist to library, or vice versa.

C-u h

Switch from playlist to library, or vice versa, leaving the original buffer visible in another window.

C-x C-s

Save the current buffer (use “foo.bongo-library”file names for library buffers).

Finally, here are another few handy commands:

r

Rename the file corresponding to the track under point.

d

Open a Dired buffer containing the track under point.

v

Change the audio volume (requires github.com/dbrock/volume-el).