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