| 1 | .TH abcde 1 |
| 2 | .SH NAME |
| 3 | abcde \- Grab an entire CD and compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format. |
| 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 |
| 13 | Audio Codec (FLAC), Ogg/Speex or MPP/MP+(Musepack). With one command, it will: |
| 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 * |
| 22 | Compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format |
| 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 |
| 69 | .B \-h |
| 70 | Get help information. |
| 71 | .TP |
| 72 | .B \-j [number] |
| 73 | Start [number] encoder processes at once. Useful for SMP systems. Overrides |
| 74 | the MAXPROCS configuration variable. Set it to "0" when using distmp3 to avoid |
| 75 | local encoding processes. |
| 76 | .TP |
| 77 | .B \-k |
| 78 | Keep the wav files after encoding. |
| 79 | .TP |
| 80 | .B \-l |
| 81 | Use the low-diskspace algorithm. See the LOWDISK configuration variable. |
| 82 | .TP |
| 83 | .B \-L |
| 84 | Use a local CDDB repository. See CDDBLOCALDIR variable. |
| 85 | .TP |
| 86 | .B \-n |
| 87 | Do not query CDDB database. Create and use a template. Edit the template to |
| 88 | provide song names, artist(s), ... |
| 89 | .TP |
| 90 | .B \-N |
| 91 | Non interactive mode. Do not ask anything from the user. Just go ahead. |
| 92 | .TP |
| 93 | .B \-m |
| 94 | Create DOS-style playlists, modifying the resulting one by adding CRLF line |
| 95 | endings. Some hardware players insist on having those to work. |
| 96 | .TP |
| 97 | .B \-M |
| 98 | Create a CUE file with information about the CD. Together with the possibility |
| 99 | of creating a single file (see option "\-1"), one can recreate the original CD. |
| 100 | .TP |
| 101 | .B \-o [filetype][:filetypeoptions] |
| 102 | Select output type. Can be "vorbis" (or "ogg"), "mp3", "flac", "spx" or "mpc". |
| 103 | Specify a comma-delimited list of output types to obtain all specified types. |
| 104 | See the OUTPUTTYPE configuration variable. One can pass options to the encoder |
| 105 | for a specific filetype on the command line separating them with a colon. The |
| 106 | options must be escaped with double-quotes. |
| 107 | .TP |
| 108 | .B \-p |
| 109 | Pads track numbers with 0\'s. |
| 110 | .TP |
| 111 | .B \-r [hosts...] |
| 112 | Remote encode on this comma-delimited list of machines using distmp3. See |
| 113 | the REMOTEHOSTS configuration variable. |
| 114 | .TP |
| 115 | .B \-R |
| 116 | Add replaygain information to the id3 or tag information for play |
| 117 | normalization. Only works with MP3 and Ogg/Vorbis. |
| 118 | .TP |
| 119 | .B \-S [speed] |
| 120 | Set the speed of the CD drive. Needs CDSPEED and CDSPEEDOPTS set properly |
| 121 | and both the program and device must support the capability. |
| 122 | .TP |
| 123 | .B \-t [number] |
| 124 | Start the numbering of the tracks at a given number. It only affects the |
| 125 | filenames and the playlist. Internal (tag) numbering remains the same. |
| 126 | .TP |
| 127 | .B \-T [number] |
| 128 | Same as \-t but changes also the internal (tag) numbering. Keep in mind that |
| 129 | the default TRACK tag for MP3 is $T/$TRACKS so it is changed to simply $T. |
| 130 | .TP |
| 131 | .B \-v |
| 132 | Show the version and exit |
| 133 | .TP |
| 134 | .B \-V |
| 135 | Be a bit more verbose. On slow networks the CDDB requests might give the |
| 136 | sensation nothins is happening. |
| 137 | .TP |
| 138 | .B \-x |
| 139 | Eject the CD when all tracks have been read. See the EJECTCD configuration |
| 140 | variable. |
| 141 | .TP |
| 142 | .B \-w [comment] |
| 143 | Add a comment to the tracks ripped from the CD. |
| 144 | .TP |
| 145 | .B \-W [number] |
| 146 | Concatenate CD\'s. It uses the number provided to define a comment "CD #" and |
| 147 | to modify the numbering of the tracks, starting with "#01". |
| 148 | .TP |
| 149 | .B [tracks] |
| 150 | A list of tracks you want abcde to process. If this isn't specified, abcde |
| 151 | will process the entire CD. Accepts ranges of track numbers - |
| 152 | "abcde 1-5 7 9" will process tracks 1, 2, 3, 4, 5, 7, and 9. |
| 153 | .SH OUTPUT |
| 154 | Each track is, by default, placed in a separate file named after the track |
| 155 | in a subdirectory named after the artist under the current directory. |
| 156 | This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT |
| 157 | variables in your abcde.conf. Each file is given an extension identifying |
| 158 | its compression format, 'vorbis' for '.ogg', '.mp3', '.flac', '.spx', or '.mpc'. |
| 159 | .SH CONFIGURATION |
| 160 | abcde sources two configuration files on startup - /etc/abcde.conf and |
| 161 | $HOME/.abcde.conf, in that order. |
| 162 | .TP |
| 163 | The configuration options stated on those files can ba overriden by providing |
| 164 | the appropiate flags at runtime. |
| 165 | .TP |
| 166 | The configuration variables have to be set as follows: |
| 167 | .TP |
| 168 | .B VARIABLE=value |
| 169 | Except when "value" needs to be quoted or otherwise interpreted. If other |
| 170 | variables within "value" are to be expanded upon reading the configuration |
| 171 | file, then double quotes should be used. If they are only supposed to be |
| 172 | expanded upon use (for example OUTPUTFORMAT) then single quotes must be used. |
| 173 | .TP |
| 174 | All sh escaping/quoting rules apply. |
| 175 | .TP |
| 176 | Here is a list of options abcde recognizes: |
| 177 | .TP |
| 178 | .B CDDBURL |
| 179 | Specifies a server to use for CDDB lookups. |
| 180 | .TP |
| 181 | .B HELLOINFO |
| 182 | Specifies the Hello information to send to the CDDB server. The CDDB |
| 183 | protocol requires you to send a valid username and hostname each time you |
| 184 | connect. The format of this is username@hostname. |
| 185 | .TP |
| 186 | .B CDDBLOCALDIR |
| 187 | Specifies a directory where we store a local CDDB repository. The entries must |
| 188 | be standard CDDB entries, with the filename being the DISCID value. Other |
| 189 | CD playing and ripping programs (like Grip) store the entries under ~/.cddb |
| 190 | and we can make use of those entries. |
| 191 | .TP |
| 192 | .B CDDBCOPYLOCAL |
| 193 | Store local copies of the CDDB entries under the $CDDBLOCALDIR directory. |
| 194 | .TP |
| 195 | .B CDDBUSELOCAL |
| 196 | Actually use the stored copies of the CDDB entries. Can be overriden using the |
| 197 | "-L" flag (if is CDDBUSELOCAL in "n"). If an entry is found, we always give |
| 198 | the choice of retrieving a CDDB entry from the internet. |
| 199 | .TP |
| 200 | .B SHOWCDDBFIELDS |
| 201 | Coma-separated list of fields we want to parse during the CDDB parsing. |
| 202 | Defaults to "year,genre". |
| 203 | .TP |
| 204 | .B OGGENCODERSYNTAX |
| 205 | Specifies the style of encoder to use for the Ogg/Vorbis encoder. Valid options |
| 206 | are \'oggenc\' (default for Ogg/Vorbis) and \'vorbize\'. |
| 207 | This affects the default location of the binary, |
| 208 | the variable to pick encoder command-line options from, and where the options |
| 209 | are given. |
| 210 | .TP |
| 211 | .B MP3ENCODERSYNTAX |
| 212 | Specifies the style of encoder to use for the MP3 encoder. Valid options are |
| 213 | \'lame\' (default for MP3), \'gogo\', \'bladeenc\', \'l3enc\' and \'mp3enc\'. |
| 214 | Affects the same way as explained above for Ogg/Vorbis. |
| 215 | .TP |
| 216 | .B FLACENCODERSYNTAX |
| 217 | Specifies the style of encoder to use for the FLAC encoder. At this point only |
| 218 | \'flac\' is available for FLAC encoding. |
| 219 | .TP |
| 220 | .B SPEEXENCODERSYNTAX |
| 221 | Specifies the style of encoder to use for Speex encoder. At this point only |
| 222 | \'speexenc\' is available for Ogg/Speex encoding. |
| 223 | .TP |
| 224 | .B MPPENCODERSYNTAX |
| 225 | Specifies the style of encoder to use for MPP/MP+ (Musepack) encoder. At this |
| 226 | point we only have \'mppenc\' available, from corecodecs.org. |
| 227 | .TP |
| 228 | .B NORMALIZERSYNTAX |
| 229 | Specifies the style of normalizer to use. Valid options are \'default\' |
| 230 | and \'normalize'\ (and both run \'normalize-audio\'), since we only support it, |
| 231 | ATM. |
| 232 | .TP |
| 233 | .B CDROMREADERSYNTAX |
| 234 | Specifies the style of cdrom reader to use. Valid options are \'cdparanoia\' |
| 235 | and \'debug\'. It is used for querying the CDROM and obtain a list of valid |
| 236 | tracks and DATA tracks. Right now, only cdparanoia is supported. |
| 237 | .TP |
| 238 | .B KEEPWAVS |
| 239 | It defaults to no, so if you want to keep those wavs ripped from your CD, |
| 240 | set it to "y". You can use the "-k" switch in the command line. The default |
| 241 | behaviour with KEEPWAVS set is the keep the temporary directory and the wav |
| 242 | files even you have requested the "clean" action. |
| 243 | .TP |
| 244 | .B PADTRACKS |
| 245 | If set to "y", it adds 0's to the file numbers to complete a two-number |
| 246 | holder. Useful when encoding tracks 1-9. |
| 247 | .TP |
| 248 | .B INTERACTIVE |
| 249 | Set to "n" if you want to perform automatic rips, without user intervention. |
| 250 | .TP |
| 251 | .B NICE VALUES |
| 252 | Define the values for priorities (nice values) for the different CPU-hungry |
| 253 | processes: encoding (ENCNICE), CDROM read (READNICE) and distributed encoder |
| 254 | with distmp3 (DISTMP3NICE). |
| 255 | .TP |
| 256 | .B PATHNAMES |
| 257 | The following configuration file options specify the pathnames of their |
| 258 | respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC, VORBIZE, |
| 259 | OGGENC, FLAC, SPEEXENC, MPPENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, CDDAFS, |
| 260 | CDDISCID, CDDBTOOL, EJECT, MD5SUM, DISTMP3, VORBISCOMMENT, NORMALIZE, CDSPEED, |
| 261 | VORBISGAIN, MKCUE and HTTPGET. |
| 262 | .TP |
| 263 | .B COMMAND-LINE OPTIONS |
| 264 | If you wish to specify command-line options to any of the programs abcde |
| 265 | uses, set the following configuration file options: LAMEOPTS, GOGOOPTS, |
| 266 | BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS, OGGENCOPTS, |
| 267 | FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, ID3OPTS, ID3V2OPTS, CDPARANOIAOPTS, |
| 268 | CDDA2WAVOPTS, CDDAFSOPTS, CDDBTOOLOPTS, EJECTOPTS, DISTMP3OPTS, NORMALIZEOPTS, |
| 269 | CDSPEEDOPTS, MKCUEOPTS,VORBISCOMMMENTOPTS, METAFLACOPTS and HTTPGETOPTS. |
| 270 | .TP |
| 271 | .B CDSPEEDVALUE |
| 272 | Set the value of the CDROM speed. The default is to read the disc as fast as |
| 273 | the reading program and the system permits. The steps are defined as 150kB/s |
| 274 | (1x). |
| 275 | .TP |
| 276 | .B ACTIONS |
| 277 | The default actions to be performed when reading a disc. |
| 278 | .TP |
| 279 | .B CDROM |
| 280 | If set, it points to the CD-Rom device which has to be used for audio |
| 281 | extraction. Abcde tries to guess the right device, but it may fail. |
| 282 | .TP |
| 283 | .B CDPARANOIACDROMBUS |
| 284 | Defined as "d" when using cdparanoia with an IDE bus and as "g" when using |
| 285 | cdparanoia with the ide-scsi emulation layer. |
| 286 | .TP |
| 287 | .B OUTPUTDIR |
| 288 | Specifies the directory to place completed tracks/playlists in. |
| 289 | .TP |
| 290 | .B WAVOUTPUTDIR |
| 291 | Specifies the temporary directory to store .wav files in. Abcde may use up |
| 292 | to 700MB of temporary space for each session (although it is rare to use |
| 293 | over 100MB for a machine that can encode music as fast as it can read it). |
| 294 | .TP |
| 295 | .B OUTPUTTYPE |
| 296 | Specifies the encoding format to output, as well as the default extension and |
| 297 | encoder. Defaults to "vorbis". Valid settings are "vorbis" (or "ogg") |
| 298 | (Ogg/Vorbis), "mp3" (MPEG-1 Audio Layer III), "flac" (Free Lossless Audio |
| 299 | Codec), "spx" (Ogg/Speex) and "mpc" (MPP/MP+ (Musepack)). Values like |
| 300 | "vorbis,mp3" encode the tracks in both Ogg/Vorbis and MP3 formats. |
| 301 | .br |
| 302 | For each value in OUTPUTTYPE, abcde expands a different process for encoding, |
| 303 | tagging and moving, so you can use the format placeholder, OUTPUT, to create |
| 304 | different subdirectories to hold the different types. The variable OUTPUT will |
| 305 | be 'vorbis', 'mp3', 'flac', 'spx' and/or 'mpc', depending on the OUTPUTTYPE you define. |
| 306 | For example |
| 307 | .br |
| 308 | OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}' |
| 309 | .TP |
| 310 | .B OUTPUTFORMAT |
| 311 | Specifies the format for completed Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+ |
| 312 | (Musepack) filenames. |
| 313 | Variables are included |
| 314 | using standard shell syntax. Allowed variables are GENRE, ALBUMFILE, ARTISTFILE, |
| 315 | TRACKFILE, TRACKNUM, and YEAR. Default is |
| 316 | \'${ARTISTFILE}-${ALBUMFILE}/${TRACKNUM}-${TRACKFILE}\'. |
| 317 | Make sure to use single quotes around this variable. TRACKNUM is |
| 318 | automatically zero-padded, when the number of encoded tracks is higher than |
| 319 | 9. When lower, you can force with '-p' in the command line. |
| 320 | .TP |
| 321 | .B VAOUTPUTFORMAT |
| 322 | Just like OUTPUTFORMAT but for Various Artists discs. Default is whatever |
| 323 | OUTPUTFORMAT is set to. |
| 324 | .TP |
| 325 | .B MAXPROCS |
| 326 | Defines how many encoders to run at once. This makes for huge speedups |
| 327 | on SMP systems. You should run one encoder per CPU at once for maximum |
| 328 | efficiency, although more doesn't hurt very much. Set it "0" when using |
| 329 | mp3dist to avoid getting encoding processes in the local host. |
| 330 | .TP |
| 331 | .B LOWDISK |
| 332 | If set to y, conserves disk space by encoding tracks immediately after |
| 333 | reading them. This is substantially slower than normal operation but |
| 334 | requires several hundred MB less space to complete the encoding of an |
| 335 | entire CD. Use only if your system is low on space and cannot encode as |
| 336 | quickly as it can read. |
| 337 | .TP |
| 338 | .B BATCH |
| 339 | If set to y, enables batch mode normalization, which preserves relative |
| 340 | volume differences between tracks of an album. Also enables nogap encoding |
| 341 | when using the \'lame\' encoder. |
| 342 | .TP |
| 343 | .B PLAYLISTFORMAT |
| 344 | Specifies the format for completed playlist filenames. Works like the |
| 345 | OUTPUTFORMAT configuration variable. Default is |
| 346 | \'${ARTISTFILE}_\-_${ALBUMFILE}.m3u\'. |
| 347 | Make sure to use single quotes around this variable. |
| 348 | .TP |
| 349 | .B PLAYLISTDATAPREFIX |
| 350 | Specifies a prefix for filenames within a playlist. Useful for http |
| 351 | playlists, etc. |
| 352 | .TP |
| 353 | .B DOSPLAYLIST |
| 354 | If set, the resulting playlist will have CR-LF line endings, needed by some |
| 355 | hardware-based players. |
| 356 | .TP |
| 357 | .B COMMENT |
| 358 | Specifies a comment to embed in the ID3 or Ogg comment field of each |
| 359 | finished track. Can be up to 28 characters long. Supports the same |
| 360 | syntax as OUTPUTFORMAT. Does not currently support ID3v2. |
| 361 | .TP |
| 362 | .B REMOTEHOSTS |
| 363 | Specifies a comma-delimited list of systems to use for remote encoding using |
| 364 | distmp3. Equivalent to -r. |
| 365 | .TP |
| 366 | .B mungefilename |
| 367 | mungefilename() is an abcde shell function that can be overridden via |
| 368 | abcde.conf. It takes CDDB data as $1 and outputs the resulting filename on |
| 369 | stdout. It defaults to eating control characters, apostrophes and |
| 370 | question marks, translating spaces and forward slashes to underscores, and |
| 371 | translating colons to an underscore and a hyphen. |
| 372 | .br |
| 373 | If you modify this function, it is probably a good idea to keep the forward |
| 374 | slash munging (UNIX cannot store a file with a '/' char in it) as well as |
| 375 | the control character munging (NULs can't be in a filename either, and |
| 376 | newlines and such in filenames are typically not desirable). |
| 377 | .TP |
| 378 | .B mungegenre |
| 379 | mungegenre () is a shell function used to modify the $GENRE variable. As |
| 380 | a default action, it takes $GENRE as $1 and outputs the resulting value |
| 381 | to stdout converting all UPPERCASE characters to lowercase. |
| 382 | .TP |
| 383 | .B pre_read |
| 384 | pre_read () is a shell function which is executed before the CDROM is read |
| 385 | for the first time, during abcde execution. It can be used to close the CDROM |
| 386 | tray, to set its speed (via "setcd" or via "eject", if available) and other |
| 387 | preparation actions. The default function is empty. |
| 388 | .TP |
| 389 | .B post_read |
| 390 | post_read () is a shell function which is executed after the CDROM is read |
| 391 | (and, if applies, before the CDROM is ejected). It can be used to read a TOC |
| 392 | from the CDROM, or to try to read the DATA areas from the CD (if any exist). |
| 393 | The default function is empty. |
| 394 | .TP |
| 395 | .B EJECTCD |
| 396 | If set to "y", abcde will call eject(1) to eject the cdrom from the drive |
| 397 | after all tracks have been read. |
| 398 | .TP |
| 399 | .B EXTRAVERBOSE |
| 400 | If set to "y", some operations which are usually now shown to the end user |
| 401 | are visible, such as CDDB queries. Useful for initial debug and if your |
| 402 | network/CDDB server is slow. |
| 403 | .SH EXAMPLES |
| 404 |