Commit | Line | Data |
---|---|---|
79c8f4d0 | 1 | .TH abcde 1 |
c9c2ca27 | 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 | |
d100b6be | 13 | Audio Codec (FLAC), Ogg/Speex, MPP/MP+(Musepack) and/or M4A (AAC) format(s). |
14 | With one command, it will: | |
c9c2ca27 | 15 | .TP |
16 | .B * | |
e901a1b9 | 17 | Do a CDDB or Musicbrainz query over the Internet to look up your CD or use a locally stored CDDB entry |
c9c2ca27 | 18 | .TP |
19 | .B * | |
6fba8f12 | 20 | Grab an audio track (or all the audio CD tracks) from your CD |
c9c2ca27 | 21 | .TP |
22 | .B * | |
6fba8f12 | 23 | Normalize the volume of the individual file (or the album as a single unit) |
c9c2ca27 | 24 | .TP |
25 | .B * | |
fa421b8b | 26 | Compress to Ogg/Vorbis, MP3, FLAC, Ogg/Speex, MPP/MP+(Musepack) and/or M4A format(s), all in one CD read |
c9c2ca27 | 27 | .TP |
28 | .B * | |
6fba8f12 | 29 | Comment or ID3/ID3v2 tag |
30 | .TP | |
31 | .B * | |
32 | Give an intelligible filename | |
33 | .TP | |
34 | .B * | |
35 | Calculate replaygain values for the individual file (or the album as a single unit) | |
c9c2ca27 | 36 | .TP |
37 | .B * | |
38 | Delete the intermediate WAV file (or save it for later use) | |
39 | .TP | |
40 | .B * | |
41 | Repeat until finished | |
ffd57cfc | 42 | .P |
43 | Alternatively, | |
44 | .B abcde | |
45 | can also grab a CD and turn it into a single FLAC file with an embedded | |
46 | cuesheet which can be user later on as a source for other formats, and will be | |
47 | treated as if it was the original CD. In a way, | |
48 | .B abcde | |
49 | can take a compressed backup of your CD collection. | |
c9c2ca27 | 50 | .SH OPTIONS |
51 | .TP | |
52 | .B \-1 | |
53 | Encode the whole CD in a single file. The resulting file uses the CD title | |
8f9c0102 | 54 | for tagging. If the resulting format is a flac file with an embedded cuesheet, |
9c3756dc | 55 | the file can be used as a source for creating other formats. Use "\-1 \-o |
56 | flac \-a default,cue" for obtaining such a file. | |
d68ebfff | 57 | .TP |
c9c2ca27 | 58 | .B \-a [actions] |
f7c6d185 | 59 | Comma-delimited list of actions to perform. Can be one or more of: cddb, cue, |
60 | read, normalize, encode, tag, move, replaygain, playlist, clean. Normalize and | |
61 | encode imply read. Tag implies cddb, read, encode. Move implies cddb, read, | |
62 | encode, tag. Replaygain implies cddb, read, encode, tag and move. Playlist | |
93a69eff | 63 | implies cddb. The default is to do all actions except cue, normalize, |
64 | replaygain and playlist. | |
c9c2ca27 | 65 | .TP |
66 | .B \-b | |
0709e644 | 67 | Enable batch mode normalization. See the BATCHNORM configuration variable. |
c9c2ca27 | 68 | .TP |
6fba8f12 | 69 | .B \-B |
70 | Disable batch mode replaygain. It processes file by file to add the replaygain | |
89d883d6 | 71 | information. See the NOBATCHREPLAYGAIN configuration variable. |
6fba8f12 | 72 | .TP |
c9c2ca27 | 73 | .B \-c [filename] |
74 | Specifies an additional configuration file to parse. Configuration options | |
e901a1b9 | 75 | in this file override those in \fI/etc/abcde.conf\fR or \fI$HOME/.abcde.conf\fR. |
c9c2ca27 | 76 | .TP |
77 | .B \-C [discid] | |
78 | Allows you to resume a session for | |
79 | .I discid | |
e901a1b9 | 80 | when you no longer have the CD available (\fBabcde\fR will automatically resume if |
c9c2ca27 | 81 | you still have the CD in the drive). You must have already finished at |
82 | least the "read" action during the previous session. | |
83 | .TP | |
1b94d6b7 | 84 | .B \-d [devicename | filename] |
85 | CD\-ROM block device that contains audio tracks to be read. Alternatively, a | |
8f9c0102 | 86 | single-track flac file with embedded cuesheet. |
c9c2ca27 | 87 | .TP |
88 | .B \-D | |
89 | Capture debugging information (you'll want to redirect this \- try 'abcde \-D | |
90 | 2>logfile') | |
91 | .TP | |
0709e644 | 92 | .B \-e |
93 | Erase information about encoded tracks from the internal status file, to enable | |
94 | other encodings if the wav files have been kept. | |
95 | .TP | |
fa421b8b | 96 | .B \-f |
97 | Force the removal of the temporary ABCDETEMPDIR directory, even when we have | |
98 | not finished. For example, one can read and encode several formats, including | |
99 | \'.ogg\', and later on execute a \'move\' action with only one of the given | |
100 | formats. On a normal situation it would erase the rest of those encoded | |
e901a1b9 | 101 | formats. In this case, \fBabcde\fR will refuse to execute such command, except if \-f |
fa421b8b | 102 | is used. |
103 | .TP | |
0709e644 | 104 | .B \-g |
105 | Enable lame's \-\-nogap option. See the NOGAP variable. WARNING: lame's | |
106 | \-\-nogap disables the Xing mp3 tag. This tag is required for mp3 players to | |
107 | correctly display track lengths when playing variable-bit-rate mp3 files. | |
108 | .TP | |
81bc6204 | 109 | .B \-h |
110 | Get help information. | |
04609998 | 111 | .TP |
c9c2ca27 | 112 | .B \-j [number] |
113 | Start [number] encoder processes at once. Useful for SMP systems. Overrides | |
e901a1b9 | 114 | the MAXPROCS configuration variable. Set it to "0" when using \fBdistmp3\fR to avoid |
c9c2ca27 | 115 | local encoding processes. |
116 | .TP | |
117 | .B \-k | |
118 | Keep the wav files after encoding. | |
119 | .TP | |
120 | .B \-l | |
121 | Use the low-diskspace algorithm. See the LOWDISK configuration variable. | |
122 | .TP | |
123 | .B \-L | |
124 | Use a local CDDB repository. See CDDBLOCALDIR variable. | |
125 | .TP | |
aabd3397 E |
126 | .B \-m |
127 | Create DOS-style playlists, modifying the resulting one by adding CRLF line | |
128 | endings. Some hardware players insist on having those to work. | |
129 | .TP | |
81bc6204 | 130 | .B \-n |
c9c2ca27 | 131 | Do not query CDDB database. Create and use a template. Edit the template to |
132 | provide song names, artist(s), ... | |
133 | .TP | |
81bc6204 | 134 | .B \-N |
c9c2ca27 | 135 | Non interactive mode. Do not ask anything from the user. Just go ahead. |
136 | .TP | |
24f444d7 | 137 | .B \-o [filetype][:filetypeoptions] |
fa421b8b | 138 | Select output type. Can be "vorbis" (or "ogg"), "mp3", "flac", "spx", "mpc", |
139 | "m4a" or "wav". Specify a comma-delimited list of output types to obtain all | |
140 | specified types. See the OUTPUTTYPE configuration variable. One can pass | |
141 | options to the encoder for a specific filetype on the command line separating | |
142 | them with a colon. The options must be escaped with double-quotes. | |
c9c2ca27 | 143 | .TP |
144 | .B \-p | |
145 | Pads track numbers with 0\'s. | |
146 | .TP | |
fa421b8b | 147 | .B \-P |
148 | Use Unix PIPES to read and encode in one step. It disables multiple encodings, | |
149 | since the WAV audio file is never stored in the disc. | |
150 | .TP | |
93a69eff | 151 | .B \-q [quality] |
152 | Use a pre-defined quality level for the encoding process. Defined as low, | |
153 | medium or high. The "medium" value is used to reset the default values if other | |
154 | are used in the config file(s). | |
155 | .TP | |
c9c2ca27 | 156 | .B \-r [hosts...] |
e901a1b9 | 157 | Remote encode on this comma-delimited list of machines using \fBdistmp3\fR. See |
c9c2ca27 | 158 | the REMOTEHOSTS configuration variable. |
159 | .TP | |
411ef0b0 | 160 | .B \-s [fields...] |
8f4189b3 | 161 | List, separated by commas, the fields to be shown in the CDDB parsed entries. |
411ef0b0 | 162 | Right now it only uses "year" and "genre". |
163 | .TP | |
c9c2ca27 | 164 | .B \-S [speed] |
165 | Set the speed of the CD drive. Needs CDSPEED and CDSPEEDOPTS set properly | |
166 | and both the program and device must support the capability. | |
167 | .TP | |
79e3928b | 168 | .B \-t [number] |
169 | Start the numbering of the tracks at a given number. It only affects the | |
170 | filenames and the playlist. Internal (tag) numbering remains the same. | |
171 | .TP | |
172 | .B \-T [number] | |
173 | Same as \-t but changes also the internal (tag) numbering. Keep in mind that | |
174 | the default TRACK tag for MP3 is $T/$TRACKS so it is changed to simply $T. | |
175 | .TP | |
f7c6d185 | 176 | .B \-U |
177 | Set CDDBPROTO to version 5, so that we retrieve ISO-8859-15 encoded CDDB | |
178 | information, and we tag and add comments with Latin1 encoding. | |
cdbd4cc8 | 179 | .TP |
c9c2ca27 | 180 | .B \-v |
181 | Show the version and exit | |
182 | .TP | |
183 | .B \-V | |
7172fbaf E |
184 | Be more verbose. On slow networks the CDDB requests might give the |
185 | sensation nothing is happening. Add this more than once to make things | |
186 | even more verbose. | |
c9c2ca27 | 187 | .TP |
188 | .B \-x | |
189 | Eject the CD when all tracks have been read. See the EJECTCD configuration | |
190 | variable. | |
191 | .TP | |
ffd57cfc | 192 | .B \-X [cue2discid] |
193 | Use an alternative "cue2discid" implementation. The name of the binary must be | |
e901a1b9 | 194 | exactly that. \fBabcde\fR comes with an implementation in python under the examples |
ffd57cfc | 195 | directory. The special keyword "builtin" forces the usage of the internal |
196 | (default) implementation in shell script. | |
197 | .TP | |
81bc6204 | 198 | .B \-w [comment] |
199 | Add a comment to the tracks ripped from the CD. | |
200 | .TP | |
201 | .B \-W [number] | |
202 | Concatenate CD\'s. It uses the number provided to define a comment "CD #" and | |
101e0368 | 203 | to modify the numbering of the tracks, starting with "#01". For Ogg/Vorbis and |
204 | FLAC files, it also defines a DISCNUMBER tag. | |
c9c2ca27 | 205 | .TP |
fd37d8dd | 206 | .B \-z |
e901a1b9 | 207 | DEBUG mode: it will rip, using \fBcdparanoia\fR, the very first second of each track |
fd37d8dd | 208 | and proceed with the actions requested very quickly, also providing some |
209 | "hidden" information about what happens on the background. CAUTION: IT WILL | |
210 | ERASE ANY EXISTING RIPS WITHOUT WARNING! | |
211 | .TP | |
c9c2ca27 | 212 | .B [tracks] |
e901a1b9 | 213 | A list of tracks you want \fBabcde\fR to process. If this isn't specified, \fBabcde\fR |
c9c2ca27 | 214 | will process the entire CD. Accepts ranges of track numbers - |
215 | "abcde 1-5 7 9" will process tracks 1, 2, 3, 4, 5, 7, and 9. | |
216 | .SH OUTPUT | |
217 | Each track is, by default, placed in a separate file named after the track | |
9f659ada | 218 | in a subdirectory named after the artist under the current directory. |
c9c2ca27 | 219 | This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT |
e901a1b9 | 220 | variables in your \fIabcde.conf\fR. Each file is given an extension identifying |
fa421b8b | 221 | its compression format, 'vorbis' for '.ogg', '.mp3', '.flac', '.spx', '.mpc', '.aac' or '.wav'. |
c9c2ca27 | 222 | .SH CONFIGURATION |
e901a1b9 E |
223 | \fBabcde\fR sources two configuration files on startup - \fI/etc/abcde.conf\fR and |
224 | \fI$HOME/.abcde.conf\fR, in that order. | |
225 | .PP | |
226 | The configuration options stated in those files can be overridden by providing | |
8f9c0102 | 227 | the appropriate flags at runtime. |
e901a1b9 | 228 | .PP |
c9c2ca27 | 229 | The configuration variables have to be set as follows: |
230 | .TP | |
231 | .B VARIABLE=value | |
c9c2ca27 | 232 | Except when "value" needs to be quoted or otherwise interpreted. If other |
233 | variables within "value" are to be expanded upon reading the configuration | |
234 | file, then double quotes should be used. If they are only supposed to be | |
235 | expanded upon use (for example OUTPUTFORMAT) then single quotes must be used. | |
236 | .TP | |
e901a1b9 | 237 | All shell escaping/quoting rules apply. |
c9c2ca27 | 238 | .TP |
e901a1b9 | 239 | Here is a list of options \fBabcde\fR recognizes: |
c9c2ca27 | 240 | .TP |
fa421b8b | 241 | .B CDDBMETHOD |
242 | Specifies the method we want to use to retrieve the track information. Two | |
243 | values are recognized: "cddb" and "musicbrainz". The "cddb" value needs the | |
244 | CDDBURL and HELLOINFO variables described below. The "musicbrainz" value uses | |
e901a1b9 | 245 | the Perl helper script \fBabcde-musicbrainz-tool\fR to establish a |
2c2dffe6 | 246 | conversation with the Musicbrainz server for information retrieval. |
fa421b8b | 247 | .TP |
c9c2ca27 | 248 | .B CDDBURL |
249 | Specifies a server to use for CDDB lookups. | |
250 | .TP | |
d100b6be | 251 | .B CDDBPROTO |
252 | Specifies the protocol version used for the CDDB retrieval of results. Version | |
253 | 6 retrieves CDDB entries in UTF-8 format. | |
254 | .TP | |
81bc6204 | 255 | .B HELLOINFO |
256 | Specifies the Hello information to send to the CDDB server. The CDDB | |
257 | protocol requires you to send a valid username and hostname each time you | |
258 | connect. The format of this is username@hostname. | |
259 | .TP | |
260 | .B CDDBLOCALDIR | |
261 | Specifies a directory where we store a local CDDB repository. The entries must | |
262 | be standard CDDB entries, with the filename being the DISCID value. Other | |
e901a1b9 | 263 | CD playing and ripping programs (like Grip) store the entries under \fI~/.cddb\fR |
81bc6204 | 264 | and we can make use of those entries. |
265 | .TP | |
f23735e2 | 266 | .B CDDBLOCALRECURSIVE |
267 | Specifies if the CDDBLOCALDIR has to be searched recursively trying to find a | |
268 | match for the CDDB entry. If a match is found and selected, and CDDBCOPYLOCAL | |
269 | is selected, it will be copied to the root of the CDDBLOCALDIR if | |
270 | CDDBLOCALPOLICY is "modified" or "new". | |
271 | .TP | |
272 | .B CDDBLOCALPOLICY | |
273 | Defines when a CDDB entry should be stored in the defined CDDBLOCALDIR. The | |
274 | possible policies are: "net" for a CDDB entry which has been received from the | |
275 | net (overwriting any possible local CDDB entry); "new" for a CDDB entry which | |
276 | was received from the net, but will request confirmation to overwrite a local | |
277 | CDDB entry found in the root of the CDDBLOCALDIR directory; "modified" for a | |
278 | CDDB entry found in the local repository but which has been modified by the | |
279 | user; and "always" which forces the CDDB entry to be stored back in the root of | |
280 | the CDDBLOCALDIR no matter where it was found, and no matter it was not edited. | |
281 | This last option will always overwrite the one found in the root of the local | |
d100b6be | 282 | repository (if any). STILL NOT WORKING!! |
f23735e2 | 283 | .TP |
81bc6204 | 284 | .B CDDBCOPYLOCAL |
285 | Store local copies of the CDDB entries under the $CDDBLOCALDIR directory. | |
286 | .TP | |
287 | .B CDDBUSELOCAL | |
8f9c0102 | 288 | Actually use the stored copies of the CDDB entries. Can be overridden using the |
9c3756dc | 289 | "\-L" flag (if is CDDBUSELOCAL in "n"). If an entry is found, we always give |
81bc6204 | 290 | the choice of retrieving a CDDB entry from the internet. |
291 | .TP | |
9ff5088c | 292 | .B SHOWCDDBFIELDS |
293 | Coma-separated list of fields we want to parse during the CDDB parsing. | |
294 | Defaults to "year,genre". | |
295 | .TP | |
c9c2ca27 | 296 | .B OGGENCODERSYNTAX |
297 | Specifies the style of encoder to use for the Ogg/Vorbis encoder. Valid options | |
298 | are \'oggenc\' (default for Ogg/Vorbis) and \'vorbize\'. | |
299 | This affects the default location of the binary, | |
300 | the variable to pick encoder command-line options from, and where the options | |
301 | are given. | |
302 | .TP | |
303 | .B MP3ENCODERSYNTAX | |
304 | Specifies the style of encoder to use for the MP3 encoder. Valid options are | |
305 | \'lame\' (default for MP3), \'gogo\', \'bladeenc\', \'l3enc\' and \'mp3enc\'. | |
306 | Affects the same way as explained above for Ogg/Vorbis. | |
307 | .TP | |
308 | .B FLACENCODERSYNTAX | |
309 | Specifies the style of encoder to use for the FLAC encoder. At this point only | |
310 | \'flac\' is available for FLAC encoding. | |
311 | .TP | |
312 | .B SPEEXENCODERSYNTAX | |
313 | Specifies the style of encoder to use for Speex encoder. At this point only | |
314 | \'speexenc\' is available for Ogg/Speex encoding. | |
315 | .TP | |
99d009fa | 316 | .B MPPENCODERSYNTAX |
317 | Specifies the style of encoder to use for MPP/MP+ (Musepack) encoder. At this | |
318 | point we only have \'mppenc\' available, from corecodecs.org. | |
319 | .TP | |
fa421b8b | 320 | .B AACENCODERSYNTAX |
321 | Specifies the style of encoder to use for M4A (AAC) encoder. At this point we | |
322 | only support \'faac\', so \'default\' points to it. | |
323 | .TP | |
c9c2ca27 | 324 | .B NORMALIZERSYNTAX |
325 | Specifies the style of normalizer to use. Valid options are \'default\' | |
81bc6204 | 326 | and \'normalize'\ (and both run \'normalize-audio\'), since we only support it, |
327 | ATM. | |
c9c2ca27 | 328 | .TP |
81bc6204 | 329 | .B CDROMREADERSYNTAX |
1b94d6b7 | 330 | Specifies the style of cdrom reader to use. Valid options are \'cdparanoia\', |
331 | \'debug\' and \'flac\'. It is used for querying the CDROM and obtain a list of | |
332 | valid tracks and DATA tracks. The special \'flac\' case is used to "rip" CD | |
333 | tracks from a single-track flac file. | |
c9c2ca27 | 334 | .TP |
f00ed3e7 | 335 | .B CUEREADERSYNTAX |
336 | Specifies the syntax of the program we use to read the CD CUE sheet. Right now | |
337 | we only support \'mkcue\', but in the future other readers might be used. | |
338 | .TP | |
81bc6204 | 339 | .B KEEPWAVS |
340 | It defaults to no, so if you want to keep those wavs ripped from your CD, | |
9c3756dc | 341 | set it to "y". You can use the "\-k" switch in the command line. The default |
6fba8f12 | 342 | behaviour with KEEPWAVS set is to keep the temporary directory and the wav |
81bc6204 | 343 | files even you have requested the "clean" action. |
c9c2ca27 | 344 | .TP |
81bc6204 | 345 | .B PADTRACKS |
346 | If set to "y", it adds 0's to the file numbers to complete a two-number | |
65f3ebb1 | 347 | holder. Useful when encoding tracks 1-9. |
c9c2ca27 | 348 | .TP |
81bc6204 | 349 | .B INTERACTIVE |
350 | Set to "n" if you want to perform automatic rips, without user intervention. | |
351 | .TP | |
352 | .B NICE VALUES | |
353 | Define the values for priorities (nice values) for the different CPU-hungry | |
354 | processes: encoding (ENCNICE), CDROM read (READNICE) and distributed encoder | |
e901a1b9 | 355 | with \fBdistmp3\fR (DISTMP3NICE). |
81bc6204 | 356 | .TP |
357 | .B PATHNAMES | |
358 | The following configuration file options specify the pathnames of their | |
c1bbe6c3 | 359 | respective utilities: LAME, TOOLAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC, |
fa421b8b | 360 | VORBIZE, OGGENC, FLAC, SPEEXENC, MPPENC, AACEND, ID3, ID3V2, EYED3, METAFLAC, |
cb414c1e | 361 | CDPARANOIA, CDDA2WAV, CDDAFS, CDDISCID, CDDBTOOL, EJECT, MD5SUM, DISTMP3, |
362 | VORBISCOMMENT, NORMALIZE, CDSPEED, MP3GAIN, VORBISGAIN, MPPGAIN, MKCUE, MKTOC, | |
ffd57cfc | 363 | CUE2DISCID (see option "\-X"), DIFF and HTTPGET. |
81bc6204 | 364 | .TP |
365 | .B COMMAND-LINE OPTIONS | |
e901a1b9 | 366 | If you wish to specify command-line options to any of the programs \fBabcde\fR uses, |
c1bbe6c3 | 367 | set the following configuration file options: LAMEOPTS, TOOLAMEOPTS, GOGOOPTS, |
81bc6204 | 368 | BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS, OGGENCOPTS, |
b8fa3593 | 369 | FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, AACENCOPTS, ID3OPTS, ID3V2OPTS, MP3GAINOPTS, |
fa421b8b | 370 | CDPARANOIAOPTS, CDDA2WAVOPTS, CDDAFSOPTS, CDDBTOOLOPTS, EJECTOPTS, DISTMP3OPTS, |
371 | NORMALIZEOPTS, CDSPEEDOPTS, MKCUEOPTS, VORBISCOMMMENTOPTS, METAFLACOPTS, | |
b8fa3593 | 372 | DIFFOPTS, FLACGAINOPTS, VORBISGAINOPTS and HTTPGETOPTS. |
81bc6204 | 373 | .TP |
374 | .B CDSPEEDVALUE | |
375 | Set the value of the CDROM speed. The default is to read the disc as fast as | |
376 | the reading program and the system permits. The steps are defined as 150kB/s | |
377 | (1x). | |
378 | .TP | |
379 | .B ACTIONS | |
380 | The default actions to be performed when reading a disc. | |
381 | .TP | |
382 | .B CDROM | |
383 | If set, it points to the CD-Rom device which has to be used for audio | |
1b94d6b7 | 384 | extraction. Abcde tries to guess the right device, but it may fail. The special |
385 | \'flac\' option is defined to extract tracks from a single-track flac file. | |
c9c2ca27 | 386 | .TP |
c008b56d | 387 | .B CDPARANOIACDROMBUS |
e901a1b9 E |
388 | Defined as "d" when using \fBcdparanoia\fR with an IDE bus and as "g" when using |
389 | \fBcdparanoia\fR with the ide-scsi emulation layer. | |
c008b56d | 390 | .TP |
c9c2ca27 | 391 | .B OUTPUTDIR |
392 | Specifies the directory to place completed tracks/playlists in. | |
393 | .TP | |
394 | .B WAVOUTPUTDIR | |
395 | Specifies the temporary directory to store .wav files in. Abcde may use up | |
396 | to 700MB of temporary space for each session (although it is rare to use | |
397 | over 100MB for a machine that can encode music as fast as it can read it). | |
398 | .TP | |
c9c2ca27 | 399 | .B OUTPUTTYPE |
400 | Specifies the encoding format to output, as well as the default extension and | |
b82e2042 | 401 | encoder. Defaults to "vorbis". Valid settings are "vorbis" (or "ogg") |
402 | (Ogg/Vorbis), "mp3" (MPEG-1 Audio Layer III), "flac" (Free Lossless Audio | |
fa421b8b | 403 | Codec), "spx" (Ogg/Speex), "mpc" (MPP/MP+ (Musepack)), "m4a" (for M4A (AAC)) or |
404 | "wav" (Microsoft Waveform). Values like "vorbis,mp3" encode the tracks in both | |
f52719f5 | 405 | Ogg/Vorbis and MP3 formats. For example |
406 | .br | |
407 | OUTPUTTYPE=vorbis,flac | |
81bc6204 | 408 | .br |
e901a1b9 | 409 | For each value in OUTPUTTYPE, \fBabcde\fR expands a different process for encoding, |
c9c2ca27 | 410 | tagging and moving, so you can use the format placeholder, OUTPUT, to create |
411 | different subdirectories to hold the different types. The variable OUTPUT will | |
fa421b8b | 412 | be 'vorbis', 'mp3', 'flac', 'spx', 'mpc', 'm4a' and/or 'wav', depending on the |
413 | OUTPUTTYPE you define. For example | |
81bc6204 | 414 | .br |
c9c2ca27 | 415 | OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}' |
416 | .TP | |
81bc6204 | 417 | .B OUTPUTFORMAT |
fa421b8b | 418 | Specifies the format for completed Ogg/Vorbis, MP3, FLAC, Ogg/Speex, MPP/MP+ |
419 | (Musepack) or M4A filenames. Variables are included using standard shell | |
420 | syntax. Allowed variables are GENRE, ALBUMFILE, ARTISTFILE, TRACKFILE, | |
421 | TRACKNUM, and YEAR. Default is \'${ARTISTFILE}-${ALBUMFILE}/${TRACKNUM}-${TRACKFILE}\'. | |
422 | Make sure to use single quotes around this variable. TRACKNUM is automatically | |
423 | zero-padded, when the number of encoded tracks is higher than 9. When lower, | |
9c3756dc | 424 | you can force with '\-p' in the command line. |
81bc6204 | 425 | .TP |
c9c2ca27 | 426 | .B VAOUTPUTFORMAT |
ffd57cfc | 427 | Just like OUTPUTFORMAT but for Various Artists discs. The default is 'Various-${ALBUMFILE}/${TRACKNUM}.${ARTISTFILE}-${TRACKFILE}' |
428 | .TP | |
429 | .B ONETRACKOUTPUTFORMAT | |
430 | Just like OUTPUTFORMAT but for single-track rips (see option "\-1"). The default is '${ARTISTFILE}-${ALBUMFILE}/${ALBUMFILE}' | |
431 | .TP | |
432 | .B VAONETRACKOUTPUTFORMAT | |
433 | Just like ONETRACKOUTPUTFORMAT but for Various Artists discs. The default is 'Various-${ALBUMFILE}/${ALBUMFILE}' | |
c9c2ca27 | 434 | .TP |
c9c2ca27 | 435 | .B MAXPROCS |
436 | Defines how many encoders to run at once. This makes for huge speedups | |
437 | on SMP systems. You should run one encoder per CPU at once for maximum | |
438 | efficiency, although more doesn't hurt very much. Set it "0" when using | |
439 | mp3dist to avoid getting encoding processes in the local host. | |
440 | .TP | |
441 | .B LOWDISK | |
442 | If set to y, conserves disk space by encoding tracks immediately after | |
443 | reading them. This is substantially slower than normal operation but | |
444 | requires several hundred MB less space to complete the encoding of an | |
445 | entire CD. Use only if your system is low on space and cannot encode as | |
446 | quickly as it can read. | |
b470d3eb | 447 | |
448 | Note that this option may also help when reading | |
449 | a CD with errors. This is because on a scratchy disk reading is quite timing | |
450 | sensitive and this option reduces the background load on the system which | |
451 | allows the ripping program more precise control. | |
c9c2ca27 | 452 | .TP |
0709e644 | 453 | .B BATCHNORM |
c9c2ca27 | 454 | If set to y, enables batch mode normalization, which preserves relative |
455 | volume differences between tracks of an album. Also enables nogap encoding | |
456 | when using the \'lame\' encoder. | |
457 | .TP | |
0709e644 | 458 | .B NOGAP |
459 | Activate the lame's \-\-nogap option, that allows files found in CDs with no | |
460 | silence between songs (such as live concerts) to be encoded without noticeable | |
461 | gaps. WARNING: lame's \-\-nogap disables the Xing mp3 tag. This tag is | |
462 | required for mp3 players to correctly display track lengths when playing | |
463 | variable-bit-rate mp3 files. | |
464 | .TP | |
c9c2ca27 | 465 | .B PLAYLISTFORMAT |
466 | Specifies the format for completed playlist filenames. Works like the | |
467 | OUTPUTFORMAT configuration variable. Default is | |
468 | \'${ARTISTFILE}_\-_${ALBUMFILE}.m3u\'. | |
469 | Make sure to use single quotes around this variable. | |
470 | .TP | |
471 | .B PLAYLISTDATAPREFIX | |
472 | Specifies a prefix for filenames within a playlist. Useful for http | |
473 | playlists, etc. | |
474 | .TP | |
99d009fa | 475 | .B DOSPLAYLIST |
476 | If set, the resulting playlist will have CR-LF line endings, needed by some | |
477 | hardware-based players. | |
478 | .TP | |
c9c2ca27 | 479 | .B COMMENT |
480 | Specifies a comment to embed in the ID3 or Ogg comment field of each | |
481 | finished track. Can be up to 28 characters long. Supports the same | |
482 | syntax as OUTPUTFORMAT. Does not currently support ID3v2. | |
483 | .TP | |
484 | .B REMOTEHOSTS | |
485 | Specifies a comma-delimited list of systems to use for remote encoding using | |
e901a1b9 | 486 | \fBdistmp3\fR. Equivalent to \-r. |
c9c2ca27 | 487 | .TP |
488 | .B mungefilename | |
e901a1b9 E |
489 | mungefilename() is an \fBabcde\fR shell function that can be overridden via |
490 | \fIabcde.conf\fR. It takes CDDB data as $1 and outputs the resulting filename on | |
c9c2ca27 | 491 | stdout. It defaults to eating control characters, apostrophes and |
492 | question marks, translating spaces and forward slashes to underscores, and | |
493 | translating colons to an underscore and a hyphen. | |
494 | .br | |
495 | If you modify this function, it is probably a good idea to keep the forward | |
496 | slash munging (UNIX cannot store a file with a '/' char in it) as well as | |
497 | the control character munging (NULs can't be in a filename either, and | |
498 | newlines and such in filenames are typically not desirable). | |
499 | .TP | |
7acef70b | 500 | .B mungegenre |
501 | mungegenre () is a shell function used to modify the $GENRE variable. As | |
502 | a default action, it takes $GENRE as $1 and outputs the resulting value | |
503 | to stdout converting all UPPERCASE characters to lowercase. | |
504 | .TP | |
505 | .B pre_read | |
506 | pre_read () is a shell function which is executed before the CDROM is read | |
e901a1b9 | 507 | for the first time, during \fBabcde\fR execution. It can be used to close the CDROM |
7acef70b | 508 | tray, to set its speed (via "setcd" or via "eject", if available) and other |
509 | preparation actions. The default function is empty. | |
510 | .TP | |
9ff5088c | 511 | .B post_read |
512 | post_read () is a shell function which is executed after the CDROM is read | |
513 | (and, if applies, before the CDROM is ejected). It can be used to read a TOC | |
514 | from the CDROM, or to try to read the DATA areas from the CD (if any exist). | |
515 | The default function is empty. | |
516 | .TP | |
c9c2ca27 | 517 | .B EJECTCD |
e901a1b9 | 518 | If set to "y", \fBabcde\fR will call \fBeject\fR(1) to eject the cdrom from the drive |
1b94d6b7 | 519 | after all tracks have been read. It has no effect when CDROM is set to a flac |
520 | file. | |
79e3928b | 521 | .TP |
522 | .B EXTRAVERBOSE | |
7172fbaf | 523 | If set to "1", some operations which are usually now shown to the end user |
65f3ebb1 | 524 | are visible, such as CDDB queries. Useful for initial debug and if your |
7172fbaf E |
525 | network/CDDB server is slow. Set to "2" or more for even more verbose |
526 | output. | |
24f444d7 | 527 | .SH EXAMPLES |
e901a1b9 | 528 | Possible ways one can call \fBabcde\fR: |
24f444d7 | 529 | .TP |
530 | .B abcde | |
531 | Will work in most systems | |
532 | .TP | |
0709e644 | 533 | .B abcde \-d /dev/cdrom2 |
e901a1b9 | 534 | If the CDROM you are reading from is not the standard \fI/dev/cdrom\fR (in GNU/Linux systems) |
24f444d7 | 535 | .TP |
0709e644 | 536 | .B abcde \-o vorbis,flac |
24f444d7 | 537 | Will create both Ogg/Vorbis and Ogg/FLAC files. |
538 | .TP | |
0709e644 | 539 | .B abcde \-o vorbis:"-b 192" |
9c3756dc | 540 | Will pass "\-b 192" to the Ogg/Vorbis encoder, without having to modify the |
24f444d7 | 541 | config file |
542 | .TP | |
0709e644 | 543 | .B abcde \-W 1 |
1b94d6b7 | 544 | For double+ CD settings: will create the 1st CD starting with the track number |
545 | 101, and will add a comment "CD 1" to the tracks, the second starting with 201 | |
546 | and so on. | |
547 | .TP | |
548 | .B abcde \-d singletrack.flac | |
8f9c0102 | 549 | Will extract the files contained in singletrack using the embedded cuesheet. |
c9c2ca27 | 550 | .SH BACKEND TOOLS |
e901a1b9 | 551 | \fBabcde\fR requires the following backend tools to work: |
c9c2ca27 | 552 | .TP |
553 | .B * | |
fa421b8b | 554 | An Ogg/Vorbis, MP3, FLAC, Ogg/Speex, MPP/MP+(Musepack) or M4A encoder (oggenc, vorbize, lame, gogo, bladeenc, l3enc, mp3enc, flac, speexenc, mppenc, faac) |
c9c2ca27 | 555 | .TP |
556 | .B * | |
6b005b85 | 557 | An audio CD reading utility (cdparanoia, icedax, cdda2wav, dagrab) |
c9c2ca27 | 558 | .TP |
559 | .B * | |
560 | cd-discid, a CDDB DiscID reading program. | |
561 | .TP | |
562 | .B * | |
e901a1b9 E |
563 | An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, |
564 | among others). Alternatively, abcde-musicbrainz-tool (which depends on | |
565 | Perl and some Musicbrainz libraries) can be used to retrieve CDDB | |
566 | information about the CD. | |
c9c2ca27 | 567 | .TP |
568 | .B * | |
569 | (for MP3s) id3 or id3v2, id3 v1 and v2 tagging programs. | |
570 | .TP | |
571 | .B * | |
572 | (optional) distmp3, a client/server for distributed mp3 encoding. | |
573 | .TP | |
574 | .B * | |
6fba8f12 | 575 | (optional) normalize-audio, a WAV file volume normalizer. |
576 | .TP | |
577 | .B * | |
fa421b8b | 578 | (optional) a replaygain file volume modifier (vorbisgain, metaflac, mp3gain, replaygain), |
1b94d6b7 | 579 | .TP |
580 | .B * | |
581 | (optional) mkcue, a CD cuesheet extractor. | |
c9c2ca27 | 582 | .SH "SEE ALSO" |
583 | .BR cdparanoia (1), | |
6b005b85 | 584 | .BR icedax (1), |
c9c2ca27 | 585 | .BR cdda2wav (1), |
586 | .BR dagrab (1), | |
72d7162b | 587 | .BR normalize-audio (1), |
c9c2ca27 | 588 | .BR oggenc (1), |
589 | .BR vorbize (1), | |
590 | .BR flac (1), | |
6fba8f12 | 591 | .BR toolame (1), |
1b94d6b7 | 592 | .BR speexenc (1), |
593 | .BR mppenc (1), | |
fa421b8b | 594 | .BR faac (1), |
c9c2ca27 | 595 | .BR id3 (1), |
6fba8f12 | 596 | .BR id3v2 (1), |
c9c2ca27 | 597 | .BR wget (1), |
598 | .BR fetch (1), | |
599 | .BR cd-discid (1), | |
600 | .BR distmp3 (1), | |
601 | .BR distmp3host (1), | |
6fba8f12 | 602 | .BR curl (1), |
1b94d6b7 | 603 | .BR mkcue (1), |
6fba8f12 | 604 | .BR vorbisgain (1), |
605 | .BR mp3gain (1) | |
9f659ada | 606 | .SH AUTHORS |
b7f1cc84 | 607 | Robert Woodcock <rcw@debian.org>, |
e901a1b9 E |
608 | Jesus Climent <jesus.climent@hispalinux.es>, |
609 | Colin Tuckley <colint@debian.org>, | |
610 | Steve McIntyre <93sam@debian.org> and contributions from many others. |