dssi-vst: a DSSI plugin wrapper for VST plugins
===============================================

This is a DSSI plugin wrapper for VST effects and instruments with GUI
support.  Copyright (c) 2004 Chris Cannam.

This is the 0.3.1 release of dssi-vst.  The main improvement since the
initial 0.1 release is that dssi-vst now works correctly with VSTs
that have complex GUIs using back-channels to communicate things like
patch information to the audio plugin.


Build etc
---------

To build dssi-vst, you will need:

* The dssi.h header.

* A reasonably recent version of Wine (anything from the start of 2004
  onwards is probably OK) -- http://www.winehq.com/

* Steve Harris's liblo "Lite OSC" library -- http://liblo.sf.net/.
  You will need version 0.9 or newer.

* The VST SDK headers -- http://www.steinberg.net/steinberg/ygrabit/index.html
  These are free but not redistributable.

Once you have all of the above, edit Makefile.in to specify the VST
SDK location; then you should be able to build and install by running
autoconf ; ./configure ; make ; make install.

To use dssi-vst: make sure DSSI_PATH is set appropriately, set
VST_PATH to a colon-separated list of the directories containing VST
plugins, and start up your DSSI host.

The plugin soname is dssi-vst.so, and each VST plugin gets a label
corresponding to its DLL name.  So for example, with
jack-dssi-host, you should be able to just run

   jack-dssi-host dssi-vst.so:MyVstPlugin.dll

Source files:

* dssi-vst.cpp: DSSI plugin implementation
* dssi-vst_gui.cpp: DSSI plugin GUI process implementation
* dssi-vst-scanner.cpp: Program that determines what VSTs you have and
  communicates that to the plugin
* dssi-vst-server.cpp: Program that hosts a single VST with a comms link
  to the plugin
* rdwrops.cpp, paths.cpp: misc functions
* remotepluginclient.cpp/remotepluginserver.cpp: Code to handle process
  separation for audio plugin (not VST specific), used by DSSI plugin & server
* vsthost.cpp: JACK/aseq host for VSTs using dssi-vst-server, but not using
  the actual DSSI plugin. 


Bugs and limitations
--------------------

Does not handle multiple VST plugins in a single DLL.

Does not handle multi-channel support correctly yet.  DSSI does not
use MIDI channels, so dssi-vst should permit separate instances
delivering to separate VST MIDI channels using run_multiple_synths to
share the VST plugin.

Does not communicate tempo and beat information to the VST plugin (the
VST API has a mechanism for this, but DSSI does not).

Has a tendency to leave FIFOs and shared-memory files lying around in
the temporary directory (/tmp or /var/tmp).  You may want to go and
remove anything starting with "rplugin_" occasionally...


Why not use vstserver or libfst?
--------------------------------

dssi-vst doesn't use libfst because libfst is just too serious a thing
to start messing about with in a plugin whose host doesn't know about
it (because it involves introducing Wine threads into the host).

The main reason dssi-vst doesn't use vstserver is that I wrote most of
this code quite a while ago as an exercise, and I've just got used to
my own code.  Architecturally dssi-vst is like vstserver in that it
runs the VST plugin in a separate process and communicates with it via
some IPC mechanism (here shared memory and POSIX FIFOs, in vstserver
shared memory and Unix domain sockets).

Good points of dssi-vst:

* Bugs in dssi-vst aside, it ought to be impossible for a misbehaving
  VST plugin to crash its host.  It's therefore theoretically possible
  for dssi-vst to be more stable for audio use than an fst host.
  (The same is true of vstserver.)

* DSSI provides a closer match to the VST feature set than LADSPA
  does -- apart from the synth stuff, this plugin handles VST programs
  as well as parameters -- which makes it more useful than vstserver's
  existing ladspavst plugin.

* Obviously, dssi-vst allows any DSSI host to become a VST host
  without having to know anything about VST or to have a code (or
  licence) dependency on the VST SDK, which is not the case with fst.

Bad points:

* Processes everywhere.  Besides your host process, you get a
  server process to do the actual audio processing, a scanner
  process to identify the available VST plugins, and a GUI process.
  All of these except the GUI process (which in fact does nothing
  except send information around between the other processes) are
  winelib applications that are run under Wine.  dssi-vst is useful
  for running the odd synth or effect on a fast machine, not for
  doing all your effects work.

* It's hard to make sure things like the communications FIFOs are
  tidied up when exiting.  Apart from anything else it requires
  that the host call cleanup() on its plugins when exiting from
  ctrl-C or whatever.  A model with a server shared among many
  plugins would cope better with this by having the server take
  ownership of such resources instead of the DSSI plugin.

* The comms model dssi-vst uses introduces a fixed latency equal to
  the JACK period size, as well as any existing latency in the VST
  plugin.  (The fixed latency is exposed through the _latency output
  control port.  Does anyone know how to find out the latency of a
  VST plugin?)


Licence
-------

My usual preference would be to offer dssi-vst under the GNU GPL.
However, it is my personal opinion (and I am not a lawyer and have not
consulted one) that GPL'd code that makes use of the Steinberg VST SDK
header files, either directly or via a library, cannot be redistributed
without violating either the GPL or at least one of the copyright or
licensing terms for the Steinberg header files.  So I am offering this
code under the following terms:

"You may distribute and/or modify dssi-vst under the terms of version 2
of the GNU General Public License as published by the Free Software
Foundation, except that you are hereby permitted to omit the source
code to the two VST SDK header files AEffect.h and aeffectx.h (the
source code of which would otherwise be required by section 3 of the
GPL) when redistributing dssi-vst.  The full terms of the GPL continue
to apply to all of the remaining source code for dssi-vst.

Chris Cannam, [email protected]"

What does this mean in practice?  The main thing is it means dssi-vst
is not Free Software in the terms of e.g. the Debian Free Software
Guidelines.  You can redistribute a compiled dssi-vst plugin legally
so long as you follow the GPL's terms with respect to the source code
for dssi-vst and liblo (see below), but you cannot redistribute the
whole of the source code required to build dssi-vst.  Since dssi-vst
exists solely to provide compatibility with proprietary code in the
form of VST plugins, I don't see this as a great moral hardship.  If
it troubles you, don't use proprietary plugins.

You _can_ use dssi-vst as a plugin with a GPL'd DSSI host.


Licence for liblo
-----------------

dssi-vst makes use of the liblo library by Steve Harris, which is
provided under the GPL.  Steve Harris has provided the following
exemption to permit the liblo library to be used with dssi-vst:

"You are hereby permitted to omit the source code to the two VST SDK
header files AEffect.h and aeffectx.h (the source code of which would
otherwise be required by section 3 of the GPL) when redistributing any
version of dssi-vst which uses liblo.  This offer does not imply any
exemption to the GPL for the liblo code itself or the remainder of
dssi-vst, nor to any other derived work that may use liblo.

Steve Harris
steve <at> plugin <dot> org <dot> uk"