                                 Wsynth-DSSI
                                 ===========
                    A wavetable synthesizer plugin  for the
                        Disposable Soft Synth Interface

Introduction
============
Wsynth-DSSI is the working title of a simple wavetable synth plugin for 
DSSI.  DSSI is the "Disposable Soft Synth Interface", a plugin API for 
software instruments and effects with user interfaces, which are used 
with Linux audio applications.  More information on DSSI, along with a 
few example plugins, can be found at http://dssi.sourceforge.net/ 

Wsynth-DSSI is written and maintained by Gordon JC Pearce, and copyright 
2005 under the GPL.  See the file COPYING for details of the GPL.  
Portions of the code have been inspired by, adapted from and just plain 
stolen outright from Xsynth-DSSI by Sean Bolton, which in turn uses code 
from a few other projects.  See the enclosed file AUTHORS for details.  
The following document borrows heavily from the Xsynth README, because 
the two plugins are currently very similar.
If you find Wsynth-DSSI useful (or for that matter if you don't) I would
appreciate an email with one or more of the following:

    - Who you are, where you're from, and how you heard about Wsynth-DSSI
    - copies of or links to stuff you've created with Wsynth-DSSI.
    - any patches you create for Wsynth-DSSI.
    - suggestions for improving Xsynth-DSSI.

Xsynth-DSSI can be found at the DSSI website.
Xsynth-DSSI is based on Steve Brooke's Xsynth 1.0.2, which is
available (also under GPL) at:

Requirements
============
Wsynth-DSSI requires the following:

    - DSSI version 0.9 or greater, available from the
        dssi.sourceforge.net address above.
    - liblo version 0.12 or later, a library implementing the Open
        Sound Control protocol, available at
        http://plugin.org.uk/liblo/
    - 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.)
    - 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.)
    - 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.
(Unchanged from the Xsynth README)

Installation
============
The generic installation instructions in the enclosed file INSTALL
aren't particularly helpful, so try this instead:

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'.
    configure will add '-Wall' and some 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
    src/xsynth.h, and define XSYNTH_DEBUG as explained in the
    comments.

5. Do 'make'.  Hopefully it should build without warnings (or
    errors.)

6. 'make install' will install the following:

    <prefix>/lib/dssi/wsynth-dssi.so
    <prefix>/lib/dssi/wsynth-dssi/Wsynth_gtk

Feedback on your experiences building Xsynth-DSSI is appreciated.

Operation
=========
To run the Wsynth-DSSI plugin under the jack-dssi-host provided in
the DSSI distribution, I do the following:

1. Start JACK.

2. Start jack-dssi-host, supplying the correct plugin path
    and filename (substitute <prefix> as appropriate):

    $ DSSI_PATH=<prefix>/lib/dssi sudo jack-dssi-host wsynth-dssi.so

    jack-dssi-host should start, and moments later the Wsynth-DSSI
    graphic user interface should appear.

    If you are using the capabilities patch (and if you're not, you
    should be), then jack-dssi-host wsynth-dssi.so should work,
3. Connect jack-dssi-host to a MIDI source, such as vkeybd or an ALSA
   port.  You could use aconnect or qjackctl or something for this.

4. Begin playing sounds!  If you get no response, try clicking the
    'Send Test Note' button in the Wsynth-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.

Wsynth-DSSI starts up with a small set of sound presets, or
'patches', that you can select either by selecting the GUI 'Patches'
tab and clicking on the patch name, or by sending a MIDI program
change from your MIDI source with the appropriate program number.

File Menu
---------
You may load additional patches by selecting 'Load Patch Bank...'
from the GUI 'File' menu, and pointing the file selection dialog to
a Wsynth-DSSI patch bank file.

Selecting 'Save Patch Bank...' from the 'File' menu will allow you
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.

The controls in the VCO1, VCO2, LFO, MIXER, PORTAMENTO, EG1, EG2,
VCF, and VOLUME sections all offer real-time control of the
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, but 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 NAME text box allows you to change the name of a patch.

Once you have edited a patch to your satisfaction, you may save it
back to the patch bank by clicking the 'Save Changes' button.  You
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.

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:
    'Off'  - polyphonic operation.
    'On'   - monophonic operation, where the envelopes are
             retriggered upon each incoming note on event.
    'Once' - monophonic operation, where the envelopes are triggered
             only on the first note on of a legato phrase -- that
             is, if you hold one note while playing a second, the
             envelopes will not be retriggered for the second note.
    'Both' - monophonic operation, where the envelopes are
             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
==================
Wsynth-DSSI is not really based on any real-life synthesizer, but was 
written with the PPG Wave and Ensoniq ESQ-1 synthesizers in mind.  The 
wavetable samples started life in the wave ROM of an ESQ-1.  Technically 
it is more like a vector synth rather than a true wavetable synth, as the 
DCOs mix between two waveforms in "real time" rather than creating a 
wavetable as the waveforms are selected.
The two Digital Controlled Oscillators are mixed, fed to the filter, 
through the final VCA and then out to the appropriate port.  Each 
oscillator has two Wave settings, which let the user pick one of eight 
waveforms.  Depending on the modulation settings, each oscillator will 
output a mix of these waves.

Modulation of these elements is possible using two envelope
generators (EG1 and EG2), a low-frequency oscillator (LFO), and the
MIDI key and velocity.

DCO1 and DCO2
-------------
The pitch of both oscillators is controlled by the MIDI key, pitch bend, 
pitch control and in the case of DCO2, the LFO.  The portamento control 
will allow the instrument to slide between notes.
The frequency of DCO2 is also affected by the 'pitch mod' amounts
from EG1 and the LFO.

The waveforms available for both oscillators are:
    0 - SQUARE	- squarewave
    1 - SAW	- sawtooth wave (no surprises, eh?)
    2 - BELL	- nice clangy FM bell tone
    3 - BASS	- meaty electric bass
    4 - DIGITAL	- harsh buzzy FM-like sound
    5 - VOICE	- Fairlight-y vocal "Aaah"
    6 - CLAV	- clavinet waveform
    7 - REED	- single-reed wind, like a sax

The wavetable mixing is controlled by the LFO in the case of DCO1 and EG2 
in the case of DCO2.  With the LFO amount turned down to nothing, DCO1 
outputs a 50% mix of both waveforms.  With the EG2 amount down, DCO2 
outputs Wave B only.

MIXER
-----
A 'balance' setting of '0' causes the mixer to output only DCO1, a
setting of '10' outputs only DCO2, 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
'filter mod' amounts from EG1 and EG2.

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.

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 'vel 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
----------------------------
LFO has sine, triangle, saw up, saw down and square waves.


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.

Questions that might be frequently asked
========================================
Q:  I'm getting horrible noises at some pitches
A:  The filter is a little unstable, particularly at high cutoff settings 

    and low resonance settings.  You may also be getting aliasing at high 

    frequencies.

Q. Why aren't the GUI slider values and the corresponding LADSPA
    port values the same?
A. The LADSPA port values are the actual numeric values used by the
    synthesis code, while the GUI slider values are all the 0-to-10
    values used in Steve Brookes' original Xsynth interface.

