README for SooperLooper LADSPA Plugin
2002, Jesse Chappell <jesse@essej.net>

http://essej.net/sooperlooper/


SooperLooper is a looping sampler very much like the Gibson/Oberheim
Echoplex Digital Pro.  In fact, it is a downright emulation of an EDP,
with some additional features and a silly name.  I figured that the EDP feature-set is
powerful, proven, and popular -- so why not implement it as a LADSPA plugin
we can all use?  It is a true realtime software looper if used with a 
low-latency Linux kernel and the proper audio buffer configuration.

I have never used an actual EDP, but all the features are described in
the user's manual, which was an invaluable resource.  Take a look at
http://www.loopers-delight.com/tools/echoplex/echoplex.html to get the
manual and other tips.  It all applies.

FEATURES of SooperLooper shared with the EDP:
  Record
  Overdub
  Multiply
  Insert
  Replace
  Reverse
  Mute
  One Shot
  Undo
  Tap tempo delay mode
  Feedback and Mix parameters
  QuantizeMode and RoundMode toggles

Additional features of SooperLooper:
  Redo
  Scratch Mode (DJ-like scratching of the current loop)
       w/ arbitrary playback rate


There are a few differences in functionality on the alternate endings
of certain functions, but for the most part I tried to match the EDP
manual.  The primary difference is the mechanism of control, as it is
a LADSPA plugin and not hardware :)

See the PARAMETERS file for a detailed description of the LADSPA input and
output parameters for this plugin.


HOW TO GET IT WORKING FOR YOU
-----------------------------

*** NEW! PD PATCHES ****

Included are patches for Pure-Data (PD) which use the plugin~ external
to wrap the SooperLooper plugin.  However, because of bugs and missing
features of plugin~-0.2 you will need to apply this patch to use it:
  http://essej.net/sooperlooper/pd-plugin0.2-patch.diff

Once you have a patched plugin~, fire up PD making sure that
it and 'sooperlooper~.pd' and 'sooperloopermanual_midi.pd' are located 
in your PD path (or specified via the -path argument).

Open 'sooperloopermanual_midi.pd', you will need to get audio in and
out.  You can open up a new window to 'throw' and 'catch' the data
from the audio hardware as seen in the screenshot:
  http://essej.net/sooperlooper/sooperlooper_pd_shot.png
Or do it your own way....

You can control it via the buttons, or via a MIDI program change
messages ideally sent by your MIDI footcontroller.  The values are:

   UNDO       0   // UNDO ALL in mute mode
   REDO       1   // DELAY TAP, if REDO_TAP_MODE is true
   REPLACE    2   // QUANTIZE TOGGLE in mute mode
   REVERSE    3   // ROUND TOGGLE in mute mode
   SCRATCH    4   // UNMUTE from Top in mute mode
   RECORD     5
   OVERDUB    6
   MULTIPLY   7
   INSERT     8   // ONE SHOT playback from mute mode
   MUTE       9   // UNMUTE continue in mute mode

  The value of the tens digit (well, 0-12) is used to match the value
  of the "Multi Tens" parameter set for a given instance of the
  plugin.  This way you can use the same hardware controller to
  control several independent instances of the plugin.




INSTALL THE PLUGIN AND TRY THE PYTHON DEMO:
-------------------------------------------
If you just want to try it out without investing the time and
effort to do it with your feet, or learn PD :) I included a sample
curses-based console program to let you try it out with the keyboard.
It also has some nice feedback from the control outputs to let you
know the state of the plugin and time info about the looping.


'sltester.py' is a Python script using curses and pyecasound to handle
the audio.  You must have Python 2.x, the LADSPA header file and
Ecasound (with pyecasound module (including eci.py) properly
installed).  Ecasound is fantastically useful and well designed for a
wide variety of audio applications, you should already have it if you
don't.

Get them at:
  http://www.python.org
  http://www.ladspa.org
  http://www.wakkanet.fi/~kaiv/ecasound/

Compile SooperLooper by possibly editing the Makefile, and running
'make' and copying SooperLooper.so into your LADSPA_PATH (or 'make
install').


Run the python script like this:
  ./sltester.py 2> error.output

And in another window tail the file to see the debugging output:
  tail -f -s 0 error.output

If you don't do this the stderr will screw up the curses display. And its
useful to see the debugging output, if you compiled it in.

Make sure your mixer is set to record the input you want to use, and
everything except PCM and master is muted.  If you don't have a good
full-duplex soundcard and/or low-latency kernel you may want to
increase the -b:128 in the ECASTART variable near the top of
sltester.py to -b:256.  However, with a low-latency patched kernel and
running as root (to get SCHED_FIFO) you should have no problems (you
could even take it down to -b:64).

Have at it... note that the usage portion of the window changes a bit
depending on what state the plugin is in.  The updating time status is
turned off by default, but if you have nice low-latency stuff enabled you can
turn it on without any overruns.... (press 's').


INADEQUATE USAGE TIPS

RECORD:
  Start here.  If Threshold > 0 the loop recording doesn't start until
  the audio data is greater than the threshold.  The same goes for
  when you finish a loop by pressing RECORD again, the loop doesn't
  end until the audio goes above the threshold.  It might seem
  strange, but this really helps get clean seams on your loops.  For
  instance, in silence press RECORD the first time.  Then play a
  measure or two in proper time, and just _before_ you hit the
  downbeat (it must be below threshold) press RECORD again and play
  the downbeat in time, don't stop.  The loop will take over and if
  you did it right your last downbeat will be louder, but not out of
  time.  If the Threshold is 0, it starts and stop the moment you
  press RECORD.  See the tips in the EDP manual, it works best if you
  stop and start recording the moment you hit the downbeat, not
  before.  Trust them.

  If you end a RECORD with another function it will finish the loop
  immediately (threshold ignored) and start doing the new function.  A
  special feature: ending with REVERSE stops recording and plays the
  loop backwards once then goes into MUTE mode.


OVERDUB:
  This just keeps playing the loop and just keeps adding whatever you
  play until you stop overdubbing.  Very useful.... this is the main
  tool.

MULTIPLY:
  This similar to overdub, except the original loop is repeated
  underneath you "multiplying" the loop length until you stop it.
  Thus it can turn a 1 measure loop into a 2,3, etc measure loop.
  QuantizeMode and RoundMode affect how the overdubbing starts and
  stops.  See if you can figure it out. Keep in mind that the original
  loop length is a "cycle" and the loop length will be a multiple of
  that.  You can actually make an already multiplie loop have fewer
  cycles with the right combination of options.

  If you end a MULTIPLY with a RECORD press it ends the loop
  immediately and resets the cycle length to the whole loop, if you
  want that.


INSERT:
  It insert new input in place, but always one "cycle" length...
  QuantizeMode and RoundMode have effects (RTF EDP Manual).

REPLACE:
  Is like overdub without keeping or playing the underlying audio.

REVERSE:
  Reverses playback direction.  Can be used in play mode, and even
  during an OVERDUB, which makes for some pretty interesting stuff.
  Can also be used in DELAY mode.

UNDO:
  Undoes the last operation and immediatly plays the previous loop
  maintaining the current time if the loop you are undoing was based
  on the previous loop (usually is).  You can go all the way back to
  the first one.

REDO:
  Redoes the loop if it can (if you haven't done a new operation since
  your last undos).  Taken together UNDO and REDO allow you to do some
  neat things: record a verse part, then hit record to do a chorus
  part.  To get back to the verse, press UNDO... to get to the chorus
  press REDO...  Pressing UNDO while in MUTE mode undoes all the way
  back (can be redone).

MUTE MODE:
  To continue playing the loop press MUTE again.  To continue playing
  the loop from the top press SCRATCH.  To play back the loop once and
  return to mute, press Insert/OneShot.

  You can toggle some of the parameters while in MUTE mode, see the
  usage panel.  QuantizeMode and RoundMode are described in the EDP
  manual... the semantics in SooperLooper are almost the same, there
  is a subtle difference in MULTIPLY mode when QuantizeMode is on,
  more description to come.

TAP DELAY MODE:
  If you set the REDOTAPMODE parameter to non-zero, the REDO button
  will become the trigger for the tap tempo delay mode.  Or you can
  use the dedicated conrol input on the LADSPA plugin for the tap
  trigger (any change is considered a trigger).  The time between the
  most recent two presses is the new delay time.  While in DELAY mode,
  you can toggle Hold Mode, or Reverse at any time for a cool effect.
  To get out of delay mode press any other function or UNDO.  You will
  probably want to adjust Feedback down from 1 before you enter delay
  mode or you'll build up a nice cacophony fast.

SCRATCH MODE:
  By default the Scratch Rate Active is toggled off which means it
  ignores the Scratch Rate parameter.  Changes in the Scratch Position
  input parameter over time define the rate of playback (position unit
  is ratio of current loop length).  Pressing the Reverse command
  while in Scratch mode toggles the Scratch Rate Active flag.  Then
  the loop is played back at Rate input parameter (which can be +/-
  anything) unless you're actively scratching.

  You can't test this feature in the console demo, but it works great
  with a hardware controller patched in through midi and Ecasound.
  I personally use a Theremin (PAIA Theremax) with CV output through
  my MIDI pedal, very cool.







