EQ - A graphic equalizer plugin for XMMS (C) 2002-2004 Felipe Rivera
			<liebremx at users.sourceforge.net>

  Disclaimer
  ==========
  This piece of software is provided AS IS without any implicit or explicit 
  warranties.
  If you use it is under your own risk.
  The authors are not liable for any damage caused by the use of this piece
  of software

  Aknowledgements
  ===============
  See the file 'AUTHORS'

  Introduction
  ============
  EQ is a graphic equalizer effect plugin for XMMS that equalizes almost
  everything that XMMS reproduces, not just MP3s. 
  This means that your OGG, WAV, etc. files will be also equalized.
  The almost depends on the audio characteristics of the file being reproduced like
  sampling frequency and bits per sample.
  For most of the played files there won't be any problems.
  
  Supported sampling frequencies
  ------------------------------
    48KHz, 44.1KHz, 22.05KHz, 11.025KHz
    
  Supported number of channels
  ----------------------------
    Mono and stereo

  Bands
  -----
  - Five different equalizer modes (configurable):

        Number of 	Bandwidth 	Central frequencies
	bands		(in octaves)
	--------	------------	-------------------
	10		1		XMMS original ones
  	10		1			ISO
	15		2/3			ISO
	25		1/3	                ISO	
	31		1/3			ISO
  
    More than +-14dB of gain per band and a +12dB/-12dB preamp

  GUI
  -------------
  - Skin support (by Simone Lehmann)
  - Shadowed mode (by Simone Lehmann again)
  - Independent gain settings for left and right channels (configurable)
  - Floating point implementation of the equalizer core routines

    NOTE: When reproducing audio with sample rates equal to 22.05KHz or 11.025KHz
          the equalizer automatically forces the equalizer to be 10bands and with
          the upper frequencies changed from the usual ones to take into account
          the fact that the frequencies found in the reproduced audio have been
          cut below 11.025KHz and 5.512KHz respectively.
          See src/iir_cf.h to check these frequencies

  The latest version should be available from

	http://equ.sourceforge.net/

  Requirements
  ============

  CPU
  ---
    Any platform where XMMS runs on should be able to compile and execute the 
    plugin.
    Please report in what platform you are running the plugin other than Linux 
	for x86 to add it here.
  
    This code is CPU intensive, so the newer and faster the processor is the
  	better for you.
    The CPU usage is at a maximum when using 31 bands and the "Extra filtering"
    setting is ON.
    I would like to hear about the CPU characteristics of your box if you
	were not able to run the plugin 'comfortably'.
  
  Frank Klemm provided the following information:

  > CPUs which are able to equalize in realtime and which aren't support SSE
  >are:
  >                                                                              
  > K6-2                 (266...550 MHz)                 3DNow!
  > K6-III               (400, 450 MHz)                  3DNow!
  > Athlon (non XP)      (500...1400 MHz)                3DNow!
  > Pentium II           (ca. 350...450 MHz)             No FPU-SSE available

  Software
  --------
  If you plan to compile from source you need the following
  - A C compiler (GCC will do)
  - Headers and libraries for
    gtk+ >= 1.2.7
    glib >= 1.2.7
    xmms >= 1.2.7

  If you got a precompiled package then you just need XMMS >= 1.2.7

  The plugin DOESN'T compile with XMMS 1.2.5 but it may work on 1.2.6.
  This code was developed using XMMS 1.2.7
  The developers are using it with XMMS 1.2.10
  
  If you use it with 1.2.6 please let me know.

  Precompiled binaries
  ====================
  Currently there are several precompiled binaries available.
  Check the website http://equ.sourceforge.net

  Compiling/Installing
  ====================
  - For the anxious:
    Just type 
  
      #./configure && make && make install

    from the command line. 

  NOTE: Starting with version 0.6 the configure script tries to compile the fastest
    possible code for the platform you're compiling in so you don't need to worry
    about the features of your X86 CPU to get the fastest code.
    This feature only works for systems using the proc filesystem
    under the X86 platform (e.g. Linux).
    (If you have another platform and now what compiler flags will help to make
     the plugin run faster please contact us).

  - For the calm:
  This software is 'configure'ified, which means that it uses autoconf and
  all the family of auto* tools to compile and install this package easily.
  So read the INSTALL file first if you're not familiar with the auto*
  tools (although you can skip its lecture).
  If you use an RPM based distribution be sure that the libxmms1*-devel
  package is installed as well as the libglib1.x*-devel and gtk+1.*-devel 
  packages otherwise the configure process will fail.

  Standard compilation and instalation
  
  #./configure && make && make install

   - Available options for configure:

    --libdir=$HOME/.xmms/Plugins/Effect
                If you want to have a local installation  (the plugin is 
                installed in your home's '.xmms' directory) instead of a 
                site-wide one use the following configure option

                NOTE: Don't use ~ because is not recognized by the configure 
                script

    --enable-debug (default: OFF)
		Enables the '-g' flag for GCC to have debug support added to
                the code (usually only for the developers) but is there in 
                case you need it

    --enable-mmx   (default: auto)
                If your CPU supports the MMX/3DNow instructions use this option to
                have a better performance. 

                #grep mmx /proc/cpuinfo

                If your CPU supports the MMX/3DNow instruction-set you will see a 
                line like the following one
                
                'flags           : fpu vme de pse tsc msr pae mce cx8 sep mtrr
                                    pge mca cmov pat pse36 mmx fxsr sse'

                CPU's that support MMX/3DNow are practically all AMD and Intel ones
                nowadays

    --enable-sse   (default: auto)
                If your CPU supports the SSE instructions use this option to
                have a better performance. Still I believe support for this 
                instructions were added to gcc starting from version 3.x
                You can check if your CPU supports them by typing the 
                following in a terminal window

                #grep sse /proc/cpuinfo

                If your CPU supports the SSE instruction-set you will see a 
                line like the following one
                
                'flags           : fpu vme de pse tsc msr pae mce cx8 sep mtrr
                                    pge mca cmov pat pse36 mmx fxsr sse'

                CPU's that support SSE are usually:
                    Pentium III
                    Pentium IV
                    Athlon?
                
        --enable-sse2   (default: auto)
                 If your CPU supports the SSE2 instructions use this option to 
                 have a better performance. Still I believe support for this
                 instructions were added to gcc starting from version 3.x
                 You can check if your CPU supports them by typing the 
                 following in a terminal window

                 #grep sse2 /proc/cpuinfo

                 If your CPU supports the SSE2 instruction-set you will see a 
                 line like the following one
                
                'flags           : fpu vme de pse tsc msr pae mce cx8 sep mtrr
                                    pge mca cmov pat pse36 mmx fxsr sse sse2'

                CPU's that support SSE2 are usually:
                    Pentium IV
                    Athlon?


        --enable-benchmark (default: OFF)
                You can compare the performace of different filter 
                implementations used by the equalizer by turning this on.
                This 'benchmark' will tell you only which filter implementation
                is the fastest, that's all.

  Skins
  =====
  Since version 0.5 the plugin is skinned. Thanx to Simone Lehmann.
  Read the file SKINS for installation instructions.

  Using
  =====
  First be sure XMMS' built-in equalizer is disabled!
  Then go to the Preferences menu and select the Effect/General Plugins tab.
  Select the EQ Plugin from the list and mark the 'Use plugins' next to
  the list.
  Since XMMS doesn't tell an Effect plugin when it has been selected, you
  will have to quit XMMS and run it again in order to see the GUI of the
  Equalizer or go into the Preferences menu of the plugin and toggle the
  'Show' option in the GUI section.

  From the Effect/General Plugins tab you can select Configure to
  change the following settings:

    - Show
      You can show/hide the GUI with this option. Hidding the GUI
      won't turn off the EQ
  
    - Shadowed mode
      Shadowed changes the equalizer GUI into a small horizontal bar where you
      can control de volume and the balance.
      To go into shadowed mode simply click on the second button from right to left
      in the upper-right corner of the GUI        
      You can return to full mode by pressing the same button again

	- Numer of bands the equalizer uses
	  Here you have five options:
		  	10 bands, original XMMS frequencies
			10 bands, ISO spaced frequencies
			15 bands, ISO spaced frequencies
			25 bands, ISO spaced frequencies
			31 bands, ISO spaced frequencies
	  Default is: 15 bands, ISO spaced frequencies

	- Use independent channels
	  When selected independent gain settings for the left and right 
          channels are available. Otherwise the plugin uses the same settings
          for both.
	  Default is: use the same for both channels

	- Lock sliders
	  When selected the band sliders are locked so when you adjust the gain
	  in one of the channels the other changes at the same time.
	  It has meaning only when 'Use independent channels' is selected.
	  Default is: ON

    - Automatic volume control
      This option will automatically turn down the volume when the EQ is
      turned off and will turn up the volume to its original setting when
      the EQ is turned back on.
      How fast the volume goes up/down is controlled by the sliding bar.
	  Default is: ON

    - Extra filtering
      This option turns on an extra filtering stage resulting in a better
      equalizing.
      The net result is that it sounds better ;) at a cost of 2x CPU cycles.
	  Default is: ON

  The presets menu:
    You can load/save presets manually and now also automatically.

  NOTE: If you have some good quality headphones I think you will appreciate
  		more what this plugin can do for the music you're playing.

  History
  =======
  Well, one day I was sitting in front of the computer listening to some music
  with XMMS (using XMMS's own equalizer) and then I started playing a CD from
  the CD-ROM unit and thought: wouldn't it be cool to equalize the CD output as
  well? (I don't have a nice shelf EQ as part of my sound system mind you)
  And then started finding out things.. and saw sadly that the EQ in XMMS
  only worked for MP3's, since it was something that each Input plugin
  programmer should provide.
  So then I thought about using mpg123 plugin's equalizer for the rest of
  the formats, but it was implemented for the frequency domain (you can
  learn about this on the references given in the 'Technical stuff' section
  later in this file), which basically meant that it wasn't a straightforward
  thing to use that code outside that plugin.
  After that I decided to look for other options to modify XMMS so that the
  output PCM audio could be equalized, not just the MP3's, so all the files
  that XMMS can play would be equalized. (Have you tried to listen those
  cool Ogg files lately and realized that they were not equalized? :P).
  Also I wanted to add some extra features.
  And well, this is the result :) I hope you enjoy listening as much as I do.


  Technical stuff
  ===============
  The EQ is implemented as two cascaded sets of band pass second order IIR
  digital filters working on the time domain.
  Each stage provides about +-14dB of gain/attenuation, but since they are all
  normalized for unity gain at the output, the original signal is attenuated at
  the output. This means that the volume level at the end is lower than the
  original unequalized audio unless all the bands' gain is set to the maximum.
  The bands' central frequencies are ISO spaced and also XMMS's Equalizer
  original frequencies are supported.
  The bandwidth of each of the supported number of bands are:
  10 bands - 1 octave
  15 bands - 2/3 octave
  25 bands - 1/3 octave
  31 bands - 1/3 octave

  The implementation of the IIR filters is now available also in fixed point,
  although the floating point implementation requires aprox. half the clock cycles
  than the fixed point in my PIII. It is provided just because.
  Read the following documents (I'm not related to these companies in any way)
  if you're interested in learning more about the theory behind the filters:
  - Constant-Q Graphic Equalizers, Rane Corporation. 
  	http://www.rane.com
  - The application note from Motorola 'DSP based 10-Band equalizer' has a lot
  of interesting information, although some of the math they do on the 
  application note had errors,
  	http://www.harmony-central.com/Computer/Programming/apr2-d.pdf
  - The DSPGuide is quite useful: 
  	http://www.dspguide.com