## This is the README file for dekagen            Sun Jan 11 19:07:26 CET 2004
## ===========================================================================

dekagen is a front-end to several tools for the ripping, converting, and
naming of MP3 and Ogg-Vorbis files. It automates the whole process of ripping
data from music compact discs (CD), the naming of the files, their converting
into MP3 or Ogg-Vorbis format and the labelling of the MP3 files with an ID3
tag. dekagen uses dialog for a user interface that is intended to be
"intuitive".

Music data is read from CDs using cdda2wav, cdparanoia, dagrab, or tosha, and
stored on your harddisk in wav-format. Note that this will have an excessive
need of disk space. After this, the wav-data is converted into MP3 format
using 8hz-mp3, bladeenc, l3enc, lame, mp3enc, or notlame, or into Ogg-Vorbis
format using oggenc. This will take a while. To avoid manual naming and
tagging for all the files, cda is used for CDDB lookups. To label the MP3
files with ID3 tags, id3ed, id3tag, id3tool, or mp3info, or the built-in
capabilities of some encoders (lame, notlame) are used. Ogg-Vorbis files can
be labelled with oggenc.


# ----------------------------------------------------------------------------
# Be sure you have already installed on your system:

1. cdda2wav, cdparanoia, dagrab, or tosha,
2. 8hz-mp3, bladeenc, l3enc, lame, mp3enc, or notlame,
   or oggenc.
You might also wish to install:
3. xmcd,
4. id3ed, id3tag, id3tool, or mp3info.

� cdda2wav is available under GNU GPL at
  http://www.escape.de/users/colossus/cdda2wav.html
� cdparanoia is available under GNU GPL at http://www.xiph.org/paranoia/
� dagrab is available in two flavours, both under GNU GPL, at
  http://web.tiscali.it/marcellou/dagrab.html or
  http://vertigo.fme.vutbr.cz/~stibor/dagrab.html
� bladeenc is available under GNU LGPL at http://bladeenc.mp3.no/
� lame is available under GNU LGPL at http://www.mp3dev.org/
� notlame is available under GNU LGPL at
  http://www.idiap.ch/~sanders/not_lame/
� oggenc is available under GNU GPL at http://www.vorbis.com/download_unix.psp
� xmcd is available under GNU GPL at http://www.amb.org/xmcd/
� id3ed is available under GNU GPL at
  http://www.azstarnet.com/~donut/programs/id3ed.html
� id3tag is available under GNU LGPL at http://id3lib.sourceforge.net/
� id3tool is available under GNU GPL at http://kitsumi.xware.cx/id3tool/
� mp3info is available under GNU GPL at http://www.ibiblio.org/mp3info/

You will find oggenc included in the "vorbis-tools" package, cda in the "xmcd"
package, and id3tag in the "id3lib" (or "id3lib-examples" on RPM-based
systems) package.
Please note that some rippers have to be run suid root.
ID3 tagging utilities are not needed when using lame or notlame, because
these programs have a built-in ID3 tagging, and cannot be used together with
oggenc, because Ogg-Vorbis has its own tagging system.

dekagen was developed and tested under Linux with the programs mentioned
above, but it should work on other UNIX-like platforms as well (in particular
on FreeBSD), provided that all required programs (at least a bourne-compatible
shell, "dialog", a ripper, and an encoder) are available.

dekagen has been tested with dialog v.0.6, available under GNU GPL at
http://www.ibiblio.org/pub/Linux/utils/shell/. It should work, however, also
with "cdialog", or dialog v.0.9.


# ----------------------------------------------------------------------------
# Published under the terms of the GNU General Public License.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.


# ----------------------------------------------------------------------------
# Download locations:

The latest version of dekagen can be found at:

	http://userpage.fu-berlin.de/~mbayer/tools/dekagen.html
or
	[ftp|http]://ftp.ibiblio.org/pub/linux/apps/sound/convert/

If you are going to retrieve the source code from within automated scripts,
e.g. by a software packaging manager, please prefer downloading it from the
Ibiblio server or one of its mirrors.


# ----------------------------------------------------------------------------
# Be aware of legal restrictions:

In some countries, the use of MP3-generating algorithms may be subject to
licence restrictions. Please check the documentation of your encoding tool
or consider the use of Ogg-Vorbis instead of MP3.


# ----------------------------------------------------------------------------
# Be aware of the following changes in Version 0.8:

When aborting the program with <CTRL>+C, or <ESC>, or selecting the 'Cancel'
item in the main dialogue, background encoding activities will be terminated.
Only if the program is left with the 'quit' menu item, the user will be asked
whether he wishes to abort background encoding processes or not. In the latter
case the background encodings and ID3 labellings will proceed normally.


# ----------------------------------------------------------------------------
# The name changed with version 0.9:

dekagen was formerly published under the name "ripenc". This tool was
maintained up to version 0.7 by Michael J. Parmeley. Since in 2000 it seemed
as if he had given up its development, I re-published it after considerable
changes under the version number 0.8.X. After he had re-appeared on the net,
he refused to apply the changes of my 0.8-releases to his program core. But
then he published an other release of "ripenc", based on version 0.7, that
included a lot of the code-cleaning I made, except for the "dialog"-based user
interface. Since as a consequence two different programs with the same name,
but different interfaces existed, I decided to rename the ripenc-series with
the "dialog"-interface (versions 0.8.X) to "dekagen" (version 0.9 and newer).


# ----------------------------------------------------------------------------
# New auto-configuring features in version 1.0:

If you run dekagen for the first time, it will look for the third-party
software it requires automatically, setting its preferences accordingly.
After this, dekagen will check these settings on every run, and adjust them
automatically if needed.

This search will proceed according to a built-in order. If you are an
administrator and going to install dekagen system-wide, you can pre-set
the defaults in the lines 36-49 of the script. dekagen will then look for
these programs first. Otherwise there is no need to change these values.


# ----------------------------------------------------------------------------
# Prospects for the next version:

� Drop support for 8hz-mp3, l3enc, mp3enc, and tosha?

� Bladeenc is not being developed any more. If we droped support for it, too,
  we could do without any external ID3 tool, using the built-in tagging
  capabilities of lame, notlame, and oggenc.

� Quality level settings (for lame, notlame, and oggenc) as an alternative to
  (nominal) bitrate settings?

� Use dagrab for retrieving CDDB data as an alternative to xmcd (cda)?

� Add support for lossless compression algorithms, like MPEG-4 ALS
  (http://www.nue.tu-berlin.de/forschung/projekte/lossless/mpeg4als.html),
  formerly known as LPAC, and/or FLAC (http://flac.sourceforge.net/)?

� Make pre-set defaults (lines 36-49) a system-wide configuration file, e.g.
  /etc/dekagenrc?

Suggestions and comments are welcome.


# ----------------------------------------------------------------------------
# �We accept patches.�

Please include in all your messages information on
	� the version of dekagen you are referring to (`dekagen --version`),
	� name and version of your operating system (`uname -a`),
	� name and version of your shell (e.g. `bash --version`) and
	  other third-party-software (like cda) related to your problem.

If you think you found a possible security impact, please let _me_ know
_first_.

If you think you found a bug, please try to describe it as exactly as
possible, in order to save other people's time. I will not consider any "bug
report" that just claims "your program is buggy!!!!!1", nor will I answer to
any mail asking me OS-specific questions.

I will include into the TODO list any sensible feature request.

And, last but not least, patches are always very welcome. :-)


Martin Bayer <mbayer@zedat.fu-berlin.de>

	For all e-mails, use of PGP (GPG) is encouraged. You will find my
	public key (ID: 0xCB537B60) on my homepage and on keyservers. The key's
	fingerprint is: "46A1 B556 41CD C77A 0261  D22F 41A6 EB90 CB53 7B60".