* Bumped to 2.4
[abcde.git] / README
diff --git a/README b/README
index 3e80ccd..9e58a0b 100644 (file)
--- a/README
+++ b/README
@@ -2,56 +2,95 @@ ABCDE
 =====
 
 abcde is a frontend command-line utility (actually, a shell script) that
-grabs tracks off a CD, encodes them to Ogg/Vorbis, MP3, FLAC or Ogg/Speex
+grabs tracks off a CD or a singletrack flac file with an embeded cuesheet,
+encodes them to Ogg/Vorbis, MP3, FLAC, Ogg/Speex and/or MPP/MP+(Musepack)
 format, and tags them, all in one go.
 
-Your finished Ogg/MP3/FLAC/Speex's are, by default, stored in a subdirectory of 
-the current directory (named after the artist) with a filename based on the
-track title. Spaces are replaced by underscores, and apostrophes and
-control codes are filtered out. Colons are replaced with an underscore and a
-hyphen. The end result usually looks like: Our_Lady_Peace/01.Supermans_Dead.ogg
-This filename munging is customizable - edit the mungefilename function in
-your abcde.conf to change it.
+Your finished Ogg/MP3/FLAC/Speex/MPP's are, by default, stored in a subdirectory
+of the current directory (named after the artist) with a filename based on the
+track title. Spaces are replaced by underscores, and apostrophes and control
+codes are filtered out. Colons are replaced with an underscore and a hyphen. The
+end result usually looks like: Our_Lady_Peace/01.Supermans_Dead.ogg This
+filename munging is customizable - edit the mungefilename function in your
+abcde.conf to change it.
 
-Need to go through an HTTP proxy for CDDB access? No problem, just export
-your http_proxy variable first so wget/fetch/curl can see it.
-
-You already store CDDB entries for your CD collection on your hard disk? Piece
-of cake. Just edit CDDBLOCALDIR to point to the repository and give abcde the 
-"-L" flag to make use of it.
-
-Low on disk space? abcde has different algorithms to schedule ripping and
-encoding - to optimize for disk conservation, use -l.
-
-abcde can also take advantage of SMP systems, just like make. Try
-'abcde -j 2' - it'll run two encoder jobs while it rips the next
-track.
-
-abcde now uses FreeDB by default. To use a different FreeDB mirror or
-another CDDB service, change the CDDBURL option in your abcde.conf.
-
-Frustrated that you can't use the CPU power on Machine A sitting right
-next to Machine B with the fast cdrom drive? Now you don't have to be -
-Run distmp3host (included in distmp3) on Machine A, and then run
-abcde -r MachineA from Machine B (where "MachineA" is a dns name or IP
-address). Use this in combination with '-j 0' to shift all encoding off the
-local machine.
-
-You do not have internet connection, or just feel with free time to write 
-down all the song names and artists instead of using CDDB? Use -n and edit
-the template.
-
-To make abcde 2.x work more like 1.x, put these options in your abcde.conf:
-
-INTERACTIVE=n
-OUTPUTTYPE=mp3
-ID3TAGV=1
-
-NOTICE: abcde needs cd-discid. Grab it from:
-http://www.hispalinux.es/~data/files/cd-discid/
+Many of the questions related of problems executing abcde have been moved to the
+FAQ, which should be distributed along with this package. Reffer to that file 
+for more help.
 
 MAJOR CHANGES
 =============
+Changes in 2.4:
+* Read TOC entries from the CD. The default uses cdrdao. The program mkcue is
+  also optional.
+* Possibility to use CDDBCHOICE1,CDDBCHOICE2 (i.e., 1,3) to get a diff of two
+  parsed CDDB entries.
+* Added SHOWCDDBFIELDS to define wether to show the YEAR and GENRE fields from
+  the CDDB output.
+* Added the possibility of embeding a cuesheet on a singletrack flac file. A
+  single BACKUP flag is most likely needed to use all the needed flags:
+  "abcde -1 -o flac -a default,cue"
+* Added the possibility of using a singletrack flac file with an embeded
+  cuesheet as a source to extract tracks from (use -X to specify an external
+  CUE2DISCID implementation; check under examples in the distributed source
+  code or package).
+* Added replaygain for Ogg/Vorbis and Ogg/FLAC.
+* Added M4A encoding.
+* Uses the default found $CDROMREADER instead of forcing cdparanoia when
+  cdda2wav is installed.
+* BATCH mode has been split into two options: BATCHNORM and NOGAP.
+* Added -U option for non-UNICODE (non UTF-8) tag encoding.
+* Added -z for debug.
+* Added -f to force the removal of left files.
+* CUE support has changed from a flag (-M) to an action (cue).
+Changes in 2.3:
+* Support for mkcue, to create a CUE sheet of the CD structure. It can be used
+  with "-1" to create a backup, so that later the original CD can be recreated.
+* New -o <output(1)>:<options(1)>,... way of passing specific options to an
+  output. Now we can pass specific options without having to modify a config
+  file. This feature was already present in the last versions of the 2.2 cycle.
+* Unix PIPEs, as a second way to encode files with a low disc space.
+* Option to erase the "encoded" entries from the status file. Allows one to
+  encode the wav files (in case they were not erased) into another format. This
+  is needed until status information is stored for each format.
+* The "ogg" output mode will be substituted for "vorbis" in the near future.
+  This release adds a compatibility layer so that both entries work.
+* The FLAC encoder forces the files to be overwritten, in case they previously
+  exists. This avoids a half-through abcde run to continue without errors in
+  case it was cancelled during the FLAC encoding.
+* Added a post_read() function so that we can do things with the CD before we
+  eject it.
+
+Changes in 2.2:
+
+* Support for MPP/MP+(Musepack) format. It can be downloaded from
+  corecodecs.org. It is supposed to be Free (not only free), and released under
+  the GPL...
+* New "-t <number>" option for starting the numbering of the output files at a
+  given starting number. Ideal for albums with more than one CD.  
+* New "-T <number>" option, similar to "-t" but also modifies the tag entries
+  on the files themselves.
+* New "-w <COMMENT>" to add a comment to the tracks of a given CD rip. Use
+  quotes.
+* New "-W <number>" option to combine both a comment with "CD #number" and a
+  starting number for both the tracks and the tags with "#01" (that is, 101 for
+  the 1st CD, 201 for the second...)
+* Support for keeping an existing playlist (and not add new entries to it),
+  erase the existing one (overwrite) or append new entries to the existing
+  one.
+* Under ./examples you will find a very basic way to make abcde run in the
+  background and start a non-interactive rip of a CD, if it can find an
+  audio CD in the tray.
+  The abcded script depends on eject and cdparanoia being installed in your
+  system.
+* New mungegenre function to switch off (or modify) the default behaviour of
+  transforming uppercase characters to lowercase.
+* cdparanoia permits performing a query to the CD drive and obtain a list of 
+  valid audio tracks. So, now we perform such query and process the results.
+* Support for "None of the above" has been added with the "0" selection. A 
+  template is created, and the selection to edit it is defaulted to "y".
+
 New options in 2.1.19:
 
 * ONETRACK mode has been introduced. Setting the flag "-1" will create a
@@ -60,20 +99,20 @@ New options in 2.1.19:
 Changes in 2.1.18:
 
 * CDSPEED option defaults to eject. However, since cdparanoia has a built-in
-  option to set the speed, we use it. There is not way (right now) to force
-  the use of eject, but it will be introduced in a future release. Also one
-  can use the pre_read function to set the speed with other program.
+  option to set the speed, we use it. There is not way (right now) to force the
+  use of eject, but it will be introduced in a future release. Also one can use
+  the pre_read function to set the speed with other program.
 
 New options in 2.1.16:
 
-* -S, CDSPEED and CDSPEEDOPTS for setting the speed of the CDROM. One can 
-  set the options in abcde.conf and pass the value on the command line.
-  This option can be used with "eject -x <speed>", "setcd -x <speed>" or the
-  built-in cdparanoia option "-S <speed>", if the CD reader supports it.
+* -S, CDSPEED and CDSPEEDOPTS for setting the speed of the CDROM. One can set
+  the options in abcde.conf and pass the value on the command line.  This option
+  can be used with "eject -x <speed>", "setcd -x <speed>" or the built-in
+  cdparanoia option "-S <speed>", if the CD reader supports it.
 * Added a pre-read function. Modify it at your pleasure in abcde.conf
   One can use it to close the CD drive.
-* -m option, to modify the playlist to include CRLF in every line. Some 
-  players insist on having those to work properly with playlists.
+* -m option, to modify the playlist to include CRLF in every line. Some players
+  insist on having those to work properly with playlists.
 
 New options in 2.1.15:
 
@@ -113,19 +152,20 @@ Options added/modified from 2.1.1 to 2.1.3:
 
 Options added/modified from 2.0.3 to 2.1.x:
 
-* -b use batch processing. It uses normalize to adjust the volume of the
-  songs, and a -g gapless option from lame to remove gaps. Only available
+* -b use batch processing. It uses normalize-audio to adjust the volume of 
+  the songs, and a -g gapless option from lame to remove gaps. Only available
   for mp3+lame combination.
 * a new "normalize" option has been added to -a, to normalize the volume.
 * -o works now with a combination of the different outputs: ogg, mp3, flac.
   Combine them separated by ",". Example: "-o ogg,flac".
-* OUTPUTTYPE is no longer used for the output file type. From version 2.1
-  abcde implements multiple-output and the file type is always appended at
-  the end of the file. The OUTPUT variable can be used in the 
-  PLAYLISTFORMAT and OUTPUTFORMAT to create different directory structures
-  and playlist names for each of the output formats selected.
-* DYEAR can be used as DiskYear value in CDDB data. If the data is not 
-  supplied by the CDDB server, it can be added.
+* OUTPUTTYPE is no longer used for the output file type. From version 2.1 abcde
+  implements multiple-output and the file type is always appended at the end of
+  the file. The OUTPUT variable can be used in the PLAYLISTFORMAT and
+  OUTPUTFORMAT to create different directory structures and playlist names for
+  each of the output formats selected.
+
+* DYEAR can be used as DiskYear value in CDDB data. If the data is not supplied 
+  by the CDDB server, it can be added.
 
 Other options that changed from 1.x to 2.x:
 
@@ -162,11 +202,13 @@ abcde requires the following backend tools to work:
   You can get a trial version of mp3enc at:
     http://www.iis.fhg.de/amm/download/ or:
 * FLAC encoder (flac) or:
-* Ogg/Speex encoder (speexenc)
-* normalize for volume normalization.
-* CD Paranoia, an audio CD reading utility,
-* Or cdda2wav, the audio CD reading utility cdparanoia was born from,
-* Or dagrab, another audio CD reading utility.
+* Ogg/Speex encoder (speexenc) or:
+* MPP/MP+(Musepack) encoder (mppenc) or:
+* AAC encoder (faac)
+* normalize-audio for volume normalization.
+* CD Paranoia, an audio CD reading utility or:
+* cdda2wav, the audio CD reading utility cdparanoia was born from or:
+* dagrab, another audio CD reading utility.
 * cd-discid, a CDDB DiscID reading program. Formerly bundled with abcde.
   It's available in Debian or http://www.hispalinux.es/~data/files/cd-discid/
 * An HTTP retrieval program: wget, fetch (FreeBSD) or curl (MacOSX)
@@ -175,37 +217,15 @@ abcde requires the following backend tools to work:
 * (optional) distmp3, a client/server for distributed mp3 encoding.
   You can get distmp3 at http://wlug.westbo.se/medlprog/medlprog.html
 
-Potential problems:
-
-Having trouble getting cdparanoia to read from your drive as a user?
-Add yourself to the cdrom group, change the permissions on your cdrom device
-to 660, and if you have a SCSI cdrom drive, check the permissions on
-/dev/sg* as well.
-
-Running out of disk space for .wav files but don't want to use -l? Put them
-in a different location by adding WAVOUTPUTDIR=/some/other/path to your
-/etc/abcde.conf or ~/.abcde.conf.
-
-If abcde seems to be ignoring your configuration options or not running
-commands such as the encoder, you may have misquoted something. Config
-options such as the following do not work:
-
-LAMEOPTS=-h -k
-
-Try this instead:
-
-LAMEOPTS='-h -k'
-
 Abcde's new mailing list is abcde@listas.hispalinux.es. So far has not
 been actively used.
 The posts from non-subscribers are moderated to prevent spam.
 
-Archives of the old list are publically available at:
-http://lly.org/~rcw/abcde/list/current/threads.html
+Abcde's current page is at http://code.google.com/p/abcde/
 
-Abcde's current page is at http://www.hispalinux.es/~data/abcde.php
-Abcde's new homepage will be at http://abcde.hispalinux.es/.
-Abcde's old homepage is at http://lly.org/~rcw/abcde/page/.
 --
-Robert Woodcock <rcw@debian.org>
 Jesus Climent <jesus.climent@hispalinux.es>
+Colin Tuckley <colint@debian.org>
+
+abcde was originally created by Robert Woodcock <rcw@debian.org>
+