FreqTweak - Realtime audio frequency spectral manipulation
 
Written by Jesse Chappell <jesse@essej.net>

Please see the file COPYING for license details.
For building and installation instructions please see the INSTALL file.


**** Description ****

FreqTweak is a tool for realtime audio spectral manipulation and display. It
provides several algorithms for processing audio data in the frequency domain
and a highly interactive GUI to manipulate the associated filters for each. It
also provides high-resolution spectral displays in the form of scrolling-
raster spectragrams and energy vs frequency plots displaying both pre- and
post-processed spectra.

It is an extremely addictive audio toy, I have to pry myself away from playing
with it so I can work on it! I hope it has value for serious audio work too
(sound design, etc). The spectrum analysis is pretty useful in its own right.


**** Features ****

Freqtweak supports manipulating the spectral filters at several frequency
resolutions (64,128,256,512,1024,2048, or 4096 bands) depending on your needs/
resources. Overlap and windowing are also selectable.

The GUI filter graph manipulators (and analysis plots) have selectable
frequency scale types: 1x and 2x linear, and two log scales to help with
modulating the musical frequencies. Filters can be linked across multiple
channels.

The current processing filters are described below in the order audio is
processed in the chain. Any or all of the filters can be bypassed. The state
of all filters can be stored or loaded as presets.

    ** Spectral Analysis -- Multicolor scrolling-raster spectragram, or energy
      vs. freq line or bar plots... one shows pre-processed, another shows
      post-processed.

    ** EQ -- Your basic multi-band frequency attenuation. But you get an
      unhealthy number of bands...

    ** Pitch Scaling -- This is an interesting application of Sprengler's pitch
      scaling algorithm (used in Steve Harris' LADSPA plugin). If you keep all
      the bins at the same scale, it is equivalent to Steve's plugin, but when
      you start applying different scales per frequency bin, things quickly
      get weird.

    ** Gate -- This is a double filter where a given frequency band is allowed
      to pass through (unaltered) if the power on that band is between two dB
      thresholds... otherwise its gain is clamped to 0.

    ** Delay -- This lets you delay the audio on a per frequency-bin basis
      yielding some pretty wild effects (or subtle, if you are careful). A
      feedback filter controls the feedback of the delay per bin (be careful
      with this one). This is basically what Native Instrument's Spektral-
      Delay accomplishes. Granted, I don't have all the automated filter
      modulations (yet ;). See their website for audio examples of what is
      possible with this cool effect.


**** Requirements ****

    * JACK [jackit.sf.net] -- providing realtime low-latency audio
      interconnection and delivery. JACK requires the ALSA Linux sound
      drivers so you'll need those too.

    * FFTW [www.fftw.org] -- for speedy FFT processing
	(compiled as single-precision)

    * wxWindows (wxGTK) [www.wxwindows.org] -- the GUI toolkit I've
      chosen to use. It should work with the most recent 2.2.x and
      2.3.x series. Why not GTK? I happen to know wx better at the moment...


**** Misc Usage Tips ****

    * Left button click/drag to draw filters. If Control is down, the y-axis
      is fixed at the last cursor location (to draw nice horizontal lines).
      If Control *and* Alt are down you can draw nice arbitrary lines.

    * Right button drag to move filters around in space. The filters wrap
      around the left/right edges unless you hold down Control. Dragging with
      both left and right buttons down moves both primary and alternate
      together (on Gate).

    * Holding Shift modifies the alternate filter (on double filter graphs
      like Gate) for the previous operations.

    * Middle-button pops up frequency axis menu.

    * Ctrl-Alt right-click resets a filter to default values.

    * Shift-Ctrl-Alt Left-Drag zooms in on the y axis.
      Look at the status bar to see the values for the cursor
      itself and the values of the filter at the cursor's
      frequency.  Shift-Ctrl-Alt Right click-release resets
      the Y-zoom to full.  	      

    * The B and BA buttons mean Bypass and Bypass All respectively.

    * The L and LA buttons mean Link and Link All respectively.


****  Here is an example of using freqtweak with an alsaplayer feeding it
      and output going to speakers (alsa_pcm:out_?) without using a JACK patchbay:
 
   Start freqtweak first with this command line:
      freqtweak -i none,none -n ft  &

   [ you will see some jack errors, ignore them.. they are intentional ]

   Start alsaplayer like so:

     alsaplayer -o jack -d ft:in_1,ft:in_2  &





**** TODO ****

    * Fix known bugs
    * Support reordering of processing modules
    * Automated filter modulation (via plugins?)
    * Plot performance optimizations (OpenGL?)
    * Whatever else the users want :)


==============================================================================
  Jesse Chappell <jesse@essej.net>
  Last modified: Sat Oct 12 13:02:59 EDT 2002

