--- a/README
+++ b/README
@@ -1,146 +1,127 @@
                                  Xsynth-DSSI
                                  ===========
-                    A software synthesizer plugin for the
-                          DSSI Soft Synth Interface
+                    A software synthesizer plugin  for the
+                        Disposable Soft Synth Interface
+
+NOTE
+====
+This is an ALPHA snapshot.  Please do not redistribute.
 
 Introduction
 ============
 Xsynth-DSSI is a classic-analog (VCOs-VCF-VCA) style software
-synthesizer which operates as a plugin for the DSSI Soft Synth
-Interface.  DSSI is a plugin API for software instruments (soft
-synths) with user interfaces, permitting them to be hosted
-in-process by audio applications.  More information on DSSI can be
-found at:
+synthesizer which operates as a plugin for the Disposable Soft Synth
+Interface (DSSI).  DSSI is a proposal for a plugin API for software
+instruments (soft synths) with user interfaces, permitting them to
+be hosted in-process by Linux audio applications.  More information
+on DSSI can be found at:
 
   http://dssi.sourceforge.net/
 
-Xsynth-DSSI is written by Sean Bolton, and copyright (c) 2010 under
-the GNU General Public License, version 2 or later.  See the enclosed
+Xsynth-DSSI is written by Sean Bolton, and copyright (c)2004 under the
+GNU General Public License, version 2 or later.  See the enclosed
 file COPYING for details.  While this software is 'free' within the
 requirements of this license, I (Sean) would appreciate any or all
 of the following should you find Xsynth-DSSI useful:
-
     - an email stating where you're from and how you're using
         Xsynth-DSSI, sent to <musound /at/ jps /dot/ net>.
     - copies of or links to music you've created with Xsynth-DSSI.
     - any patches you create for Xsynth-DSSI.
     - suggestions for improving Xsynth-DSSI.
-    - offers of paying work writing this sort of code!
-
-Xsynth-DSSI is based on Steve Brooke's Xsynth 1.0.2, which is
-available (also under GPL) at:
+
+Xsynth-DSSI uses the sound generation code from Steve Brooke's Xsynth
+1.0.2, which is available (also under GPL) at:
 
   http://www.ibiblio.org/pub/Linux/apps/sound/misc/xsynth-1.0.2.tar.gz
 
 Xsynth-DSSI retains the basic synthesis model of Xsynth, while
-adding the following features:
-    - operation as a DSSI plugin,
-    - polyphonic operation,
-    - band-limited oscillators,
-    - a new, more stable filter mode, and
-    - velocity-sensitive envelopes.
+extending it to polyphonic operation as well as operation as a DSSI
+plugin.
 
 Requirements
 ============
 Xsynth-DSSI requires the following:
 
-    - DSSI version 0.9 or greater, available from the
-        dssi.sourceforge.net address above.
-
-    - liblo version 0.12 or later (0.23 or later recommended), a
-        library implementing the Open Sound Control (OSC) protocol,
-        available at:
-
-        http://liblo.sourceforge.net/
-
-    - pkgconfig with PKG_CONFIG_PATH set appropriately to pick up
-        DSSI and liblo.
-
-    - GTK+ version 1.2 or 2.x.  (If GTK+ is not found, the plugin
-        will be built without the GUI.)
-
+    - GTK+ version 1.2.x.
+    - liblo version 0.5 or 0.6, a library implementing the Open
+        Sound Control protocol, available at
+        http://plugin.org.uk/liblo/
     - the LADSPA v1.x SDK.
-
     - the ALSA headers (DSSI plugins use ALSA structures, but not
         the actual drivers, so you don't necessarily need the
-        drivers installed.)  Users of non-Linux systems can use
-        libdssialsacompat, available at:
-
-        http://smbolton.com/linux.html
-
-    - a working DSSI host.  Xsynth-DSSI has been tested with
-        jack-dssi-host, available in the DSSI distribution, and with
-        ghostess, available at:
-
-        http://smbolton.com/linux.html
-
-    - automake 1.7, autoconf 2.58, and libtool 1.4.3 or better if
-        you wish to recreate the build files.
+        drivers installed.)
+    - a working DSSI host.  Xsynth-DSSI has been tested with the
+        example DSSI host available at the dssi.sourceforge.net
+        address above.
+    - automake 1.7 and autoconf 2.57 or better if you wish to
+        recreate the build files.
 
 Installation
 ============
-The generic installation instructions in the enclosed file INSTALL
-aren't particularly helpful, so try this instead:
+The enclosed file INSTALL provides generic installation instructions
+which assume I've invoked the proper automake/autoconf magic --
+which I know I haven't completely done yet.  Hopefully you should be
+able to:
 
 1. Unpack the tar file.
 
-2. Make sure PKG_CONFIG_PATH is set correctly to locate the
-    dssi.pc and liblo.pc pkgconfig files.  On many systems, this
-    will be:
-
-    $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
-    $ export PKG_CONFIG_PATH
-
-3. 'cd' into the package directory and execute './configure'.
+2. Execute './configure' with CFLAGS pointing to your liblo headers
+    and LDFLAGS pointing to your liblo library, if they're not in
+    your compiler's default search paths.  For example, I do:
+    
+    $ ./configure --prefix=/opt/audio CFLAGS=-I/opt/audio/include \
+        LDFLAGS=-L/opt/audio/lib
+
     configure will add '-Wall' and my favorite optimizations to
     CFLAGS for you if you don't include any '-Wall' or '-O' options.
     If you're using gcc and wish to provide your own optimization
     flags, you MUST at least use '-finline' and a non-zero '-O' flag
     to get decent results.
 
-4. Enable debugging information if you desire: edit the file
+3. Enable debugging information if you desire: edit the file
     src/xsynth.h, and define XSYNTH_DEBUG as explained in the
     comments.
     
-5. Do 'make'.  Hopefully it should build without warnings (or
+4. Do 'make'.  Hopefully it should build without warnings (or
     errors.)
 
-6. 'make install' will install the following:
+5. 'make install' will install the following:
 
     <prefix>/lib/dssi/xsynth-dssi.so
     <prefix>/lib/dssi/xsynth-dssi/Xsynth_gtk
     <prefix>/share/xsynth-dssi/factory_patches.Xsynth
-    <prefix>/share/xsynth-dssi/version_0.1_patches.Xsynth
+    <prefix>/share/xsynth-dssi/patch_library.Xsynth
 
 Feedback on your experiences building Xsynth-DSSI is appreciated.
 
 Operation
 =========
-To run the Xsynth-DSSI plugin under the jack-dssi-host provided in
-the DSSI distribution, I do the following:
+To run the Xsynth-DSSI plugin under the DSSI example host provided
+in the dssi-0.3.tar.gz distribution, I do the following:
 
 1. Start JACK.
 
-2. Start jack-dssi-host, supplying the correct plugin path
+2. Start the DSSI example host, supplying the correct plugin path
     and filename (substitute <prefix> as appropriate):
 
-    $ DSSI_PATH=<prefix>/lib/dssi sudo jack-dssi-host xsynth-dssi.so
-
-    jack-dssi-host should start, and moments later the Xsynth-DSSI
+    $ DSSI_PATH=<prefix>/lib/dssi dssi_example_host xsynth-dssi.so
+
+    The example host should start, and moments later the Xsynth-DSSI
     graphic user interface should appear.
 
-3. Use aconnect or kaconnect to connect jack-dssi-host to a MIDI
+3. Use aconnect or kaconnect to connect the example host to a MIDI
    source, such as vkeybd.
 
-4. Begin playing sounds!  If you get no response, try clicking the
-    'Send Test Note' button in the Xsynth-DSSI GUI. This sends a
-    note directly via the host to the plugin, so if you hear sound
-    now, look for a problem between the example host and your MIDI
-    source.  If you still don't hear sound, I'd look for a problem
-    between the example host and your output device.  If you
-    continue having trouble, you might recompile with XSYNTH_DEBUG
-    bit 2 set, which will cause the plugin to continuously output a
-    quiet buzz to help debug your outgoing signal path.
+4. Begin playing sounds!  If you get no response, try selecting the
+    'Patch Edit' tab in the Xsynth-DSSI GUI, and click the 'Send
+    Test Note' button.  This sends a note directly via the host to
+    the plugin, so if you hear sound now, look for a problem between
+    the example host and your MIDI source.  If you still don't hear
+    sound, I'd look for a problem between the example host and your
+    output device.  If you continue having trouble, you might
+    recompile with XSYNTH_DEBUG bit 2 set, which will cause the
+    plugin to continuously output a quiet buzz to help debug your
+    outgoing signal path.
 
 Xsynth-DSSI starts up with a small set of sound presets, or
 'patches', that you can select either by selecting the GUI 'Patches'
@@ -152,7 +133,7 @@
 You may load additional patches by selecting 'Load Patch Bank...'
 from the GUI 'File' menu, and pointing the file selection dialog to
 a Xsynth-DSSI patch bank file.  One such file is patch_library.Xsynth,
-which is installed with the plugin, in <prefix>/share/xsynth-dssi/.
+which was installed with the plugin, in <prefix>/share/xsynth-dssi/.
 After selecting a patch bank file, you will be asked at which
 program number to begin loading the new patches.  This allows you to
 overwrite the existing patches, or to add the new patches at the
@@ -161,22 +142,13 @@
 patches will not be loaded.
 
 Selecting 'Save Patch Bank...' from the 'File' menu will allow you
-to save your patch bank to a file.  After specifying the file name,
-you will be asked to specify the range of patches to be saved.
+to save you patch bank to a file.  It always saves the entire bank.
 
 Patches Tab
 -----------
 Selecting the 'Patches' tab displays a list of all the patches loaded.
 Clicking on the name of a patch causes that patch to be selected.
 
-Test Note
----------
-The 'Test Note' controls allow you to send a test note to the
-plugin, by clicking on the 'Send Test Note' button.  Changing the
-'key' and 'velocity' sliders will change the pitch and velocity of
-the test note.  A key of 60 is generally considered to be
-'Middle C'.
-
 Patch Edit Tab
 --------------
 This tab allows you to edit patches.
@@ -186,17 +158,10 @@
 synthesis parameters used by the plugin to create sound.  The voice
 architecture is described in more detail below.
 
-Note that the rotary knobs may be manipulated in several ways:
-    - Clicking and dragging a knob with mouse button 1 sets the
-        value directly, by making the knob pointer point toward the
-        mouse pointer.
-    - Clicking and dragging a knob with mouse button 3 allows
-        incremental adjustment of the knob's current value (without
-        a sudden jump.) Horizontal movement produces large variation
-        in the knob value, while vertical movement allows finer
-        control.
-    - Clicking on a knob with buttons 1 and 3 increment and
-        decrement the knob value.
+The TEST NOTE controls allow you to send a test note to the plugin,
+by clicking on the 'Send Test Note' button.  Changing the 'Test
+Note' slider will change the pitch of the test note, with 60
+generally considered to be 'Middle C'.
 
 The NAME text box allows you to change the name of a patch.
 
@@ -205,21 +170,16 @@
 will be asked to which program number you would like to save your
 new patch.  If you do not wish to overwrite an existing patch,
 selected the highest available patch number, next to which '(empty)'
-will be displayed, to save your changes to a new slot.  Be sure to
-then use 'Save Patch Bank...' from the 'File' menu to save your
-changes to a file.
+will be displayed, to save your changes to a new slot.
 
 Configuration Tab
 -----------------
-Tuning: Sets the tuning of this instance of the plugin, as Hz for
-    A-above-middle-C.
-
 Polyphony: Sets the maximum polyphony for this instance of the
     plugin.  If you attempt to play more notes than this setting,
     already-playing notes will be killed so that newer notes can be
     played.  If you are getting xruns, try reducing this setting.
 
-Monophonic Mode:
+Monophonic modes:
     'Off'  - polyphonic operation.
     'On'   - monophonic operation, where the envelopes are
              retriggered upon each incoming note on event. 
@@ -231,142 +191,30 @@
              retriggered at each note on, and upon note off when
              other keys are still held.
 
-Glide Mode:
-    'Legato Only' - portamento (a 'slide' in pitch between two
-             notes) is only used when a new note is played while
-             another is held.
-    'Non-legato Only' - portamento is only used for single
-             (staccato) notes, or the first note of a legato phrase.
-    'Always' - portamento is always used.
-    'Leftover' - like 'Always', but ... more difficult to predict.
-    'Off'  - disables portamento.
-
-Pitch Bend Range: Set the pitch bend range, from 0 to 12 semitones,
-    for this instance of the plugin.
-
 Voice Architecture
 ==================
-Xsynth-DSSI models a simple analog synthesizer, where two
-oscillators (VCO1 and VCO2) are mixed (MIXER) and fed to a low pass
-filter (VCF), which then feeds an amplifier (VCA) controlling the
-output volume:
-
-    VCO1
-      |
-      v
-    MIXER --> VCF --> VCA --> output
-      ^
-      |
-    VCO2
-
-Modulation of these elements is possible using two envelope
-generators (EG1 and EG2), a low-frequency oscillator (LFO), and the
-MIDI key and velocity.
-
-Oscillators VCO1 and VCO2
--------------------------
-The frequencies of VCO1 and VCO2 are controlled by the MIDI key,
-plus the value of the 'pitch' control.  Compared to a base pitch of
-'0', a value of '5' is one octave higher, and a value of '10' is two
-octaves higher.
-
-The pitch from the MIDI key may be lagged by the PORTAMENTO 'glide'
-value, as determined by the glide mode and other keys in play (see
-above).
-
-The frequency of VCO2 is also affected by the 'pitch mod' amounts
-from EG1, EG2 and the LFO.
-
-The waveforms available for both oscillators are:
-    0. sine
-    1. triangle
-    2. ascending sawtooth
-    3. descending sawtooth
-    4. square
-    5. variable-width rectangle
-    6. variable-slope triangle
-
-The 'pw/slope' control sets the width and slope of waveforms 5 and
-6, respectively.  It has no effect when waveforms 0 through 4 are
-selected.
-
-VCO2 may be 'hard synced' the VCO1, so that its phase resets
-whenever VCO1 completes a cycle, by selecting the 'osc sync'
-checkbox.
-
-MIXER
------
-A 'balance' setting of '0' causes the mixer to output only VCO1, a
-setting of '10' outputs only VCO2, and a setting of '5' results in
-an equal mix of both.
-
-Low Pass Filter VCF
--------------------
-The VCF cutoff frequency is set by the 'cutoff' control, plus the
-'filer mod' amounts from EG1, EG2, and LFO.
-
-The filter resonance, or 'Q', is set by the 'resonance' control.  Be
-aware that the filter is not always stable when the resonance is
-very high, and when the resonance is very low but the cutoff is very
-high.
-
-The 'mode' option menu controls which of the three filters is used:
-    '12 db/oct' - the original Xsynth two-pole filter.
-    '24 db/oct' - the original Xsynth four-pole filter.
-    'MCVLPF-3'  - Fons Adriaensen's MCVLPF-3, modeled after the
-                  voltage-controlled lowpass filter invented by
-                  R. A. Moog.
-
-Amplifier VCA
--------------
-The gain of the VCA set by both the 'volume' control and the
-envelope generator EG1.
-
-Envelope Generators EG1 and EG2
--------------------------------
-The envelope generators are classic 'ADSR'-style: the 'attack'
-control sets the time it takes from key-on for the envelope to reach
-full output, the 'decay' control sets the time it then takes to fall
-to the 'sustain' level, where it stays until key-off.  The 'release'
-control sets the time it then takes to fall back to zero output.
-
-The 'vels sens' (velocity sensitivity) control determines the amount
-the envelope output is reduced by low MIDI velocities.  At a
-sensitivity of '0', the envelope always goes to full output.  At
-maximum MIDI velocity (127), the envelope always goes to full
-output.  Otherwise, the lower the velocity and higher the
-sensitivity, the greater the reduction of the envelope's output.
-
-Low-frequency Oscillator LFO
-----------------------------
-The duty cycle of the waveform 5 (rectangular) is fixed at 25% high,
-and waveform 6 (variable-slope triangular) is not available.
+!FIX! this section needs to be rewritten, or maybe just written.
 
 MIDI Controller Mapping
 =======================
-For DSSI hosts that support MIDI controller mapping, Xsynth-DSSI
-requests that they map two MIDI controllers:
-
-- MIDI Control Change 5 "Portamento time" is mapped to the
-    PORTAMENTO 'glide' control, although in a somewhat backward way:
-    higher CC values map to shorter glide times, and lower CC values
-    to longer glide times.
-
-- MIDI Control Change 8 "Balance" is mapped to the MIXER balance
-    control.
-
-Xsynth-DSSI itself interprets several other MIDI control messages:
-
-- MIDI Control Change 7 "Volume" controls the output level, without
-    affecting the VOLUME control.
-
-- MIDI Control Change 1 "Modulation wheel" reduces the VCF cutoff.
-
-- MIDI channel pressure and key pressure are combined to boost the
-    VCF resonance.
+Xsynth-DSSI tells the DSSI host to map MIDI volume controller #7 to
+the plugins 'volume' parameter.  This may be a bug, because it means
+that MIDI volume control and program changes interact in non-nice
+ways.
+
+MIDI modulation wheel controller #1 is not mapped, but interpreted
+by the plugin itself to reduce the VCF cutoff.
+
+MIDI channel pressure and key pressure are combined by the plugin to
+boost the VCF resonance.
 
 Questions that might be frequently asked
 ========================================
+Q. Why doesn't the portamento (glide) work?
+A. Portamento only works in monophonic modes, and then only when one
+    note is held while another is played.  Switch to a monophonic
+    mode from the 'Configuration' tab of the GUI.
+
 Q. Woah! Where'd that nasty sound come from?
 A. A certain grittiness has always been part of Xsynth's charm for
     me, but if you're getting really nasty sound from a patch, check
@@ -386,25 +234,12 @@
         output even when you're not playing anything, your plugin
         was probably compiled with the XDB_AUDIO debug bit set.  Fix
         that and recompile.
-    - Pitch too high: even with the band-limited oscillators, it is
-        possible to get audible aliasing on very high notes.  This
-        is especially true when using oscillator sync while VCO2 is
-        producing a sine wave, since the band-limiting technique
-        doesn't deal as well with waveforms having continuously
-        varying slope.
-
-Q. Help! I just installed Xsynth-DSSI 0.9.x, and now my sessions
-    that used the older Xsynth-DSSI 0.1.x don't sound right.  What
-    should I do?
-A. Xsynth-DSSI 0.1.3 is the last 0.1.x-compatible version, but it
-    does include the anti-aliased oscillators and MVCLPF-3 filter.
-    If you just want to use your existing sessions, you'll have to
-    use version 0.1.3. If you want to convert them to 0.9.x, you'll
-    need to save any custom patches or patch banks using a 0.1.x
-    version, then install 0.9.x, load the custom patches, then tweak
-    the mix and glide settings as needed.  (Note that the version
-    0.1.x default patch set is installed by later versions as
-    <prefix>/share/xsynth-dssi/version_0.1_patches.Xsynth)
+    - Pitch too high: I haven't added band-limited oscillators to
+        the render code yet, so it does alias pretty badly on higher
+        notes.  Be patient, or help with the coding.
+
+Q. Ack! Things crashed.  Did I lose my patch edits?
+A. Check in ~/.xsynth-dssi/ -- they may be saved there.
 
 Q. Why aren't the GUI slider values and the corresponding LADSPA
     port values the same?
@@ -412,3 +247,9 @@
     synthesis code, while the GUI slider values are all the 0-to-10
     values used in Steve Brookes' original Xsynth interface.
 
+Q. Why does the Patches list flash so horribly?
+A. Because I don't know GTK+ very well, and with my code the way it
+    is now, GTK+ insists on redrawing the Patches clist every time
+    another widget is updated.  If you know GTK+, please help me fix
+    this.
+