<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book>
<bookinfo>
    <title>mp32dao documentation</title>
    <authorgroup>
       <author>
	 	<surname>Corbelli</surname>
	 	<firstname>Giuseppe</firstname>
       </author>
       <author>
	 	<surname>Steward</surname>
	 	<firstname>Joe</firstname>
       </author>
	</authorgroup>
	<legalnotice><para>Everything is under GPL.
	</para></legalnotice>
</bookinfo>		
<toc></toc>
<preface><title>What is it?</title>
<para>
<productname>mp32dao</> is a simple <productname>perl</> script designed to help you in
the task of creating audio CDs from MP3/Ogg/Flac files. It will decode compressed audio files to wav and create
a <emphasis>TOC</> file suitable for burning with <productname>cdrdao</>.
</para>
</preface>

<chapter id="authors"><title>Authors</title>
<sect1><title>The beginning and nowadays</>
<para>
	The creator of mp32dao is <emphasis>Joe Steward</>. He had the idea of track padding.
	It seems he's not maintaining mp32dao anymore, or at least I'm unable to contact him.
</para>
<para>
	My name is <emphasis>Giuseppe Corbelli</> but I bet you saw it on the very first page
	of this document ;-). I made some hacking on the original program adding CD-Text and Ogg
	decoding, and reworking all the script. The original track padding code is still here.
	You should not think of finding a good programming example, though :-).
	You can contact me at <email>cowo@lugbs.linux.it</>.
</para>
</sect1>
</chapter>

<chapter id="features"><title>Features</title>
<sect1><title>Why you'll love mp32dao</>
<para>
	Suppose you have downloaded a bunch of mp3/ogg/flac files. Suppose you want to burn them on a
	CD, without those annoying clicks between the tracks and with CD-Text support. This is
	why you're going to use mp32dao.
</para>
<para>
	Samples from the ending of a track are padded together with the beginning of the next to
	avoid leaving a CD sector half-filled with zeroes. You can avoid clicks between tracks this
	way.
</para>
<para>
	By using tags in the compressed source files (e.g. ALBUM, AUTHOR, TITLE) mp32dao will generate a toc-file with CD-Text info
	ready to use with cdrdao. If all the source files do not have the same AUTHOR and ALBUM tags the resulting toc
	will show "Compilation" as title, and "Various Artists" as author.
	Cdtext support requires the ALBUM, TITLE and ARTIST tags in all the source files.
</para>
</sect1>
</chapter>

<chapter id="installation"><title>Installation</title>
<sect1><title>Requirements</>
<para>
In order to be able to use <productname>mp32dao</> you must have,
installed and working, the following software on your system:
<variablelist>
<varlistentry><term>Perl interpreter</>
	<listitem><para>
	I currently use:
	<programlisting>
Summary of my perl5 (revision 5.0 version 6 subversion 0) configuration:
  Platform:
    osname=linux, osvers=2.4.9-xfs, archname=i686-linux
    uname='linux braveheart.cowo.net 2.4.9-xfs #5 
    	\mar ago 21 23:12:16 edt 2001 i686 unknown '
    config_args=''
    hint=recommended, useposix=true, d_sigaction=define
    usethreads=undef use5005threads=undef 
    	\useithreads=undef usemultiplicity=undef
    useperlio=undef d_sfio=undef uselargefiles=define 
    use64bitint=undef use64bitall=undef 
    	\uselongdouble=undef usesocks=undef
</programlisting> 
		and it works for me. Please note I compiled Perl myself, disabling thread support.
	</para></listitem>
</varlistentry>
<varlistentry><term>MP3::Info Perl Module</>
<listitem><para>
	It is used to access MP3 informations such as playing length, ID3 tags and more.
</para></listitem>
</varlistentry>
<varlistentry><term>Ogg::Vorbis Perl Module</>
<listitem><para>
	It is used to access Ogg informations such as playing length, comments and more.
</para></listitem>
</varlistentry>
<varlistentry><term>Audio::Wav Perl Module</>
<listitem><para>
	It is used to access Wav file information such as length.
</para></listitem>
</varlistentry>
<varlistentry><term>Audio::Tools::Time Perl Module</>
<listitem><para>
	Almost the same as above.
</para></listitem>
</varlistentry>
<varlistentry><term>FindBin Perl Module</>
<listitem><para>
	It is used to fetch mp32dao.pl location, searching for modules here. You should already have it.
</para></listitem>
</varlistentry>
<varlistentry><term>Cwd Perl Module</>
<listitem><para>
	It is used to fetch current working directory. You should already have it.
</para></listitem>
</varlistentry>
<varlistentry><term>mp3handler.pm, ogghandler.pm, flachandler.pm, MediaHandler.pm, Baseinfo.pm Perl Modules</>
<listitem><para>
	They are part of <productname>mp32dao</> distribution. Leave them in the same directory where mp32dao.pl is or install them
	in the perl search path.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1><title>Installation</title>
<para>You can put the main program file, <computeroutput>mp32dao.pl</> anywhere you like. But it expets to find its components
in the <productname>perl</> search path or in its same directory. The needed components are:
<itemizedlist>
<listitem><screen>ogghandler.pm</></listitem>
<listitem><screen>mp3handler.pm</></listitem>
<listitem><screen>flachandler.pm</></listitem>
<listitem><screen>MediaHandler.pm</></listitem>
<listitem><screen>BaseInfo.pm</></listitem>
</itemizedlist>
</para>
</sect1>
</chapter>
<chapter id="usage"><title>Usage</>
<sect1><title>Command line options</>
<para>The usage is fairly straightforward:
	<orderedlist>
		<listitem><para>put all and only the mp3 and/or ogg and/or flac files you want on the CD in a single directory.
		</para></listitem>
		<listitem><para>change to this directory
		</para></listitem>
		<listitem><para>launch mp32dao.pl [tocfile]. If you specify a tocfile it will be used to write the
			file .toc used by cdrdao. If you don't <filename>cd.toc</> will be used. Other arguments are ignored.
		</para></listitem>
	</orderedlist>
	The script should work with all filenames but you'll live happier if you don't name your files like this:
	<screen>Iced % Earth - Burning ^ Times - [01].mp3</screen>
	Avoid stupid naming schemes.
	Please note the program will compose the CD using the files in the same order as their name suggests.
	I <emphasis>strongly</> advise you to put the tracknumber at the beginning of the filename.
	Example:
	<screen>
01-The_Quickening.mp3
02-Heart_Of_Storm.mp3
03-Sworn_In_The_Metal_Wind.mp3
04-The_Song_Of_Air.mp3
05-World_Through_My_Fateless_Eyes.mp3
	</screen>
</para>
</sect1>
</chapter>
<chapter id="internals"><title>Internals</>
<sect1><title>Program structure</title>
<para>The Mediahandler constructor takes as input a directory name, scans for all supported
media files, and returns a list containing handlers for all common operations, such as wav decoding,
information access etc. This info is collected by the three lower level modules mp3handler, ogghandler and flachandler
using MP3::Info, Ogg::Vorbis and system program metaflac. The main program builds the TOC. In the distribution you will find
a simple <productname>UML</> diagram which should make it somewhat clearer.
</para>
</sect1>
</chapter>
<chapter id="future"><title>The future</>
<sect1><title>Next release plans</>
<para>
	<variablelist>
		<varlistentry><term>On-the-fly decoding</term>
		<listitem><para>
			No more huge wav files. It should be possible to do the decoding
			on the fly using a FIFO.
		</para></listitem>
		</varlistentry>
		<varlistentry><term>GUI</term>
		<listitem><para>
			Some GUIs using Perl/Tk and/or Perl/GTK.
		</para></listitem>
		</varlistentry>
		<varlistentry><term>Binary</term>
		<listitem><para>
			Compile the script to have it available in binary form.
		</para></listitem>
		</varlistentry>
	</variablelist>
</para>
</sect1>
</chapter>
<chapter id="troubleshooting"><title>Troubleshooting</>
<sect1><title>segfaults and nasty bugs here</>
	<para>There's no point in writing such a section since I develop high quality software :-)).
	</para>
</sect1>
</chapter>
<chapter id="developing"><title>Developing</>
<sect1><title>Wanna help me?</>
	<para>I'm working on mp32dao alone. I always need help and knowledge. Please drop me a mail at
		<email>cowo@lugbs.linux.it</>
	</para>
</sect1>
</chapter>
</book>
