Extace Waveform Viewer
----------------------

   This is the eXtace Audio signal visualizer.  It plugs itself in as 
   an EsounD or ALSA Loopback monitor and displays the output from Audio
   passing through EsounD or the ALSA card/device/subdevice selected. 
   eXtace will NOT display the output of a CD playing in your CD/CDRW/DVD
   drive, as the drive does all the decoding an just passes analog audio
   through your soundcards mixer. eXtace requires the raw PCM (Puls Code 
   Modulation) audio data to give you a display.  There are many apps that 
   can extract the audio data from a CD to be played back in this manner. 
   cdda2wav and paranoia are two main applications that can "rip" audio
   data off of a CD to be piped through ALSA or Esound so eXtace can "see"
   it.
   
   EsounD is Gnome's sound daemon.  ALSA stands for the Advanced Linux
   Sound Architecture.  It is still in fairly heavy development, but the 
   0.5.x stable tree works well and has many more features than OSS,
   which may have came with your Linux box, while maintaining OSS 
   compatibility.  Currently ALSA is at 0.9.xbeta level, and eXtace does 
   NOT YET support it as the previous loopback functionality has been removed
   and I have not coded in a workaround yet.
   
   
Features:
   eXtace has several modes, 3D Wireframe FFT, 3D solid FFT, 2D Graphic
   Equalizer, Several scopes (dot, line, gradient), a 3D Spike FFT (high
   resolution) and a 2 2D spectrograms, (horizontal and vertical scroll). 
   All modes are fully configurable via the options panel.  Any of the 3D 
   modes can be dragged around the screen by grabbing an end with the 
   mouse and moving it anywhere within the window.

   The direction panel will appear when the proper display is running.  This
   works similar to above. Just grab the end of the marker and drag it around 
   and the trace will travel off into space in the same direction as the 
   pointer in the direction window.


   Clicking your middle mouse button on any of the displays brings up a 
   colormap editor to change the colormap eXtace uses.  (For those of you with
   two button mice, try hitting both buttons at once to mimic the middle button)
   Clicking within the gradient on the left and then selecting a color on the
   right and clicking "OK" will update the window and the running display.
   Colormaps can be saved and loaded using the Load/Save buttons. An arbritrary
   number of colormaps can be setup.  If you come up with something REALLY cool
   send me the colormap file and I'll include it with the next release. 
   Colormaps are stored in your ~/.eXtace/ColorMaps/ Directory. Their structure
   is extremely simple (and somewhat inflexible), see the source for details.

Compilation instructions:
   You will need either ALSA or Esound installed and working and the FFTW 
   (Fastest FFT in the West) library to build and run eXtace.
   The FFTW lib can be found on http://www.fftw.org/. Source and Binary RPMS
   are mirrored on http://extace.souceforge.net/


   Run "./configure" (no quotes). Then "make" and then "make install" as root.
   Every effort has been taken to try and address the various installation
   methods of fftw, but occasionally the configure script fails to locate
   a library or header file properly.  If you run into this problem, email
   me your config.log, the screen output from running ./configure and any 
   options you fed to configure to get it to fail.


   The EsounD daemon 'esd' will need to be running as well, though NOT 
   necessarily if you are using ALSA and have selected the proper card/device 
   and subdevice in eXtace's options panel.  You can switch between Esound 
   and ALSA if you are playing between them simultaneously. 

   Currently there are no command line parameters.  An options panel
   is available to tune the speed, and 3D effects.

   ALSA information:
       ALSA has the concept of Card, Device and Subdevice:
       A Card is just like it says, your Sound card, each one has a number 
       usually starting with 0. (first one) the soundcard number is 
       user configurable with module parameters in /etc/conf.modules. See ALSA
       documentation for more details.
       A Device is a PCM (Pulse Code Modulation), a.k.a. DAC device on the card.
       Most cards only have one, others (AC97 and others can have more)
       A subdevice (formerly known as subchannel) is if the card is a multi-
       channel card. (i.e. a High end professional series card). The subdevice
       also applies to ALSA's "share" card, which is a virtual sound card that
       gives you the ability to use multiple apps that playback SIMULTANEOUSLY
       This is pretty close to ESOUND, only the latency is lower, predictable,
       and the format conversion is EXCELLENT, compared to Esounds' 
       harsh sample rate conversions.  ALSA's share driver does NOT have sample
       caching like Esound, or network support though...

Performance:
   eXtace was tuned to try and use as little processor as possible. (I have
   not found any other visualizer app that uses as little as eXtace.) 
   NOTE: my system is a Dual Celeron 500, with an NVIDIA GeForce2 running XFree
   4.0.3 and NVIDIAs' binary drivers.  Your system performance may vary...
   I typically see processor usage of around 2-15% for eXtace plus 5-20% for
   X (the X server).  If you run into very high processor usage (over 70%) 
   you can try turning on or off the backing pixmap option with the options 
   panel.  On Xfree 3.3.x Backing pixmap turned off gives me lower processor
   usage.  Though on Xfree 4.0.x I get MUCH lower processor use with backing
   pixmap turned on.  Your mileage may vary.  NOTE: The more video RAM your 
   card has, the better. (more ram = more space for pixmap caches and other
   off-screen stuff.)  With less memory backing pixmaps become slower as system
   memory has to be used and overhead increases.  Having backing pixmap cache
   turned off will result in flicker though (which may get annoying).

Testing:   
   The sine.c is an example program to test extace with, just run

	./sine | esdcat				<--- ESOUND
	./sine | aplay -c0 -fs16l -s44100 -S	<--- ALSA
change the -c0 to whatever soundcard number you have if you have more than
one. The ALSA line is specific to Alsa 0.5.x series. ALSA 0.9.0 may have 
different syntax when it is released.


   Turn down your volume though as it may be loud.. :)
   This feeds a sine wave into ALSA/Esound which you should hear, 
   and see in eXtace.

Misc:
   The scope has an option in the panel to enable/disable the Trace Stabilizer.
   The stabilizer uses a mathematical routine (called a convolution) that 
   is used as a pattern matcher to stabilize the dispay.  Thanks to Ralph 
   Loader for giving me a hand with the code and Andy LaFoe for the code from
   Alsaplayer (One cool mp3/audio player, the only Variable speed one too). 
  
    
   Enjoy!

Dave Andruczyk. <djandruczyk@yahoo.com>

Based on the orignal extace code written by:
The Rasterman           <raster@redhat.com> 
Michael Fulbright       <msf@redhat.com>

