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