r168@frost: data | 2005-09-19 10:27:33 +0300
[abcde.git] / abcde.1
diff --git a/abcde.1 b/abcde.1
index 61b88b3..85831f3 100644 (file)
--- a/abcde.1
+++ b/abcde.1
@@ -1,4 +1,4 @@
-.TH ABCDE 1
+.TH abcde 1
 .SH NAME
 abcde \- Grab an entire CD and compress it to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack) format.
 .SH SYNOPSIS
@@ -66,6 +66,9 @@ CD\-ROM block device that contains audio tracks to be read.
 Capture debugging information (you'll want to redirect this \- try 'abcde \-D
 2>logfile')
 .TP
+.B \-h
+Get help information.
+.TP
 .B \-j [number]
 Start [number] encoder processes at once. Useful for SMP systems. Overrides
 the MAXPROCS configuration variable. Set it to "0" when using distmp3 to avoid
@@ -80,21 +83,27 @@ Use the low-diskspace algorithm. See the LOWDISK configuration variable.
 .B \-L
 Use a local CDDB repository. See CDDBLOCALDIR variable.
 .TP
-.B -n
+.B \-n
 Do not query CDDB database. Create and use a template. Edit the template to
 provide song names, artist(s), ...
 .TP
-.B -N
+.B \-N
 Non interactive mode. Do not ask anything from the user. Just go ahead.
 .TP
-.B -m
+.B \-m
 Create DOS-style playlists, modifying the resulting one by adding CRLF line
 endings. Some hardware players insist on having those to work.
 .TP
-.B \-o [filetype]
-Select output type. Can be "ogg", "mp3", "flac", "spx" or "mpc". Specify a 
-comma-delimited list of output types to obtain all specified types. See 
-the OUTPUTTYPE configuration variable.
+.B \-M
+Create a CUE file with information about the CD. Together with the possibility
+of creating a single file (see option "\-1"), one can recreate the original CD.
+.TP
+.B \-o [filetype][:filetypeoptions]
+Select output type. Can be "vorbis" (or "ogg"), "mp3", "flac", "spx" or "mpc".
+Specify a comma-delimited list of output types to obtain all specified types.
+See the OUTPUTTYPE configuration variable. One can pass options to the encoder
+for a specific filetype on the command line separating them with a colon. The
+options must be escaped with double-quotes.
 .TP
 .B \-p
 Pads track numbers with 0\'s.
@@ -103,14 +112,26 @@ Pads track numbers with 0\'s.
 Remote encode on this comma-delimited list of machines using distmp3. See
 the REMOTEHOSTS configuration variable.
 .TP
-.B \-s [number]
-Start the numbering of the tracks at a given number. It only affects the
-filenames and the playlist. Internal (tag) numbering remains the same.
+.B \-R
+Add replaygain information to the id3 or tag information for play
+normalization. Only works with MP3 and Ogg/Vorbis.
+.TP
+.B \-s [fields...]
+List, separated by comas, the fields to be shown in the CDDB parsed entries.
+Right now it only uses "year" and "genre".
 .TP
 .B \-S [speed]
 Set the speed of the CD drive. Needs CDSPEED and CDSPEEDOPTS set properly
 and both the program and device must support the capability.
 .TP
+.B \-t [number]
+Start the numbering of the tracks at a given number. It only affects the
+filenames and the playlist. Internal (tag) numbering remains the same.
+.TP
+.B \-T [number]
+Same as \-t but changes also the internal (tag) numbering. Keep in mind that
+the default TRACK tag for MP3 is $T/$TRACKS so it is changed to simply $T.
+.TP
 .B \-v
 Show the version and exit
 .TP
@@ -122,8 +143,12 @@ sensation nothins is happening.
 Eject the CD when all tracks have been read. See the EJECTCD configuration
 variable.
 .TP
-.B \-h
-Get help information.
+.B \-w [comment]
+Add a comment to the tracks ripped from the CD.
+.TP
+.B \-W [number]
+Concatenate CD\'s. It uses the number provided to define a comment "CD #" and
+to modify the numbering of the tracks, starting with "#01".
 .TP
 .B [tracks]
 A list of tracks you want abcde to process. If this isn't specified, abcde
@@ -134,11 +159,14 @@ Each track is, by default, placed in a separate file named after the track
 in a subdirectory named after the artist under the current directory. 
 This can be modified using the OUTPUTFORMAT and VAOUTPUTFORMAT
 variables in your abcde.conf. Each file is given an extension identifying 
-its compression format, '.ogg', '.mp3', '.flac', '.spx', or '.mpc'.
+its compression format, 'vorbis' for '.ogg', '.mp3', '.flac', '.spx', or '.mpc'.
 .SH CONFIGURATION
 abcde sources two configuration files on startup - /etc/abcde.conf and
 $HOME/.abcde.conf, in that order. 
 .TP
+The configuration options stated on those files can ba overriden by providing
+the appropiate flags at runtime.
+.TP
 The configuration variables have to be set as follows:
 .TP
 .B VARIABLE=value
@@ -154,6 +182,29 @@ Here is a list of options abcde recognizes:
 .B CDDBURL
 Specifies a server to use for CDDB lookups.
 .TP
+.B HELLOINFO
+Specifies the Hello information to send to the CDDB server. The CDDB
+protocol requires you to send a valid username and hostname each time you
+connect. The format of this is username@hostname.
+.TP
+.B CDDBLOCALDIR
+Specifies a directory where we store a local CDDB repository. The entries must
+be standard CDDB entries, with the filename being the DISCID value. Other
+CD playing and ripping programs (like Grip) store the entries under ~/.cddb
+and we can make use of those entries.
+.TP
+.B CDDBCOPYLOCAL
+Store local copies of the CDDB entries under the $CDDBLOCALDIR directory.
+.TP
+.B CDDBUSELOCAL
+Actually use the stored copies of the CDDB entries. Can be overriden using the 
+"-L" flag (if is CDDBUSELOCAL in "n"). If an entry is found, we always give 
+the choice of retrieving a CDDB entry from the internet.
+.TP
+.B SHOWCDDBFIELDS
+Coma-separated list of fields we want to parse during the CDDB parsing.
+Defaults to "year,genre".
+.TP
 .B OGGENCODERSYNTAX
 Specifies the style of encoder to use for the Ogg/Vorbis encoder. Valid options 
 are \'oggenc\' (default for Ogg/Vorbis) and \'vorbize\'.
@@ -180,26 +231,66 @@ point we only have \'mppenc\' available, from corecodecs.org.
 .TP
 .B NORMALIZERSYNTAX
 Specifies the style of normalizer to use.  Valid options are \'default\'
-and \'normalize'\ (and both run \'normalize\'), since we only support it, ATM.
+and \'normalize'\ (and both run \'normalize-audio\'), since we only support it,
+ATM.
 .TP
-.B HELLOINFO
-Specifies the Hello information to send to the CDDB server. The CDDB
-protocol requires you to send a valid username and hostname each time you
-connect. The format of this is username@hostname.
+.B CDROMREADERSYNTAX
+Specifies the style of cdrom reader to use. Valid options are \'cdparanoia\'
+and \'debug\'. It is used for querying the CDROM and obtain a list of valid
+tracks and DATA tracks. Right now, only cdparanoia is supported.
 .TP
-.B CDDBLOCALDIR
-Specifies a directory where we store a local CDDB repository. The entries must
-be standard CDDB entries, with the filename being the DISCID value. Other
-CD playing and ripping programs (like Grip) store the entries under ~/.cddb
-and we can make use of those entries.
+.B CUEREADERSYNTAX
+Specifies the syntax of the program we use to read the CD CUE sheet. Right now
+we only support \'mkcue\', but in the future other readers might be used.
 .TP
-.B CDDBCOPYLOCAL
-Store local copies of the CDDB entries under the $CDDBLOCALDIR directory.
+.B KEEPWAVS
+It defaults to no, so if you want to keep those wavs ripped from your CD,
+set it to "y". You can use the "-k" switch in the command line. The default
+behaviour with KEEPWAVS set is the keep the temporary directory and the wav
+files even you have requested the "clean" action.
 .TP
-.B CDDBUSELOCAL
-Actually use the stored copies of the CDDB entries. Can be overriden using the 
-"-L" flag (if is CDDBUSELOCAL in "n"). If an entry is found, we always give 
-the choice of retrieving a CDDB entry from the internet.
+.B PADTRACKS
+If set to "y", it adds 0's to the file numbers to complete a two-number 
+holder. Useful when encoding tracks 1-9.
+.TP
+.B INTERACTIVE
+Set to "n" if you want to perform automatic rips, without user intervention.
+.TP
+.B NICE VALUES
+Define the values for priorities (nice values) for the different CPU-hungry
+processes: encoding (ENCNICE), CDROM read (READNICE) and distributed encoder
+with distmp3 (DISTMP3NICE).
+.TP
+.B PATHNAMES
+The following configuration file options specify the pathnames of their
+respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC, VORBIZE,
+OGGENC, FLAC, SPEEXENC, MPPENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, CDDAFS,
+CDDISCID, CDDBTOOL, EJECT, MD5SUM, DISTMP3, VORBISCOMMENT, NORMALIZE, CDSPEED,
+VORBISGAIN, MKCUE and HTTPGET.
+.TP
+.B COMMAND-LINE OPTIONS
+If you wish to specify command-line options to any of the programs abcde
+uses, set the following configuration file options: LAMEOPTS, GOGOOPTS,
+BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS, OGGENCOPTS,
+FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, ID3OPTS, ID3V2OPTS, CDPARANOIAOPTS,
+CDDA2WAVOPTS, CDDAFSOPTS, CDDBTOOLOPTS, EJECTOPTS, DISTMP3OPTS, NORMALIZEOPTS,
+CDSPEEDOPTS, MKCUEOPTS,VORBISCOMMMENTOPTS, METAFLACOPTS and HTTPGETOPTS.
+.TP
+.B CDSPEEDVALUE
+Set the value of the CDROM speed. The default is to read the disc as fast as
+the reading program and the system permits. The steps are defined as 150kB/s
+(1x).
+.TP
+.B ACTIONS
+The default actions to be performed when reading a disc.
+.TP
+.B CDROM
+If set, it points to the CD-Rom device which has to be used for audio
+extraction. Abcde tries to guess the right device, but it may fail.
+.TP
+.B CDPARANOIACDROMBUS
+Defined as "d" when using cdparanoia with an IDE bus and as "g" when using
+cdparanoia with the ide-scsi emulation layer.
 .TP
 .B OUTPUTDIR
 Specifies the directory to place completed tracks/playlists in.
@@ -209,6 +300,21 @@ Specifies the temporary directory to store .wav files in. Abcde may use up
 to 700MB of temporary space for each session (although it is rare to use
 over 100MB for a machine that can encode music as fast as it can read it).
 .TP
+.B OUTPUTTYPE
+Specifies the encoding format to output, as well as the default extension and
+encoder. Defaults to "vorbis". Valid settings are "vorbis" (or "ogg")
+(Ogg/Vorbis), "mp3" (MPEG-1 Audio Layer III), "flac" (Free Lossless Audio
+Codec), "spx" (Ogg/Speex) and "mpc" (MPP/MP+ (Musepack)). Values like
+"vorbis,mp3" encode the tracks in both Ogg/Vorbis and MP3 formats.
+.br
+For each value in OUTPUTTYPE, abcde expands a different process for encoding,
+tagging and moving, so you can use the format placeholder, OUTPUT, to create 
+different subdirectories to hold the different types. The variable OUTPUT will
+be 'vorbis', 'mp3', 'flac', 'spx' and/or 'mpc', depending on the OUTPUTTYPE you define.
+For example
+.br
+OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}'
+.TP
 .B OUTPUTFORMAT
 Specifies the format for completed Ogg/Vorbis, MP3, FLAC, Ogg/Speex or MPP/MP+ 
 (Musepack) filenames.
@@ -220,44 +326,10 @@ Make sure to use single quotes around this variable. TRACKNUM is
 automatically zero-padded, when the number of encoded tracks is higher than
 9. When lower, you can force with '-p' in the command line.
 .TP
-.B OUTPUTTYPE
-Specifies the encoding format to output, as well as the default extension and
-encoder. Defaults to "ogg". Valid settings are "ogg" (Ogg/Vorbis), "mp3"
-(MPEG-1 Audio Layer III), "flac" (Free Lossless Audio Codec), "spx" (Ogg/Speex)
-and "mpc" (MPP/MP+ (Musepack)). Values like "ogg,mp3" encode the tracks in 
-both Ogg/Vorbis and MP3 formats.
-.P
-For each value in OUTPUTTYPE, abcde expands a different process for encoding,
-tagging and moving, so you can use the format placeholder, OUTPUT, to create 
-different subdirectories to hold the different types. The variable OUTPUT will
-be 'ogg', 'mp3', 'flac', 'spx' and/or 'mpc', depending on the OUTPUTTYPE you define.
-For example
-.P
-OUTPUTFORMAT='${OUTPUT}/${ARTISTFILE}/${ALBUMFILE}/${TRACKNUM}._${TRACKFILE}'
-.TP
 .B VAOUTPUTFORMAT
 Just like OUTPUTFORMAT but for Various Artists discs. Default is whatever
 OUTPUTFORMAT is set to.
 .TP
-.B PATHNAMES
-The following configuration file options specify the pathnames of their
-respective utilities: LAME, GOGO, BLADEENC, L3ENC, XINGMP3ENC, MP3ENC,
-VORBIZE, OGGENC, FLAC, SPEECENC, MPPENC, ID3, ID3V2, CDPARANOIA, CDDA2WAV, 
-HTTPGET, CDDISCID, CDDBTOOL, EJECT, NORMALIZE, DISTMP3, VORBISCOMMENT, and 
-CDSPEED.
-.TP
-.B COMMAND-LINE OPTIONS
-If you wish to specify command-line options to any of the programs abcde
-uses, set the following configuration file options: LAMEOPTS, GOGOOPTS,
-BLADEENCOPTS, L3ENCOPTS, XINGMP3ENCOPTS, MP3ENCOPTS, VORBIZEOPTS,
-OGGENCOPTS, FLACOPTS, SPEEXENCOPTS, MPPENCOPTS, ID3OPTS, ID3V2OPTS, 
-CDPARANOIAOPTS, CDDA2WAVOPTS, HTTPGETOPTS, CDDBTOOLOPTS, EJECTOPTS, 
-DISTMP3OPTS, NORMALIZEOPTS, CDSPEEDOPTS, and CDSPEEDVALUE.
-.TP
-.B CDROM
-If set, it points to the CD-Rom device which has to be used for audio
-extraction. Abcde tries to guess the right device, but it may fail.
-.TP
 .B MAXPROCS
 Defines how many encoders to run at once. This makes for huge speedups
 on SMP systems. You should run one encoder per CPU at once for maximum
@@ -276,16 +348,6 @@ If set to y, enables batch mode normalization, which preserves relative
 volume differences between tracks of an album. Also enables nogap encoding
 when using the \'lame\' encoder.
 .TP
-.B KEEPWAVS
-It defaults to no, so if you want to keep those wavs ripped from your CD,
-set it to "y". You can use the "-k" switch in the command line. The default
-behaviour with KEEPWAVS set is the keep the temporary directory and the wav
-files even you have requested the "clean" action.
-.TP
-.B PADTRACKS
-If set to "y", it adds 0's to the file numbers to complete a two-number 
-holder. Usefull when encoding tracks 1-9.
-.TP
 .B PLAYLISTFORMAT
 Specifies the format for completed playlist filenames. Works like the
 OUTPUTFORMAT configuration variable. Default is
@@ -321,9 +383,50 @@ slash munging (UNIX cannot store a file with a '/' char in it) as well as
 the control character munging (NULs can't be in a filename either, and
 newlines and such in filenames are typically not desirable).
 .TP
+.B mungegenre
+mungegenre () is a shell function used to modify the $GENRE variable. As
+a default action, it takes $GENRE as $1 and outputs the resulting value
+to stdout converting all UPPERCASE characters to lowercase.
+.TP
+.B pre_read
+pre_read () is a shell function which is executed before the CDROM is read
+for the first time, during abcde execution. It can be used to close the CDROM
+tray, to set its speed (via "setcd" or via "eject", if available) and other
+preparation actions. The default function is empty.
+.TP
+.B post_read
+post_read () is a shell function which is executed after the CDROM is read
+(and, if applies, before the CDROM is ejected). It can be used to read a TOC
+from the CDROM, or to try to read the DATA areas from the CD (if any exist).
+The default function is empty.
+.TP
 .B EJECTCD
 If set to "y", abcde will call eject(1) to eject the cdrom from the drive
 after all tracks have been read.
+.TP
+.B EXTRAVERBOSE
+If set to "y", some operations which are usually now shown to the end user
+are visible, such as CDDB queries. Useful for initial debug and if your
+network/CDDB server is slow.
+.SH EXAMPLES
+Possible ways one can call abcde
+.TP
+.B abcde
+Will work in most systems
+.TP
+.B abcde -d /dev/cdrom2
+If the CDROM you are reding from is not the standard /dev/cdrom (in GNU/Linux systems)
+.TP
+.B abcde -o vorbis,flac
+Will create both Ogg/Vorbis and Ogg/FLAC files.
+.TP
+.B abcde -o vorbis:"-b 192"
+Will pass "-b 192" to the Ogg/Vorbis encoder, without having to modify the
+config file
+.TP
+.B abcde -W 1
+For double CDs settings: will create the 1st CD starting with the track number
+101, and will add a comment "CD 1" to the tracks
 .SH BACKEND TOOLS
 abcde requires the following backend tools to work:
 .TP
@@ -351,7 +454,7 @@ An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, among others
 .BR cdparanoia (1),
 .BR cdda2wav (1),
 .BR dagrab (1),
-.BR normalize (1),
+.BR normalize-audio (1),
 .BR oggenc (1),
 .BR vorbize (1),
 .BR flac (1),
@@ -365,5 +468,5 @@ An HTTP retrieval program: wget, fetch (FreeBSD) or curl (Mac OS X, among others
 .BR distmp3host (1),
 .BR curl(1)
 .SH AUTHORS
-Robert Woodcock <rcw@debian.org>
-Jesus Climent <jesus.climent@hispalinux.es>
+Robert Woodcock <rcw@debian.org>,
+Jesus Climent <jesus.climent@hispalinux.es> and contributions from many others.