/*
** aacgain - modifications to mp3gain to support mp4/m4a files
** Copyright (C) 2004-2007 David Lasker, Altos Design, Inc.
**
** 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
**/

AACGAIN VERSION 1.7

AACgain is a modification to Glen Sawyer's mp3gain, to support AAC 
(mp4/m4a/QuickTime) files as well as mp3 files. If you are not familiar with
mp3gain, stop reading this, and go to http://mp3gain.sourceforge.net

USAGE NOTES

1. BACK UP YOUR MUSIC FILES BEFORE USING AACGAIN! THIS IS EXPERIMENTAL 
   SOFTWARE. THERE HAVE BEEN BUGS IN PAST RELEASES THAT CORRUPTED MUSIC
   FILES. I AM NOT RESPONSIBLE FOR DAMAGED FILES.
2. AACGain supports files in the mp4/Quicktime file format. These files
   usually have a file extension of .mp4 or .m4a. Raw AAC files, or
   files encoded with HE-AAC/SBR are not supported.
3. DRM'ed files purchased from the iTunes music store are not supported. You
   may convert these to .m4a format by burning them to a CD-ROM and importing
   them back into iTunes, or by using one of the underground methods to
   losslessly convert them to .m4a.
4. AACGain takes the same command line options as mp3gain - no
   changes have been made to the command usage.
5. If you rename the AACGain.exe executable to mp3gain.exe, it will work 
   with the Visual Basic front-end MP3GainGUI.exe.
6. When calculating or applying album gain, you may mix aac and mp3 files
   in the same command.
7. The /t (use temp file) option is ignored for aac files. A temp file
   is always used. The mpeg4ip/mp4v2 Optimize function is used to copy the
   processed file back to the original name. Experience has shown that this
   is required for processed music files to play on the iPod Shuffle.
8. The /w (wrap) flag is ignored for aac files, since allowing an aac file
   to wrap will leave it in an unplayable state.
9. The /f (assume input file is an MPEG 2 Layer III) option is ignored
   for AAC files. If a file starts with a 'ftyp' atom, it is assumed to be
   AAC, even if /f was specified.
10. The following metadata tags will be added to your files:
     - replaygain_track_gain
     - replaygain_album_gain
     - replaygain_track_peak
     - replaygain_album_peak
     - replaygain_track_minmax
     - replaygain_album_minmax
     - replaygain_undo
    These are all free-form metadata tags (moov.udta.meta.ilst.----)
    with 'data' text fields in the same format as the mp3gain
    equivalents. You may use AtomicParsley (download from sourceforge)
    to view the tags.
    
WHAT'S NEW IN VERSION 1.7
a) If the total length of the directory plus file name path exceeded
   64 bytes, memory corruption would occur. This has been corrected.

WHAT'S NEW IN VERSION 1.6
a) Files with a 'cprt' (copyright) tag are now processed correctly.
   Previous versions of aacgain corrupted the metadata of files with a
   copyright tag.
b) AACGain now works on video or other files where the first audio track 
   has a track number of other than 1. Previous versions required the
   audio track to have a number of 1. AACGain will still only process
   the first audio track found on a file. Thanks to Arthur Yarwood at
   Sony Computer Entertainment Europe for this fix.

WHAT'S NEW IN VERSION 1.5
a) Running AACGain on Apple lossless or other unsupported file format 
   resulted in a crash with an unhandled exception. This is now fixed.

WHAT'S NEW IN VERSION 1.4
a) Temporary files are created in the same directory as the input file.
   Formerly they were created in the same directory that the program was run
   in. This solves a problem only seen on Unix systems where the temporary 
   file could not be renamed back to the original input filename, if the 
   input file was located on a different filesystem from where the program 
   was run. Windows users are unaffected by this problem and can continue to
   use 1.3.

WHAT'S NEW IN VERSION 1.3
a) Always uses the /t (use temp file) option, even if it is not specified
   on the command line. This resolves issues where processed files would
   not play on the iPod Shuffle.
b) Preserves original values of MP4 properties bufferSizeDB, maxBitrate and 
   avgBitrate. Without this change, mpeg4ip/mp4vs was recalulating the
   actual values of these parameters. This caused bitrate as displayed by
   iTunes to change slightly, i.e. songs ripped at 320KB would display as
   319KB.
c) Incorporates recent changes to mp3gain which prevent crashes when
   working with 48KB files on Linux.
d) Source code directory structure was reorganized to be compatible with mp3gain 
   CVS on sourceforge. Thanks to Glen Sawyer, the AACGain source code is now 
   hosted on sourceforge's CVS repository as part of the mp3gain project.

WHAT'S NEW IN VERSION 1.2
a) Fixes compatibility issue with MP3GainGUI version 1.2.5 or 1.3.4.
b) All temporary files created are erased.
   
WHAT'S NEW IN VERSION 1.1
a) Multi-channel and mono files now work.
b) Fixes compatibility issues with MP3GainGUI:
   - /o option always outputs Album gain
c) /f option is ignored for AAC files - see usage notes below.
d) Uses portable versions of all library functions, and has been
   successfully compiled under Linux. Thanks to Prakash Punnoor
   for his help with this.
   
BUILDING AACGAIN FOR WINDOWS FROM SOURCE CODE

I created AACGain using MSVC++.NET 2003. Thanks to Glen Sawyer for 
converting the .sln/.vcproj files to .dsw/.dsp. Thanks to Prakash Punoor, 
the source code is portable, and has been compiled under Linux.

In order to build AACGain from source code, the following components are 
required. You may download them from the links listed below:

a) aacgain

   Thanks to Glen Sawyer, aacgain source code is checked into the sourceforge
   CVS repository as part of the mp3gain project. A CVS client is required.
   See the instructions at http://sourceforge.net/cvs/?group_id=49979. The
   commands to check out the aacgain source code are:
   cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mp3gain login 

   cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mp3gain co -P aacgain

b) mp3gain
   You must check out the source code from sourceforge's CVS repository. A CVS
   client is required. The zipped source code files available for download
   from http://mp3gain.sourceforge.net/download.php is currently at version 
   1.4.6 and is not compatible with AACGain source code. When version 1.4.7 
   is released, use of CVS will no longer be required. The commands to check 
   out the mp3gain source code are:
   cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mp3gain login 

   cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mp3gain co -P mp3gain
   
c) faad2 
   Download the latest "FAAD2 CVS snapshot 15-09-2004" from
   http://www.audiocoding.com/modules/mydownloads/ AACGain is based on FAAD2 
   as of Sept. 15, 2004. Since AACGain was developed, FAAD2 version 2.5 has
   been released. I have not tried this version, since the previous version
   meets my needs. If you want to try version 2.5, make sure the code
   in aacgain/decoder.c and aacgain/syntax.c, which contains replacements
   for the corresponding faad2 code, is still correct for the latest version.
   
d) mpeg4ip
   Checkout mpeg4ip version 1.5.20 or later from CVS at 
   http://sourceforge.net/cvs/?group_id=18676. The cvs checkout commands are:
   cvs -d:pserver:anonymous@mpeg4ip.cvs.sourceforge.net:/cvsroot/mpeg4ip login
   cvs -z3 -d:pserver:anonymous@mpeg4ip.cvs.sourceforge.net:/cvsroot/mpeg4ip co -P mpeg4ip
    
   Do NOT download the official mpeg4ip version 1.5.0.1. The fix for the
   'cprt' bug in AACGain 1.6 requires mpeg4ip version 1.5.5 or later, which
   has not yet been officially released. I am recommending you use version
   1.5.20 because that is what I used to build AACGain 1.7. Unfortunately 
   the mpeg4ip developers do not tag their internal versions, so the best
   way to checkout a version identical to the one I used is to use 
   the CVS co -D option with a date of 20070402.
   
The components must be arranged in the following directory hierarchy:
-- aacgain containing aacgain.dsw/.sln, aacgain.dsp/.vcproj and source files
-- faad2 (create this directory and extract the faad2 archive into it)
   -- include
   -- libfaad containing libfaad.dsp
      -- codebook
      -- fftw
   other directories are not used and can be pruned if desired
-- mpeg4ip
   -- include
   -- lib
      -- mp4v2 containing libmp4v2.vcproj
         -- util
      -- gnu containing libmissing.vcproj
   other directories are not used and can be pruned if desired
-- mp3gain
   -- mpglibDBL
      
AACGain releases prior to 1.6 required applying a patch to mpeg4ip version
1.2. No patches are necessary, now that we have upgraded to a later mp4v2
release.

Both .dsw/.dsp and .sln/.vcproj files are provided for use with MSVC++6
or later. But since I can only test with MSVC++2003, use the .dsw/.dsp files
at your own risk. I know for sure that the .dsp files packaged with
mpeg4ip/mp4v2 are out of date.

Files mpeg4ip/lib/mp4v2/libmp4v2.vcproj and 
mpeg4ip/lib/gnu/libmissing.vcproj are for MSVC++ 2005 (8.0). If you are
like me, and too poor to have the latest MSVC++ version, you can use these files
with MSVC++2003 by opening each file with a text editor and changing the 
line:
    Version="8.00"
to
    Version="7.10"

Open aacgain/aacgain.sln or aacgain/aacgain.dsw. There should be 5 projects
in your workspace/solution:
1. aacgain
2. libfaad
3. libmissing
4. libmp4v2
5. mp3gainlib

Make the following changes to the libfaad project properties:
a) Change the C++/Code generation/Runtime Library property for libfaad to
   "Single-threaded Debug (/MLd)" for debug build and "Single-threaded (/ML)"
   for release build. 
b) Change the Librarian/Ignore All Default Libraries property to 
   "Yes (/NODEFAULTLIB)" for both debug and release builds.

Make the following changes to both libmp4v2 and libmissing projects:
a) Change the C++/Code generation/Runtime Library property for libfaad to
   "Single-threaded Debug (/MLd)" for debug build and "Single-threaded (/ML)"
   for release build. 
b) Change the C++/General/Additional Include Directories property
   to "..\..\include"
c) Change the C++/General/Debug Information Format property to
   "Program Database (Zi)".
d) If you are using MSVC++6.0, the mpeg4ip .dsp files have not been kept up to
   date.You will need to add files virtual_io.cpp and virtual_io.h to libmp4v2,
   and change the character set to Unicode (define _UNICODE) in both 
   libmp4v2 and libmissing.
   
At this point, you may press F7 and cross your fingers:-)

BUILDING AACGAIN FOR UNIX (LINUX/MAC OS X) FROM SOURCE CODE

I am a windows-only programmer, so I can not vouch for or answer
questions on the following, which was supplied by other AACGAIN
users:

Obtain the source code, and set up the directories, as described above
for the Windows build. Expand the archive file unix_build_system.tar.bz2 
that is checked into aacgain's CVS repository.

Due to my overriding classes in mpeg4ip/mp4v2, it is not possible
to dynamically link libmp4v2. It must be statically linked.

Users building with mpeg4ip/mp4v2 version 1.5 report compile errors
in mpeg4ip.h due to redefinition of struct iovec. This can be corrected
either by deleting the struct from the header file, or else #define
the symbol HAVE_STRUCT_IOVEC.

HOW AACGAIN WORKS

mpeg4ip/lib/mp4v2 is used to parse the mp4/QuickTime file format, to
read individual samples so that they can be passed to faad2, and to
read and write metadata tags.

faad2 is used to de-compress and decode the aac frames into linear 
PCM for analysis by the replaygain algorithm.

Files syntax.c and decoder.c are slightly modified versions of the
corresponding files from faad2. The modifications allow the positions
and original values of the global_gain fields to be saved.

File MP4MetaFile.cpp subclasses mp4v2 class MP4File. Additional functionality
was added in MP4MetaFile to modify the global_gain fields within a frame, and
to optimize the resulting file in the same order as iTunes.

aacgain.cpp is a wrapper for the above functionality.

mp3gain.c has been modified to call aacgain when the symbol AACGAIN is
defined. The version mp3gain.c checked into sourceforge's cvs repository
has this modification included.

ACKNOWLEDGEMENTS

I am a total newbie to digital audio, and I created AACGain primarily
as a learning exercise. I couldn't have done it without the help of others:

1. Thanks to the user community at hydrogenaudio.org and audiocoding.com,
   especially Menno and Hans-Jrgen.
2. Thanks to Bill May for helping me get started with mpeg4ip.
3. Thanks to Prakash Punnoor, Hardloaf, Ben Allison, and Miguel Angel Alvarez
   for their help with Linux and Mac.
4. Last, but not least, thanks to Glen Sawyer for creating mp3gain.

Dave Lasker
dave@altosdesign.com
April 14, 2005
