c9c2ca27 |
1 | .TH ABCDE 1 |
2 | .SH NAME |
99d009fa |
3 | abcde \- Grab an entire CD and compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format. |
c9c2ca27 |
4 | .SH SYNOPSIS |
5 | .B abcde |
6 | .I [options] [tracks] |
7 | .SH DESCRIPTION |
8 | Ordinarily, the process of grabbing the data off a CD and encoding it, then |
9 | tagging or commenting it, is very involved. |
10 | .BR abcde |
11 | is designed to automate this. It will take an entire CD and convert it into |
12 | a compressed audio format - Ogg/Vorbis, MPEG Audio Layer III, Free Lossless |
99d009fa |
13 | Audio Codec (FLAC), Ogg/Speex or MPP/MP+(Musepack). With one command, it will: |
c9c2ca27 |
14 | .TP |
15 | .B * |
16 | Do a CDDB query over the Internet to look up your CD or use a locally stored CDDB entry |
17 | .TP |
18 | .B * |
19 | Grab a track from your CD |
20 | .TP |
21 | .B * |
99d009fa |
22 | Compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format |
c9c2ca27 |
23 | .TP |
24 | .B * |
25 | Comment or ID3 tag it |
26 | .TP |
27 | .B * |
28 | Give it an intelligible filename |
29 | .TP |
30 | .B * |
31 | Delete the intermediate WAV file (or save it for later use) |
32 | .TP |
33 | .B * |
34 | Repeat until finished |
35 | .SH OPTIONS |
36 | .TP |
37 | .B \-1 |
38 | Encode the whole CD in a single file. The resulting file uses the CD title |
39 | for tagging. |
40 | .TP |
41 | .B \-a [actions] |
42 | Comma-delimited list of actions to perform. Can be one or more of: |
43 | cddb, read, normalize, encode, tag, move, playlist, clean. Normalize |
44 | and encode imply read. Tag implies cddb, read, encode. Move implies |
45 | cddb, read, encode, tag. Playlist implies cddb. The default is to |
46 | do all actions except normalize and playlist. |
47 | .TP |
48 | .B \-b |
49 | Enable batch mode normalization. See the BATCH configuration variable. |
50 | .TP |
51 | .B \-c [filename] |
52 | Specifies an additional configuration file to parse. Configuration options |
53 | in this file override those in /etc/abcde.conf or $HOME/.abcde.conf. |
54 | .TP |
55 | .B \-C [discid] |
56 | Allows you to resume a session for |
57 | .I discid |
58 | when you no longer have the CD available (abcde will automatically resume if |
59 | you still have the CD in the drive). You must have already finished at |
60 | least the "read" action during the previous session. |
61 | .TP |
62 | .B \-d [devicename] |
63 | CD\-ROM block device that contains audio tracks to be read. |
64 | .TP |
65 | .B \-D |
66 | Capture debugging information (you'll want to redirect this \- try 'abcde \-D |
67 | 2>logfile') |
68 | .TP |
04609998 |
69 | .B \-f |
70 | Force the use of a locally cached CDDB entry and fallback to a template if none |
71 | is found. For faster network-disconnected operation. |
72 | .TP |
c9c2ca27 |
73 | .B \-j [number] |
74 | Start [number] encoder processes at once. Useful for SMP systems. Overrides |
75 | the MAXPROCS configuration variable. Set it to "0" when using distmp3 to avoid |
76 | local encoding processes. |
77 | .TP |
78 | .B \-k |
79 | Keep the wav files after encoding. |
80 | .TP |
81 | .B \-l |
82 | Use the low-diskspace algorithm. See the LOWDISK configuration variable. |
83 | .TP |
84 | .B \-L |
85 | Use a local CDDB repository. See CDDBLOCALDIR variable. |
86 | .TP |
87 | .B -n |
88 | Do not query CDDB database. Create and use a template. Edit the template to |
89 | provide song names, artist(s), ... |
90 | .TP |
91 | .B -N |
92 | Non interactive mode. Do not ask anything from the user. Just go ahead. |
93 | .TP |
94 | .B -m |
95 | Create DOS-style playlists, modifying the resulting one by adding CRLF line |
96 | endings. Some hardware players insist on having those to work. |
97 | .TP |
98 | .B \-o [filetype] |
99d009fa |
99 | Select output type. Can be "ogg", "mp3", "flac", "spx" or "mpc". Specify a |
c9c2ca27 |
100 | comma-delimited list of output types to obtain all specified types. See |
101 | the OUTPUTTYPE configuration variable. |
102 | .TP |
103 | .B \-p |
104 | Pads track numbers with 0\'s. |
105 | .TP |
106 | .B \-r [hosts...] |
107 | Remote encode on this comma-delimited list of machines using distmp3. See |
108 | the REMOTEHOSTS configuration variable. |
109 | .TP |
99d009fa |
110 | .B \-s [number] |
79e3928b |
111 | [DEPRECATED: use -t, see below] |
99d009fa |
112 | .TP |
c9c2ca27 |
113 | .B \-S [speed] |
114 | Set the speed of the CD drive. Needs CDSPEED and CDSPEEDOPTS set properly |
115 | and both the program and device must support the capability. |
116 | .TP |
79e3928b |
117 | .B \-t [number] |
118 | Start the numbering of the tracks at a given number. It only affects the |
119 | filenames and the playlist. Internal (tag) numbering remains the same. |
120 | .TP |
121 | .B \-T [number] |
122 | Same as \-t but changes also the internal (tag) numbering. Keep in mind that |
123 | the default TRACK tag for MP3 is $T/$TRACKS so it is changed to simply $T. |
124 | .TP |
c9c2ca27 |
125 | .B \-v |
126 | Show the version and exit |
127 | .TP |
128 | .B \-V |
129 | Be a bit more verbose. On slow networks the CDDB requests might give the |
130 | sensation nothins is happening. |
131 | .TP |
132 | .B \-x |
133 | Eject the CD when all tracks have been read. See the EJECTCD configuration |
134 | variable. |
135 | .TP |
136 | .B \-h |
137 | Get help information. |
138 | .TP |
139 | .B [tracks] |
140 | A list of tracks you want abcde to process. If this isn't specified, abcde |
141 | will process the entire CD. Accepts ranges of track numbers - |
142 | "abcde 1-5 7 9" will process tracks 1, 2, 3, 4, 5, 7, and 9. |
143 | .SH OUTPUT |
144 | Each track is, by default, placed in a separate file named after the track |
9f659ada |
145 | in a subdirectory named after the artist under the current directory. |
c9c2ca27 |
146 | This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT |
9f659ada |
147 | variables in your abcde.conf. Each file is given an extension identifying |
148 | its compression format, '.ogg', '.mp3', '.flac', '.spx', or '.mpc'. |
c9c2ca27 |
149 | .SH CONFIGURATION |
150 | abcde sources two configuration files on startup - /etc/abcde.conf and |
151 | $HOME/.abcde.conf, in that order. |
152 | .TP |
153 | The configuration variables have to be set as follows: |
154 | .TP |
155 | .B VARIABLE=value |
c9c2ca27 |
156 | Except when "value" needs to be quoted or otherwise interpreted. If other |
157 | variables within "value" are to be expanded upon reading the configuration |
158 | file, then double quotes should be used. If they are only supposed to be |
159 | expanded upon use (for example OUTPUTFORMAT) then single quotes must be used. |
160 | .TP |
161 | All sh escaping/quoting rules apply. |
162 | .TP |
163 | Here is a list of options abcde recognizes: |
164 | .TP |
165 | .B CDDBURL |
166 | Specifies a server to use for CDDB lookups. |
167 | .TP |
168 | .B OGGENCODERSYNTAX |
169 | Specifies the style of encoder to use for the Ogg/Vorbis encoder. Valid options |
170 | are \'oggenc\' (default for Ogg/Vorbis) and \'vorbize\'. |
171 | This affects the default location of the binary, |
172 | the variable to pick encoder command-line options from, and where the options |
173 | are given. |
174 | .TP |
175 | .B MP3ENCODERSYNTAX |
176 | Specifies the style of encoder to use for the MP3 encoder. Valid options are |
177 | \'lame\' (default for MP3), \'gogo\', \'bladeenc\', \'l3enc\' and \'mp3enc\'. |
178 | Affects the same way as explained above for Ogg/Vorbis. |
179 | .TP |
180 | .B FLACENCODERSYNTAX |
181 | Specifies the style of encoder to use for the FLAC encoder. At this point only |
182 | \'flac\' is available for FLAC encoding. |
183 | .TP |
184 | .B SPEEXENCODERSYNTAX |
185 | Specifies the style of encoder to use for Speex encoder. At this point only |
186 | \'speexenc\' is available for Ogg/Speex encoding. |
187 | .TP |
99d009fa |
188 | .B MPPENCODERSYNTAX |
189 | Specifies the style of encoder to use for MPP/MP+ (Musepack) encoder. At this |
190 | point we only have \'mppenc\' available, from corecodecs.org. |
191 | .TP |
c9c2ca27 |
192 | .B NORMALIZERSYNTAX |
193 | Specifies the style of normalizer to use. Valid options are \'default\' |
72d7162b |
194 | and \'normalize'\ (and both run \'normalize-audio\'), since we only support it, ATM. |
c9c2ca27 |
195 | .TP |
196 | .B HELLOINFO |
197 | Specifies the Hello information to send to the CDDB server. The CDDB |
198 | protocol requires you to send a valid username and hostname each time you |
199 | connect. The format of this is username@hostname. |
200 | .TP |
201 | .B CDDBLOCALDIR |
202 | Specifies a directory where we store a local CDDB repository. The entries must |
203 | be standard CDDB entries, with the filename being the DISCID value. Other |
204 | CD playing and ripping programs (like Grip) store the entries under ~/.cddb |
205 | and we can make use of those entries. |
206 | .TP |
207 | .B CDDBCOPYLOCAL |
208 | Store local copies of the CDDB entries under the $CDDBLOCALDIR directory. |
209 | .TP |
210 | .B CDDBUSELOCAL |
211 | Actually use the stored copies of the CDDB entries. Can be overriden using the |
212 | "-L" flag (if is CDDBUSELOCAL in "n"). If an entry is found, we always give |
213 | the choice of retrieving a CDDB entry from the internet. |
214 | .TP |
215 | .B OUTPUTDIR |
216 | Specifies the directory to place completed tracks/playlists in. |
217 | .TP |
218 | .B WAVOUTPUTDIR |
219 | Specifies the temporary directory to store .wav files in. Abcde may use up |
220 | to 700MB of temporary space for each session (although it is rare to use |
221 | over 100MB for a machine that can encode music as fast as it can read it). |
222 | .TP |
223 | .B OUTPUTFORMAT |
99d009fa |
224 | Specifies the format for completed Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+ |
225 | (Musepack) filenames. |
c9c2ca27 |
226 | Variables are included |
227 | using standard shell syntax. Allowed variables are GENRE, ALBUMFILE, ARTISTFILE, |
99d009fa |
228 | TRACKFILE, TRACKNUM, and YEAR. Default is |
9f659ada |
229 | \'${ARTISTFILE}-${ALBUMFILE}/${TRACKNUM}-${TRACKFILE}\'. |
c9c2ca27 |
230 | Make sure to use single quotes around this variable. TRACKNUM is |
9f659ada |
231 | automatically zero-padded, when the number of encoded tracks is higher than |
232 | 9. When lower, you can force with '-p' in the command line. |
c9c2ca27 |
233 | .TP |
234 | .B OUTPUTTYPE |
235 | Specifies the encoding format to output, as well as the default extension and |
236 | encoder. Defaults to "ogg". Valid settings are "ogg" (Ogg/Vorbis), "mp3" |
9f659ada |
237 | (MPEG-1 Audio Layer III), "flac" (Free Lossless Audio Codec), "spx" (Ogg/Speex) |
99d009fa |
238 | and "mpc" (MPP/MP+ (Musepack)). Values like "ogg,mp3" encode the tracks in |
239 | both Ogg/Vorbis and MP3 formats. |
c9c2ca27 |
240 | .P |
241 | For each value in OUTPUTTYPE, abcde expands a different process for encoding, |
242 | tagging and moving, so you can use the format placeholder, OUTPUT, to create |
243 | different subdirectories to hold the different types. The variable OUTPUT will |
9f659ada |
244 | be 'ogg', 'mp3', 'flac', 'spx' and/or 'mpc', depending on the OUTPUTTYPE you define. |
c9c2ca27 |
245 | For example |
246 | .P |
247 | OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}' |
248 | .TP |
249 | .B VAOUTPUTFORMAT |
250 | Just like OUTPUTFORMAT but for Various Artists discs. Default is whatever |
251 | OUTPUTFORMAT is set to. |
252 | .TP |
253 | .B PATHNAMES |
254 | The following configuration file options specify the pathnames of their |
255 | respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC, |
9f659ada |
256 | VORBIZE, OGGENC, FLAC, SPEECENC, MPPENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, |
257 | HTTPGET, CDDISCID, CDDBTOOL, EJECT, NORMALIZE, DISTMP3, VORBISCOMMENT, and |
258 | CDSPEED. |
c9c2ca27 |
259 | .TP |
260 | .B COMMAND-LINE OPTIONS |
261 | If you wish to specify command-line options to any of the programs abcde |
262 | uses, set the following configuration file options: LAMEOPTS, GOGOOPTS, |
263 | BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS, |
9f659ada |
264 | OGGENCOPTS, FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, ID3OPTS, ID3V2OPTS, |
265 | CDPARANOIAOPTS, CDDA2WAVOPTS, HTTPGETOPTS, CDDBTOOLOPTS, EJECTOPTS, |
266 | DISTMP3OPTS, NORMALIZEOPTS, CDSPEEDOPTS, and CDSPEEDVALUE. |
c9c2ca27 |
267 | .TP |
268 | .B CDROM |
269 | If set, it points to the CD-Rom device which has to be used for audio |
270 | extraction. Abcde tries to guess the right device, but it may fail. |
271 | .TP |
272 | .B MAXPROCS |
273 | Defines how many encoders to run at once. This makes for huge speedups |
274 | on SMP systems. You should run one encoder per CPU at once for maximum |
275 | efficiency, although more doesn't hurt very much. Set it "0" when using |
276 | mp3dist to avoid getting encoding processes in the local host. |
277 | .TP |
278 | .B LOWDISK |
279 | If set to y, conserves disk space by encoding tracks immediately after |
280 | reading them. This is substantially slower than normal operation but |
281 | requires several hundred MB less space to complete the encoding of an |
282 | entire CD. Use only if your system is low on space and cannot encode as |
283 | quickly as it can read. |
284 | .TP |
285 | .B BATCH |
286 | If set to y, enables batch mode normalization, which preserves relative |
287 | volume differences between tracks of an album. Also enables nogap encoding |
288 | when using the \'lame\' encoder. |
289 | .TP |
290 | .B KEEPWAVS |
291 | It defaults to no, so if you want to keep those wavs ripped from your CD, |
292 | set it to "y". You can use the "-k" switch in the command line. The default |
293 | behaviour with KEEPWAVS set is the keep the temporary directory and the wav |
294 | files even you have requested the "clean" action. |
295 | .TP |
296 | .B PADTRACKS |
297 | If set to "y", it adds 0's to the file numbers to complete a two-number |
298 | holder. Usefull when encoding tracks 1-9. |
299 | .TP |
300 | .B PLAYLISTFORMAT |
301 | Specifies the format for completed playlist filenames. Works like the |
302 | OUTPUTFORMAT configuration variable. Default is |
303 | \'${ARTISTFILE}_\-_${ALBUMFILE}.m3u\'. |
304 | Make sure to use single quotes around this variable. |
305 | .TP |
306 | .B PLAYLISTDATAPREFIX |
307 | Specifies a prefix for filenames within a playlist. Useful for http |
308 | playlists, etc. |
309 | .TP |
99d009fa |
310 | .B DOSPLAYLIST |
311 | If set, the resulting playlist will have CR-LF line endings, needed by some |
312 | hardware-based players. |
313 | .TP |
c9c2ca27 |
314 | .B COMMENT |
315 | Specifies a comment to embed in the ID3 or Ogg comment field of each |
316 | finished track. Can be up to 28 characters long. Supports the same |
317 | syntax as OUTPUTFORMAT. Does not currently support ID3v2. |
318 | .TP |
319 | .B REMOTEHOSTS |
320 | Specifies a comma-delimited list of systems to use for remote encoding using |
321 | distmp3. Equivalent to -r. |
322 | .TP |
323 | .B mungefilename |
324 | mungefilename() is an abcde shell function that can be overridden via |
325 | abcde.conf. It takes CDDB data as $1 and outputs the resulting filename on |
326 | stdout. It defaults to eating control characters, apostrophes and |
327 | question marks, translating spaces and forward slashes to underscores, and |
328 | translating colons to an underscore and a hyphen. |
329 | .br |
330 | If you modify this function, it is probably a good idea to keep the forward |
331 | slash munging (UNIX cannot store a file with a '/' char in it) as well as |
332 | the control character munging (NULs can't be in a filename either, and |
333 | newlines and such in filenames are typically not desirable). |
334 | .TP |
7acef70b |
335 | .B mungegenre |
336 | mungegenre () is a shell function used to modify the $GENRE variable. As |
337 | a default action, it takes $GENRE as $1 and outputs the resulting value |
338 | to stdout converting all UPPERCASE characters to lowercase. |
339 | .TP |
340 | .B pre_read |
341 | pre_read () is a shell function which is executed before the CDROM is read |
342 | for the first time, during abcde execution. It can be used to close the CDROM |
343 | tray, to set its speed (via "setcd" or via "eject", if available) and other |
344 | preparation actions. The default function is empty. |
345 | .TP |
c9c2ca27 |
346 | .B EJECTCD |
347 | If set to "y", abcde will call eject(1) to eject the cdrom from the drive |
348 | after all tracks have been read. |
79e3928b |
349 | .TP |
350 | .B EXTRAVERBOSE |
351 | If set to "y", some operations which are usually now shown to the end user |
352 | are visible, such as CDDB queries. Usefull for initial debug and if your |
353 | network/CDDB server is slow. |
c9c2ca27 |
354 | .SH BACKEND TOOLS |
355 | abcde requires the following backend tools to work: |
356 | .TP |
357 | .B * |
99d009fa |
358 | An Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+(Musepack) encoder (oggenc, vorbize, lame, gogo, bladeenc, l3enc, mp3enc, flac, speexenc, mppenc) |
c9c2ca27 |
359 | .TP |
360 | .B * |
361 | An audio CD reading utility (cdparanoia, cdda2wav, dagrab) |
362 | .TP |
363 | .B * |
364 | cd-discid, a CDDB DiscID reading program. |
365 | .TP |
366 | .B * |
367 | An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, among others). |
368 | .TP |
369 | .B * |
370 | (for MP3s) id3 or id3v2, id3 v1 and v2 tagging programs. |
371 | .TP |
372 | .B * |
373 | (optional) distmp3, a client/server for distributed mp3 encoding. |
374 | .TP |
375 | .B * |
376 | (optional) normalize, a WAV file volume normalizer. |
377 | .SH "SEE ALSO" |
378 | .BR cdparanoia (1), |
379 | .BR cdda2wav (1), |
380 | .BR dagrab (1), |
72d7162b |
381 | .BR normalize-audio (1), |
c9c2ca27 |
382 | .BR oggenc (1), |
383 | .BR vorbize (1), |
384 | .BR flac (1), |
385 | .BR speexenc(1), |
99d009fa |
386 | .BR mppenc(1), |
c9c2ca27 |
387 | .BR id3 (1), |
388 | .BR wget (1), |
389 | .BR fetch (1), |
390 | .BR cd-discid (1), |
391 | .BR distmp3 (1), |
392 | .BR distmp3host (1), |
393 | .BR curl(1) |
9f659ada |
394 | .SH AUTHORS |
b7f1cc84 |
395 | Robert Woodcock <rcw@debian.org>, |
396 | Jesus Climent <jesus.climent@hispalinux.es> and contributions from many others. |