Skip to content
Newer
Older
100644 157 lines (136 sloc) 5.96 KB
5f7c1a4 @dbrock Add README.rdoc.
authored Sep 22, 2010
1 = Bongo
2
5c0e5fc @dbrock Add more introductory text to README.rdoc.
authored Sep 23, 2010
3 Bongo is a flexible and usable media player for GNU Emacs. If you
4 store your music collection locally and use structured file names,
5 then Bongo is a great way for you to play music from within Emacs.
6
7 == Getting started
8
9 Once your media collection is good to go (see below), getting started
10 with Bongo is easy. Add the Bongo directory to your
11 ‘<tt>load-path</tt>’, and then run “<tt>M-x load-library RET bongo
12 RET</tt>”. Here’s what you’ll want to put in your <tt>~/.emacs</tt>:
13
14 ;; Change this to the correct directory name for you.
15 (add-to-list 'load-path "~/src/bongo")
16 (autoload 'bongo "bongo"
17 "Start Bongo by switching to a Bongo buffer." t)
18
19 The first thing you might want to do is skim through the customization
20 group for Bongo (run “<tt>M-x customize-group RET bongo RET</tt>”).
21 It might be fun to browse through all of it, but right now the most
22 important option is ‘<tt>bongo-enabled-backends</tt>’. This option
23 determines what external programs Bongo will use to play stuff.
24 Bongo will try to find a reasonable set of default backends by looking
25 for the programs <tt>vlc</tt>, <tt>mpg123</tt>, <tt>ogg123</tt>,
26 <tt>speexdec</tt>, <tt>timidity</tt>, and <tt>mikmod</tt>. Check to
27 make sure that this looks good before moving on. You can skip most
28 other stuff for now.
5f7c1a4 @dbrock Add README.rdoc.
authored Sep 22, 2010
29
30 == Your media collection
31
32 For the best Bongo user experience, your media files
33 should have hierarchical file names. That is, they should
34 be named according to one of the following templates:
35
36 * <tt>Artist Name - 2005 - Album Title - 01 - Track Title.ogg</tt>
37 * <tt>Artist Name - Album Title - 01 - Track Title.ogg</tt>
38 * <tt>Artist Name - 2005 - Album Title - Track Title.ogg</tt>
39 * <tt>Artist Name - Album Title - Track Title.ogg</tt>
40 * <tt>Artist Name - Album Title - Track Title.ogg</tt>
41 * <tt>Artist Name - Track Title.ogg</tt>
42 * <tt>Track Title.ogg</tt>
43
44 In other words, any reasonable combination of artist name, album year,
45 album title, track index, and track title, in the right order (less
46 specific to more specific), should be okay. Embedding the metadata in
47 the file name is not only very practical, but speeds up the process of
48 fetching it.
49
50 You don’t have to use “<tt>ogg</tt>” as the file name extension for
51 all your media, of course, and you don’t have to use “<tt> - </tt>” as
52 the separator. However, you can’t use slash as the separator and just
53 have your files in nested directories. The information needs to be in
54 the basename of each file.
55
56 (XXX: This restriction should be relaxed. Maybe by adding a variable
57 called ‘<tt>bongo-file-name-roots</tt>’, which would define one or
58 more sets of file names that were to be parsed as if “<tt>/</tt>” were
59 the field separator.)
60
61 Many people use tags (e.g., ID3v2 tags or Ogg tags) for their metadata
62 and don’t care about file names. Luckily, Bongo comes with a tool
8729399 @dbrock Move tree-from-tags.rb into contrib/.
authored Sep 23, 2010
63 called <tt>tree-from-tags.rb</tt> (located in the <tt>contrib/</tt>
64 directory), which can be used to create a hierarchy of nicely-named
65 symlinks into your tagged media collection.
5f7c1a4 @dbrock Add README.rdoc.
authored Sep 22, 2010
66
67 == Commands
68
69 To start Bongo, run “<tt>M-x bongo</tt>”. To insert a file or a whole
70 directory of files, type “<tt>i</tt>”. Then hit <tt>RET</tt> to play
71 one of them.
72
73 To see a list of available commands, run ‘<tt>describe-mode</tt>’
74 (usually bound to “<tt><f1> m</tt>” or “<tt>C-h m</tt>”).
75 Here are some common ones, for your convenience:
76
77 <tt>RET</tt>::
78 Start playing the track at point, and continue playing tracks when
79 that track finishes.
80 <tt>3 RET</tt>::
81 Start playing the track under point, and continue playing tracks,
82 but stop after playing the third track below point.
83 <tt>C-c C-s</tt>::
84 Stop playback (or start, if already stopped).
85 <tt>3 C-c C-s</tt>::
86 Stop playback after the next three tracks finish playing.
87 <tt>C-u C-c C-s</tt>::
88 Stop playback after each track finishes playing (this is good when
89 playing movies, for example).
90 <tt>C-u C-u C-c C-s</tt>::
91 Stop playback after the track at point finishes playing.
92 <tt>C-c C-n</tt>::
93 Start playing the next track.
94 <tt>2 C-c C-n</tt>::
95 Skip the next track and start playing the one after that.
96 <tt>C-u C-c C-n</tt>::
97 Play the next track after each track finishes playing (this undoes
98 the effect of <tt>C-u C-c C-s</tt>).
99 <tt>C-c C-r</tt>::
100 Start playing a random track.
101 <tt>C-u C-c C-r</tt>::
102 Play tracks in random order.
103 <tt>SPC</tt>::
104 Pause playback, if supported by the backend.
105 <tt>s</tt>::
106 Seek backward or forward, if supported by the backend.
107 <tt>M-p</tt>, <tt>M-n</tt>::
108 Move point to the previous or next header line.
109 <tt>I u RET</tt>::
110 Insert a URI.
111 <tt>I c RET</tt>::
112 Insert the tracks of an audio CD.
113 <tt>I TAB</tt>::
114 List other kinds of tracks.
115 <tt>l</tt>::
116 Move point to the current track and recenter.
117 <tt>c</tt>::
118 Copy the track or section under point.
119 <tt>k</tt>::
120 Kill the track or section under point.
121 <tt>C-w</tt>::
122 Kill all tracks and sections in the region.
123 <tt>y</tt>::
124 Reinsert the last copied or killed stuff.
125 <tt>q</tt>::
126 Quit Bongo by selecting another buffer.
127
128 Here are some commands that are nice if you use library
129 buffers:
130
131 <tt>e</tt>::
132 Append the track under point or the region (if active) to the end of
133 the playlist buffer.
134 <tt>E</tt>::
135 Insert the track under point or the region (if active) into the
136 playlist buffer, directly below the track that’s currently playing.
137 <tt>3 e</tt>, <tt>3 E</tt>::
138 Enqueue the track at point and the two after that to the
139 playlist buffer.
140 <tt>h</tt>::
141 Switch from playlist to library, or vice versa.
142 <tt>C-u h</tt>::
143 Switch from playlist to library, or vice versa, leaving the original
144 buffer visible in another window.
145 <tt>C-x C-s</tt>::
146 Save the current buffer (use “<tt><em>foo</em>.bongo-library</tt>”
147 file names for library buffers).
148
149 Finally, here are another few handy commands:
150
151 <tt>r</tt>::
152 Rename the file corresponding to the track under point.
153 <tt>d</tt>::
154 Open a Dired buffer containing the track under point.
155 <tt>v</tt>::
156 Change the audio volume (requires http://github.com/dbrock/volume-el).
Something went wrong with that request. Please try again.