<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.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 files. It will decode MP3 files to Wav and create
a <emphasis>TOC</> file suitable for <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 support
	and internal mp3 decoding. I also added some more checks and rewrote all the stuff to
	improve readability and modularity. 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 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 ID3 tags such as ALBUM, AUTHOR, TITLE mp32dao will generate a toc-file with CD-Text info
	ready to use with cdrdao. Please take care that all MP3 files have the same AUTHOR and ALBUM ID3 fields.
	If don't mp32dao will name the album "mp3 compilation" and author "VV.AA". Of course this does not apply
	if you are really creating a compilation. No ID3s mean no CD-Text support.
</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, on your system the following software:
<variablelist>
<varlistentry><term>Perl interpreter</>
	<listitem><para>
	I currently use:
	<programlisting>
[cowo@braveheart mp32dao]$ perl -V
Summary of my perl5 (revision 5.0 version 6 subversion 0) configuration:
  Platform:
    osname=linux, osvers=2.2.18, archname=i686-linux
    uname='linux braveheart 2.2.18 #3 
      tue feb 6 08:32:20 cet 2001 i686 unknown '
    config_args=''
    hint=previous, useposix=true, d_sigaction=define
    usethreads=undef use5005threads=undef 
      useithreads=undef usemultiplicity=undef 
      useperlio=undef d_sfio=undef uselargefiles=undef 
      use64bitint=undef use64bitall=undef 
      uselongdouble=undef usesocks=undef
  Compiler:
    cc='cc', optimize='-O3 -fomit-frame-pointer 
      -mpentiumpro -march=pentiumpro -malign-functions=4 
      -funroll-loops -fexpensive-optimizations -malign-double 
      -fschedule-insns2 -mwide-multiply', 
      gccversion=2.95.3 19991030 (prerelease)
    cppflags='-fno-strict-aliasing -I/usr/local/include'
    ccflags ='-fno-strict-aliasing -I/usr/local/include'
    stdchar='char', d_stdstdio=define, usevfork=false
    intsize=4, longsize=4, ptrsize=4, doublesize=8
    d_longlong=define, longlongsize=8, d_longdbl=define, 
      longdblsize=12
    ivtype='long', ivsize=4, nvtype='double', nvsize=8, 
      Off_t='off_t', lseeksize=4
    alignbytes=4, usemymalloc=n, prototype=define
  Linker and Libraries:
    ld='cc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib
    libs=-lnsl -lgdbm -lpthread -ldl -lm -lc -lcrypt
    libc=/lib/libc-2.1.92.so, so=so, useshrplib=true,
      libperl=libperl.so
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, 
      ccdlflags='-rdynamic -Wl,-rpath,
      /usr/lib/perl5/5.6.0/i686-linux/CORE'
    cccdlflags='-fpic', lddlflags='-shared -L/usr/local/lib'


Characteristics of this binary (from libperl): 
  Compile-time options:
  Built under linux
  Compiled at Feb  7 2001 14:50:21
  @INC:
    /usr/lib/perl5/5.6.0/i686-linux
    /usr/lib/perl5/5.6.0
    /usr/lib/perl5/site_perl/5.6.0/i686-linux
    /usr/lib/perl5/site_perl/5.6.0
    /usr/lib/perl5/site_perl
    .
</programlisting> 
		and it works for me. Please note I compiled Perl myself, disabling thread support.
		You may get into trouble if you want to use internal mp3 decoding coupled with a threaded Perl
		distribution. This will be made clear later.
	</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>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>mp3handler Perl Module</>
<listitem><para>
	Contains the object I use for MP3 handling. You may find it useful yourself.
	You can find it along with mp32dao. If you plan to install mp32dao system-wide you
	must put it somewhere in the perl search path. Or leave it in the same directory
	where you unpacked mp32dao.
</para></listitem>
</varlistentry>
<varlistentry><term>mp3dec Perl Module</>
<listitem><para>
	This module will be used to handle mp3 decoding internally, using libmpeg3 and libsndfile. It
	is not absolutely necessary; an external decoding program can be used such as lame or madplay.
	It will be used only if available.
	You can create this module yourself by using <ulink url="http://www.swig.org">SWIG</ulink>,
	following these steps:
	<orderedlist>
	<listitem><para>
		compile <filename>mp3dec.c</>, for example using 
			<screen>gcc -fPIC -D_REENTRANT -c mp3dec.c
			</screen>
		You will obtain <filename>mp3dec.o</>. This is a stupid console program
		which exports a function used to decode mp3 files to wav files.
	</para></listitem>
	<listitem><para>
		generate perl wrapper using SWIG:
		 <screen>swig -perl5 mp3dec.i</screen>
		You will obtain files <filename>mp3dec_wrap.c</> and <filename>mp3dec.pm</>. The first will
		be used by perl to access function exported by mp3dec.c, the second is the one to include in perl code.
		<note><para>If you are using threaded perl SWIG won't work! (at least for me). Please use a no-threads
			perl build.
		</para></note>
	</para></listitem>
	<listitem><para>
		compile SWIG-generated wrapper:
		<screen>
			gcc -fPIC -c -Dbool=char -I /usr/lib/perl5/5.6.0/i686-linux mp3dec_wrap.c
		</screen>
		Of course the include option should match the right one for your system. On Redhat Linux systems
		it is usually <filename class="directory">/usr/lib/perl5/5.6.0/i386-linux</> on Intel machines.
	</para></listitem>
	<listitem><para>
		create the shared library that will be loaded by Dynaloader:
		<screen>
			gcc -shared mp3dec_wrap.o mp3dec.o -o mp3dec.so -lm -lpthread -lmpeg3 -lsndfile
		</screen>
		Ok, as you can see there are some external libraries needed; libmpeg3 and libsndfile which
		you'll find on freshmeat.net. libm and libpthread are standard on glibc2 systems, I don't
		have access to others, sorry. Then you must copy the resulting <filename>mp3dec.so</> somewhere
		in the perl search path.
	</para></listitem>
	</orderedlist>
</para></listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1><title>Compiling and installing</title>
<para>If you have SWIG, libpthread, libmpeg3 and libsndfile already installed you may use internal
mp3 decoding module. Otherwise you must have an external mp3 decoding software available.
There are no particular differences, but internal decoding gives a better feeling :-)).
</para>
	<sect2><title>Internal Decoding</>
	<para>
		Edit the supplied <filename>Makefile</> to fit your system's configuration. Then type
		<computeroutput>make</> and <computeroutput>make install</>.
	</para>
	</sect2>
	<sect2><title>External Decoding</>
	<para>
		You must have an external command-line mp3 decoder installed. Then edit <filename>mp32dao.pl</>,
		find the line <computeroutput>my $external_mp3decoder = 'lame --decode --mp3input';</> and
		change the programname and options to suit your needs. Please note that the external program
		must take a command-line like this <computeroutput>programname [OPTIONS] input.mp3 output.wav</>
		to work with mp32dao.
		You can leave mp32dao anywhere you like but take care that <filename>mp3handler.pm</> is in its
		same directory or somewhere in the perl search path.
	</para>
	</sect2>
</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 mp3files 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_Ghosts_Of_Christmas_Eve.mp3
02-Boughs_Of_Holly.mp3
03-The_World_That_She_Sees.mp3
04-Midnight_Christmas_Eve.mp3
05-The_March_Of_The_Kings-Hark_The_Herald_Angel.mp3
	</screen>
</para>
</sect1>
</chapter>
<chapter id="internals"><title>Internals</>
<sect1><title>Program structure</title>
<para>Still to be written. But take a look at the code, it should be clear enough.
</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>Packaging, documentation</term>
		<listitem><para>
			Decent packaging with makemake support and readable documentation.
		</para></listitem>
		</varlistentry>
		<varlistentry><term>Ogg support</term>
		<listitem><para>
			Support for ogg files is on the way, don't worry :-).
		</para></listitem>
		</varlistentry>
		<varlistentry><term>Better internal decoding module</term>
		<listitem><para>
			Ah, you saw how it sucks? :-) It's only a quick hack over libmpeg3.
			It should be much better, but sometimes it works :-)
		</para></listitem>
		</varlistentry>
	</variablelist>
</para>
</sect1>
<sect1><title>Sooner or later</>
<para>I'd like to couple the internal decoding module with a threaded perl. It won't probably
	speed up things much but will give a <emphasis>definite</> good feeling :-).
	Up till now SWIG and threaded perl don't work together. Seems we have to wait.
</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>