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

  Disclaimer
  ==========
  #include <standard_disclaimer.h>

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

  Introduction
  ============
  EQ is a graphic equalizer effect plugin for XMMS that equalizes everything
  that XMMS sends to the output, not just MP3s. 
  This means that your OGG, WAV, etc. files are also equalized.

  It features

  - 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

  - Skin support
  - Independent gain settings for left and right channels (configurable)
  - More than +-14dB of gain per band
  - Floating point and fixed point implementations of the equalizer core routines

  The latest version should be available from

	http://equ.sourceforge.net/

  Requirements
  ============
  - 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.
	
  - XMMS 1.2.7 (Recommended)
  The plugin DOESN'T work on XMMS 1.2.5 but it may work on 1.2.6.
  This code was developed using XMMS 1.2.7
  
  If you use it with 1.2.6 please let me know.
  
  - This code is CPU intensive, so the newer and faster the processor is the
  	better for you.
    In a PIII @ 900MHz, 'top' reports ~16%-20% of CPU usage (yes, 'top' is 
	not a good benchmark).
    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

  Precompiled binaries
  ====================
  	Currently there are RPM packages available for the PLD (Polish Linux Distribution)
	at http://www.pld.org.pl

  Compiling/Installing
  ====================
	This software is 'configure'ified, which means that it uses autoconf and
	all the family of auto* tools.
	So read the INSTALL file first if you're not familiar with it (although
	you can skip its lecture).
	If you use an RPM based distribution be sure that the xmms1*-devel
	package is installed as well as the libglib1.x*-devel and gtk+1.*-devel 
        packages otherwise the configure process will not complete.

	If you want to have the plugin installed in your own '.xmms' directory
	or wherever you desire other than XMMS's own installation directory
	structure, pass the optioniebremx@users.sourceforge.net

		--libdir=<directory>

	to the configure script, where '<directory>' is the place where you want it.
	Be sure of course that XMMS knows that you have a plugin in '<directory>'.

	NOTE: Specify the whole path, don't use ~ because is not recognized
		  by the configure script

	To compile and install:
  	#./configure; make; make install

	Available options:

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

        --enable-sse   (default: OFF)
                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 this in Linux by typing the following in a terminal
                window

                #grep sse /proc/cpuinfo

                If your CPU supports SSE you will see a line like this 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 this are usually:
                    Pentium III
                    Pentium IV
                
                This option will work

        --enable-sse2   (default: OFF)
                 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 this in Linux by typing the following in a terminal
                window

                #grep sse2 /proc/cpuinfo

                If your CPU supports SSE you will see a line like this 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 this are usually:
                    Pentium IV


        --enable-benchmark (default: OFF)
                You can compare the performace of different settings in 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
  =====
  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
          
	- Numer of bands the equalizer uses
	  Here you have four 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.
          The net result is that it sounds better ;) at a cost of 2x CPU cycles.
	  Default is: ON

        - Use fixed point
          This options makes EQ use an alternative implementation of the filters
          which doesn't require the use of the floating point unit.
          Turning on this options will result in a decreased performance in the
          filter implementation, hence more CPU usage.
	  Default is: OFF

  The BOOST button:
    There's a boost button at the left of the EQ. Right now doesn't do anything but
    it will become a 'configurable' button.

  The presets menu: XXX Pending
    You can load/save presets manually. 
    Unfortunately there's no way to have presets by song because
    XMMS doesn't tell the plugin when a new song has started playing.

  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
