45b8c5f801e8fdf1a6e303ac4dc6fb7839a8c25c
[abcde.git] / FAQ
1 0. INTRODUCTION
2    ============
3
4 Q. Who created abcde? Who develops it nowadays?
5 A. It was originally created by Robert Woodcook. He decided to give up
6    maintaining it at some point in 2002 and Jesus Climent took over. In 2012,
7    Colin Tuckley and Steve McIntyre joined in to help. Currently Steve maintains
8    abcde along with Andrew Strong. Contact either with comments or suggestions
9    at the following email addresses:
10       Steve McIntyre <93sam@@debian.org>
11       Andrew Strong <andrew.david.strong@gmail.com>
12
13
14 1. INSTALLATION
15    ============
16
17 Q. How can I install abcde on my system?
18 A. To get abcde you can use a pre-packaged version, available for Debian,
19    FreeBSD, OpenBSD, NetBSD and others.
20    In case you want to install your own release, you need to download the
21    source and install the complementary programs (abcde is just a frontend
22    and its functionality is provided by other programs).
23
24    abcde needs cd-discid. Grab it from:
25    http://www.hispalinux.es/~data/files/cd-discid/
26
27    Read the README files for a complete list of requirements.
28
29 Q. I have a problem, and I reported some time ago. Have you solved it already?
30 A. Maybe. Try downloading the master branch of the development from
31    http://git.einval.com/cgi-bin/gitweb.cgi?p=abcde.git
32
33 Q. When are you going to release a new version?
34 A. When it is ready. I keep on having new ideas and adding them to the trunk
35    (stored in the URL above), so I dont release until all the ideas are
36    finished.
37
38
39 2. EXECUTION
40    =========
41
42 Q. I want to force abcde 2.x to behave more like 1.x. How do I do it?
43 A. Put these options in your abcde.conf:
44
45    INTERACTIVE=n
46    OUTPUTTYPE=mp3
47    ID3TAGV=1
48
49 Q. Low on disk space?
50 A. abcde has different algorithms to schedule ripping and encoding - to
51    optimize for disk conservation, use -l. You can also define
52    WAVOUTPUTDIR=/some/other/path to your /etc/abcde.conf or ~/.abcde.conf to
53    store the WAV files on another NFS shared fisk, for example.
54    Also, UNIX pipes have also been implemented, using "-P", so abcde reads and
55    encodes the tracks from the CD at once. However, it has the drawback that
56    only one format can be encoded at a time.
57
58 Q. How can i make abcde encode faster? My CD reader is way faster than the pace
59    it can encode my tracks.
60 A. abcde can take advantage of SMP systems, just like make. Try 'abcde -j 2' -
61    it'll run two encoder jobs while it rips the next track.
62    You can also make use of systems which are networked, with the help of
63    distmp3. For example, MachineA has a better CPU power and MachineB has a CD
64    drive. Run distmp3host (included in distmp3) on Machine A, and then run
65    abcde -r MachineA from MachineB (where "MachineA" is a dns name or IP
66    address). Use this in combination with '-j 0' to shift all encoding off the
67    local machine.
68
69 Q. I am having problems with *my CD reading program* reading the drive as a
70    user.
71 A. You might have to add yourself (or the users who want to use abcde) to the
72    cdrom group and change the permissions of the cdrom device to 660. If you
73    have a SCSI cdrom drive, check the permissions of /dev/sg* as well.
74
75 Q. I would like to give the trackname and the artist_name directly to the
76    encoder (in my case oggenc), but found no documentation.
77 A. That is not possible, since abcde gets the information from CDDB database.
78    You can create a template and fill it with the option "-n". Also, you can
79    get the CDDB entry and edit it yourself. abcde has also an option to drop
80    back to a template if you like none of the CDDB entries, selecting 0 from
81    the CDDB options.
82
83 Q. (Thanks to Amaya) Where are those options and settings defined? Why dont
84    you include a proper abcde.conf as an example?
85 A. I do. It should be installed under /etc/abcde.conf and contains more or
86    less all the defaults abcde uses. You can use $(HOME)/.abcde.conf to
87    override those defaults. More information can be obtained from the man page
88    which can be consulted using "man abcde".
89
90 Q. I keep on getting files with ".ogg.ogg" extension. What am I doing wrong?
91 A. The code for multiple-output adds automatically the extension of the
92    different outputs you select with the "-o" extension (or with OUTPUTTYPE
93    variable). Erase the ".${OUTPUTTYPE}" part from the OUTPUTFORMAT variable
94    in /etc/abcde.conf or ~/.abcde.conf
95
96 Q. I have modified some of the options, and now CDDB has stopped working.
97 A. Check that you have modified everything in the right way. For instance, if
98    you modify the HTTPGET program you might want to set some options of your
99    own. If you use the predefined ones (wget, curl and fetch) abcde will try
100    to use some defaults. Keep in mind that the output should go to the output
101    as standard output, to be saved in a file for later use.
102
103    If abcde seems to be ignoring your configuration options or not running
104    commands such as the encoder, you may have misquoted something. Config
105    options such as the following do not work:
106
107    LAMEOPTS=-h -k
108
109    Try this instead:
110
111    LAMEOPTS='-h -k'
112
113 Q. How can I separate the different output files I get using multiple-output
114    support?
115 A. Use the OUTPUT variable in PLAYLISTFORMAT and OUTPUTFORMAT. It holds the
116    different output file types you passed to abcde (i.e., ogg, mp3, flac)
117    during playlist creation and file/directory creation.
118
119 Q. I have a CD with a data track, and abcde complaints it cannot read/encode
120    it.
121 A. From version 2.2 onwards, abcde includes some checkings with cdparanoia, to
122    try to get this right.
123    (It is not easy to find a data track on a CD. Right now, I can only think
124    of getting the track info from CDDB and ask the user for continuing should
125    a "data" track name is found. But the solution is far from been optimal.
126    For now, if you find a "data" track and you know the number, restart abcde
127    specifying the tracks to be encoded, leaving out the data one).
128
129 Q. I am requested to have "eject" when setting the speed although I do not use
130    it for anything.
131 A. If you do not use cdparanoia, eject is used for setting the speed of the
132    cdrom drive. You can substitute it for "setcd" with "-x" as the argument,
133    but you have to install it manually (setcd is, at least, available in
134    Debian).
135    Another way to get the same results is using the pre_read function, defined
136    in your /etc/abcde.conf file.
137
138 Q. I have a CD set with 1+ discs, and want to have them in the same directory,
139    sorted properly. What can abcde do for me?
140 A. Set abcde to rip the first CD and give it the option "-t 101". Use a generic
141    name for the CD, and reuse it with the rest of the CDs, editing the CDDB
142    entries. Use "-t 201" for the second CD and so on. Use "-w <comment>" to
143    add a comment about the CD you are ripping (-w "disc #"). Alternatively you
144    can use only the "-t ###" option and then move all the files to the same
145    directory, but the tag/comment information on the files will differ. If you
146    want the tagged track number to be set to the modified number you should use
147    "-T ###".
148    Even better! If you use "-W <cd_number>", abcde will put a comment to every
149    CD set ("CD <number>") and modify the number of the tracks both in the file
150    name and the tag/comment information.
151
152 Q. I have a live concert. I want to encode it in a single file. How do i do it?
153 A. Use "-1" and it will be encoded in a single file. Use "cue" as an action to
154    make a CUE sheet file where the information about the tracks is stored.
155
156 Q. Can I use abcde to take a backup of my CD collection?
157 A. Yes. Use "abcde -1 -o flac -a default,cue" and it will create a single-track
158    FLAC file with an embedded cuesheet. Later on, you can use the command
159    "abcde -o vorbis -d flac-file.flac" to extract the individual tracks in
160    Ogg/Vorbis format. Of course you can select whatever format you want.
161
162
163 3. CDDB and Musicbrainz
164    ====================
165
166 Q. I need to go through an HTTP proxy for CDDB access.
167 A. No problem, just export your http_proxy variable first so wget/fetch/curl
168    can see it.
169
170 Q. I already store CDDB entries in my hard disc. Can I make use of them?
171 A. Piece of cake. Just edit CDDBLOCALDIR to point to the repository and give
172    abcde the "-L" flag to make use of it.
173
174 Q. Fine, now it uses local CDDB, but I have no network connection. How can I
175    disable CDDB checks?
176 A. Use the "-L -n" combination. It will try to use local CDDB entries, and if
177    nothing can be found, it will use a template. You will be also given the
178    choice to edit such template.
179
180 Q. How can I use some other CDDB information provider?
181 A. abcde now uses FreeDB by default. To use a different FreeDB mirror or
182    another CDDB service, change the CDDBURL option in your abcde.conf.
183
184 Q. After requesting CDDB data, I received several answers which seem to be
185    quite alike. Can I find out the difference between some of them?
186 A. Yes. When asked which one you want to select, use "X,Y" where X and Y are
187    the numbers of the selections you want to find the difference between.
188
189 Q. I don't like CDDB/FreeDB. How can I use Musicbrainz instead?
190 A. Set CDDBMETHOD=musicbrainz and try it!
191
192
193 4. abcde and Album Art
194    ===================
195
196 Q. Can abcde download album art?   
197 A. As of abcde 2.7 it is possible to download a suitable cover
198    image from within abcde that can be used by applications such
199    as Audacious and vlc to illustrate playback with an album cover.
200    Many hardware playback devices such as iPODs will also use this
201    image during playback and show it on the device's display.
202
203 Q. How does album art downloading work?
204 A. The details are contained in abcde within a new function called
205    'getalbumart' which can be called either from the commandline or 
206    from within an ~/.abcde.conf file. The technique works in 3 possible
207    ways:
208
209     1. If CDDBMETHOD is musicbrainz the album art is downloaded from
210        coverartarchive by MBID (MusicBrainz Identifier)
211     2. If 1 fails, download is tried from amazon by ASIN (Amazon 
212        Standard Identification Number)
213     3. If if 1 and 2 fail or CDDBMETHOD is cddb the album art will 
214        be downloaded using glyrc by artist + album title
215
216    You  will need to install your distro's package of glyr, a music 
217    related metadata search engine, and it is strongly advised that
218    you use 'musicbrainz' for your cddb lookups. To access the more 
219    advanced features of getalbumart it is also strongly advised that
220    you install the ImageMagick package of your distro. getalbumart 
221    will work without ImageMagick but functionality will be reduced.
222
223 Q. What settings and options should I select?
224 A. If you want to operate abcde from the commandline only you will
225    get reasonable results with something like either of the following:
226
227      abcde -o mp3:-V2 -a default,getalbumart
228      abcde -o mp3:-V2 -G
229
230    But to experience all of the options of getalbumart you should also
231    consider setting the following in your ~/.abcde.conf file:
232
233     #----------------------------------------------------------------#
234     CDDBMETHOD=musicbrainz       # Use MusicBrainz for CDDB 
235     ACTIONS=default,getalbumart  # Select the album art action + default
236
237     # Give the path to the metadata search application glyrc. Add any
238     # glyrc options:
239     GLYRC=glyrc
240     GLYRCOPTS= 
241
242     # Give the path to ImageMagick's 'identify' which is used to give a 
243     # commandline summary of the album art and also assist in any conversions.
244     # Add any 'identify' options:
245     IDENTIFY=identify
246     IDENTIFYOPTS=
247
248     # Give the path to ImageMagick's 'display' which will show the album art. 
249     # The options below are the abcde default, feel free to add your own:  
250     DISPLAYCMD=display
251     DISPLAYCMDOPTS="-resize 512x512 -title abcde_album_art"
252
253     # Give the path to ImageMagick's 'convert' which is used to convert album 
254     # art to the format specified in ALBUMARTTYPE. Add any 'convert' options:   
255     CONVERT=convert
256     CONVERTOPTS=
257     # If you want to run CONVERTOPTS on all files (including those specified
258     # in ALBUMARTTYPE) set the following to "y":
259     ALBUMARTALWAYSCONVERT="n"
260
261     # By default the filename will be cover.jpg and the file format will
262     # be jpeg. 'convert' will automagically change other formats to jpeg:
263     ALBUMARTFILE="cover.jpg"
264     ALBUMARTTYPE="JPEG"
265     #----------------------------------------------------------------#
266
267    There are more hints concerning commandline options in the sample 
268    abcde.conf file included with your abcde package. Good news is that
269    the existing defaults will work well without any extra adjustments :).
270
271 Q. Can I manually select album art?
272 A. If you have set INTERACTIVE=y (this is the default) then you will have
273    the opportunity to manually select the album art of your choice either
274    from online by typing in a URL or by typing in the path to a local file.
275    
276 Q. What if I want my album art embedded?
277 A. The philosophy of getalbumart at the moment is to simply place the album
278    art in the same location as the encoded files. Perhaps this will change
279    one day. In the meantime you can use abcde's post_encode function in
280    your ~/.abcde.conf file to embed the album art. Here is an example for
281    mp3 embedding using eyeD3:
282
283    #----------------------------------------------------------------#
284    post_encode ()
285    {
286     ARTISTFILE="$(mungefilename "$TRACKARTIST")"
287     ALBUMFILE="$(mungefilename "$DALBUM")"
288
289    if [ "$VARIOUSARTISTS" = "y" ] ; then
290      FINDPATH="$(eval echo "$VAOUTPUTFORMAT")"
291    else
292      FINDPATH="$(eval echo "$OUTPUTFORMAT")"
293    fi
294
295    FINALDIR="$(dirname "$OUTPUTDIR/$FINDPATH")"
296    cd "$FINALDIR"
297
298    if [ "$OUTPUTTYPE" = "mp3" ] && [ "$TAGGER" = "$EYED3" ] ; then
299     vecho "Preparing to embed the album art..." >&2
300    else
301     vecho "Not embedding album art, you need mp3 output and eyeD3 tagging..." >&2
302     return 1
303    fi
304
305     if [ -e "cover.jpg" ] ; then
306       for i in *.mp3
307       do
308       eyeD3 --add-image cover.jpg:FRONT_COVER "$i"
309       done
310       mkdir backup && mv cover.jpg backup
311       vecho "Your files have had the album art embedded..." >&2
312     else
313      vecho "No album art found so no image embedded..." >&2
314     fi
315    }
316   #----------------------------------------------------------------#
317
318   Variations of the 'for' loop in this example should work for other encoding 
319   types. For example with flac:
320
321    #--------------------
322    for i in *.flac
323    do 
324     metaflac --import-picture-from=cover.jpg "$i"
325    done
326    #--------------------
327
328   With other appropriate adjustments to the $OUTPUTTYPE and $TAGGER checks of 
329   course...
330
331   
332 4. FORMATS
333    =======
334
335 Q. What formats can I encode my music to?
336 A. As for version 2.2, abcde includes support for MP3, Ogg/Vorbis,
337    Ogg/Speex, Flac and MPP/MP+(Musepack). Support for AAC will be added once
338    an FLOSS encoder/decoder is working.
339
340 Q. I want the new *put the newest and coolest codec there* format to be
341    supported by abcde. Abcde is so cool but i want to encode also to this
342    new format...
343 A. Patches are welcome! ;)
344    No, seriously, if the format is usable, available for Linux and open
345    source/free software, it should be fairly easy to integrate. Support for
346    AAC (m4p) should be the next one to be introduced.
347
348 Q. I use Debian/RedHat/(put your Unix flavour here) and MP3 encoding is not
349    working. What am I doing wrong?
350 A. Since MP3 is considered non-free (you get it for free, but hardware players
351    and net broadcasters have to pay license fees), some release engineering
352    groups and release management teams have decided not to provide MP3 encoding
353    tools.
354    These distributions or operative systems have decided to use Ogg/Vorbis as
355    the default encoding format, since it contains no (known) patent claims
356    and they are (supposed to be) completely Free (released under a BSD-like
357    license).
358    However, there is no strong (at the moment) hardware support, although
359    some groups and companies are strongly working on getting it, real soon
360    now. For that reason some people prefer to encode to MP3.
361
362    UPDATE *** UPDATE
363    There are known brands already selling Ogg/Vorbis portable players: Rio,
364    iRiver, Neuros, iAudio,...
365    Go buy one and you have no more reasons to use MP3.
366
367    If you are among those individuals, you might need to add support for MP3
368    encoding to your system:
369    Debian : check http://ftp.nerim.net/debian-marillat to install lame in your
370             system. Others prefer bladeenc. Check www.apt-get.org or google.
371    RedHat : search on rpmfind.net
372    FreeBSD: By default includes LAME support.
373    OpenBSD: Available by specifying you want to install the port with LAME
374             support, or by just installing it later from the ports tree.
375    NetBSD : Available in pkgsrc.
376
377    Others : Please, help me here.
378
379 Q. Huh! Why is MPPENCODER (with MPP) and .mpc the extension?
380 A. Dunno. You must ask the guys who created and defined the format. The
381    standard is MPEGplus (MPP/MP+) but the files use .mpc extension.
382    
383 Q. Why do I get .aac files instead of .m4a files when I encode with faac?
384 A. Faac uses mp4v2 to create aac files in an m4a or mp4 container. Some 
385    Linux distros have disabled this mp4v2 support due to a licensing issue 
386    and this leave faac only capable of generating mpeg-2/ADTS streams. 
387    These streams should correctly have the .aac file extension and some 
388    players (such as Audacious) will not even play mpeg-2/ADTS streams when
389    they are placed in an .m4a container.
390    As of version 2.7 abcde tests the version of faac being used for mp4v2 
391    support and then appropriately  places the audio either in .m4a or .aac. 
392    Note that tagging is not possible with mpeg-2/ADTS streams in .aac.
393    
394 Q. How do I encode to Apple Lossless Audio Codec (alac)?
395 A. As of abcde 2.7.1 there are 3 ways to encode to alac: using qaac, refalac
396    or FFmpeg. To use qaac or refalac follow the installation directions here:
397
398    http://www.andrews-corner.org/qaac.html#installation
399
400    and then set your ~/.abcde.conf file as follows:
401
402    AACENCODERSYNTAX=qaac
403    QAAC="$HOME/.wine/drive_c/qaac/qaac.exe"
404    # Or use the Open Source alac encoder with this small hack:
405    # QAAC="$HOME/.wine/drive_c/qaac/refalac.exe"
406    QAACENCOPTS="--alac --threading --verbose"
407    OUTPUTTYPE="m4a"
408
409    To use FFmpeg (or avconv) set your ~/.abcde.conf file as follows:
410
411    AACENCODERSYNTAX=ffmpeg
412    FFMPEG=ffmpeg
413    # Or give the path to avconv instead:
414    # FFMPEG=avconv
415    FFMPEGENCOPTS="-c:a alac"
416    OUTPUTTYPE="m4a"
417
418    And then sit back and enjoy the music :)
419
420 Q. Will FFmpeg be used with abcde for any other audio formats?
421 A. The plan is to use FFmpeg (or avconv) when FFmpeg has a good quality native
422    encoder available. For example FFmpeg has a low quality native native encoder
423    for Vorbis and AAC which will not be used but a great reverse engineered alac
424    encoder that has been used in abcde. FFmpeg also has a good WavPack encoder
425    that has been added in abcde 2.7.1 which can be added into your ~/.abcde.conf
426    file as follows:
427
428    # WVENCODERSYNTAX=wavpack
429    WVENCODERSYNTAX=ffmpeg
430    # Appropriate PATH:
431    WAVPACK=wavpack
432    FFMPEG=ffmpeg
433    # Appropriate options:
434    FFMPEGENCOPTS="-c:a wavpack -compression_level 6"
435    WAVPACKENCOPTS="-hx3"
436    # Correct output type:
437    OUTPUTTYPE="wv"
438
439    You can see in this example how easy it is to switch from one WavPack encoder to
440    another by changing the comment mark '#' on the WVENCODERSYNTAX line. Plans are
441    to use FFmpeg for True Type Audio (tta) as well as MPEG-1 Audio Layer II (mp2) as
442    well as respectively ttaenc and twolame.
443
444 5. USEPIPES
445    ========
446
447 Q. What is/are 'USEPIPES'??
448 A. This is a slightly different method of ripping and encoding with abcde
449    utilising Unix pipes. Using this method a program sends as output what
450    another programs expects as input without writing the information to the
451    hard disk. For it to work with abcde, a ripper must send the data of the
452    CD tracks which are ripped to the 'standard output', while sending other
453    information and error messages to 'standard error' so that the encoder
454    does not get confused. The encoder program needs to be able to encode the
455    information send to it by reading from the standard input (which is what
456    the ripper sends to the standard output).
457    Usually Unix/Linux programs deal with the standard input/output by using
458    the special file name '-', as in the following example:
459
460    cdripper -o - | audioencoder -i - -o file.ext
461
462    The 'cdripper' program uses the flag '-o' to identify the file it will
463    output the data to. For the 'audioencoder' program to be able to read
464    the output through a Unix pipe (the '|' symbol), the output needs to be
465    sent to the standard output using the '-' special filename. Once the
466    output has been piped to 'audioencoder' we use the same special filename
467    to read the information as input with the '-i' flag and output it to
468    'file.ext' with the '-o' flag.
469
470 Q. How do I use USEPIPES with abcde?
471 A. You can run USEPIPES in either of two ways:
472
473      1. Add 'USEPIPES=y' to your ~/.abcde.conf file
474      2. Use the commandline option 'abcde -P'
475
476 Q. Do all rippers and encoders work with USEPIPES?
477 A. No :). Keep in mind that every ripper and encoder differs from in each
478    other in the way they interact with pipes and not all rippers and encoders
479    will use or understand the '-o' and '-' options. Currently (July 2015) the
480    following rippers and encoders work:
481
482    Rippers:  cdparanoia, debug, libcdio, cdda2wav, flac, pird.
483    Encoders: mp3enc, lame, bladeenc, oggenc, opusenc, flac, speexenc,
484              mpcenc, wavpack, faac, neroAacEnc, fdkaac, qaac, fhgaacenc,
485              ffmpeg.
486
487 Q. Can I add a ripper or encoder which is not supported?
488 A. Sure! If you plan to use a ripper or encoder which is not supported you
489    need to know how to use the ripper/encoder. For example, cdparanoia just
490    uses '-' as the output filename and works. The program used to decode
491    FLAC files (yes, abcde supports 'ripping' from a FLAC file :) uses '-c'.
492    To add support for a ripper called 'cdripper' which uses the '-' special
493    flag for outputting to the standard output, you need to open the config
494    file (either /etc/abcde.conf or ~/.abcde.conf) and add the line:
495
496      PIPERIPPER_cdripper="-"
497    
498    For an encoder called 'audioencoder' which uses '--stdin' to read the pipe
499   input, you need to add:
500
501      PIPE_audioencoder="--stdin"
502
503   Of course, you should try your configuration and report it to the abcde
504   developers so that it can be included in future versions of abcde. If
505   you are familiar with POSIX shell programing, please open "abcde" and
506   take a look at the lines below the one marked with "###USEPIPESSUPPORT###",
507   the required syntax is reasonably clear.
508
509 6. MISC PROBLEMS
510    =============
511
512 Q. What happened with normalize?
513 A. Normalize has changed its name under Debian, which is the GNU/Linux
514    distribution for developing abcde (well, is The GNU/Linux Distribution
515    i only use, at the moment). Now it is called normalize-audio.
516    If you are using some other flavour of OS, you need to change the name
517    of the executable in your abcde.conf file.
518
519 Q. I am using MacOSX and I am having problems to use abcde.
520 A. Well, I have a Mac, but I use linux on it. I have not been able to find
521    a way to make it work there, since I do not have the development tools
522    installed. I have placed a basic support, but some user reports are just
523    complaining about abcde not encoding the ripped tracks, as if
524    icedax/cdda2wav/cdparanoia/cddafs would never end reading them. If you have
525    such a system and experience problems, please, report them, and I will
526    try to work them out with your help.
527
528 Q. My hardware player (put it here) does not recognize the playlists created
529    with abcde. What I am doing wrong?
530 A. Try using "-m" when creating the playlists, or setting DOSPLAYLIST as an
531    option in the config file.
532
533 OBSOLETE
534 --------
535 Q. I set KEEPWAVS to "y" but abcde insists on erasing my directory, along
536    with the wav tracks. What I am doing wrong?
537 A. The default action set includes clean, which cleans the temp directory,
538    if nothing goes wrong. Take the "clean" out from the action list and you
539    are done.
540    UPDATE: KEEPWAVS unselects now the clean action.
541
542 --
543 Jesus Climent <jesus.climent@hispalinux.es>
544 Andrew Strong <andrew.david.strong@gmail.com>