blepvco 0.1.0
=============
blepvco is a LADSPA plugin library containing three anti-aliased,
minBLEP-based, hard-sync-capable oscillator plugins.  The
oscillators are intended to be used with modular synthesis systems,
such as Alsa Modular Synth.

Users of Fons Adriaensen's VCO-plugins will find these plugins
immediately familiar, since they borrow much of their interface code
from Fons' work -- indeed, if/when you do not need the hard-sync or
variable-slope triangle wave features of blepvco, his plugins may be
a better choice, because their CPU use is somewhat lower. Currently,
his VCO-plugins can be found at:

    http://users.skynet.be/solaris/linuxaudio/

blepvco is written by Sean Bolton, and copyright (c)2005 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 blepvco useful:
    - an email stating where you're from and how you're using
        the blepvco plugins, sent to <musound /at/ jps /dot/ net>.
    - copies of or links to music you've created with them.
    - suggestions for improving the blepvco plugins or packaging.

blepvco is indirectly the result of cumulative effort by a number of
contributors, see the AUTHORS file for details.

Introduction
============
The three oscillator plugins in blepvco use pre-integrated,
minimum-phase, bandwidth-limited pulses (`minBLEPs') to construct
anti-aliased waveforms. They are capable of `hard sync', where a
slave oscillator will reset its phase whenever the master oscillator
begins a new cycle, producing a distinctive sound.  The three
oscillators are:

Sync-Saw-VCO  : Anti-aliased sawtooth oscillator with hard-sync capability
Sync-Rect-VCO : Anti-aliased variable-width rectangle oscillator, with sync
Sync-Tri-VCO  : Anti-aliased variable-slope triangle oscillator, with sync

Each of these oscillators have `Sync Out' and `Sync In' ports, which
generate and accept a special signal used for synchronization.
Connect the `Sync Out' of the master oscillator to the `Sync In' of
the slave to enable synchronization.  Note that the sync signal may
appear in your application to be an audio signal, but is actually a
stream of phase offsets, and is therefore not compatible with other
audio ports.  In particular, don't expect these oscillators to sync
properly to any source other than a `Sync Out' from another one of
these oscillators.

The sync signal may be chained (e.g. master -> slave1 -> slave2),
but for anti-aliased operation, the frequencies of the upstream
(master and slave1) oscillators must be such that no two would ever
both reset during the same audio frame.

The other ports of plugins are:

 `Output' - the audio output port
 
 `Frequency' - audio-rate frequency input, one-float-per-octave (e.g.
     adding 1.0 to this signal doubles the frequency)

 `Octave' and `Tune' - frequency control inputs, also one-float-per-
     octave.

 `Exp FM' and `Exp FM gain' - yet more one-float-per-octave
     frequency control inputs, but here the audio-rate `Exp FM'
     signal is multiplied by the control input `Exp FM gain' before
     being summed with the other frequency inputs.

 `Lin FM' and `Lin FM gain' - got enough inputs to control the
     frequency yet? Here, the product of the audio-rate `Lin FM' and
     the control input `Lin FM gain' applies a linear, one-float-
     per-kilohertz adjustment to the frequency.

 `Waveform', `Wave Mod', and `WMod gain' - present only in the
     rectangular and triangle wave plugins, these inputs control the
     duty cycle of the output waveform.  A `Waveform' control input of -1.0
     produces the shorted possible `high' portion of the rectangular
     wave, and the shorted-possible positive-slope portion of the
     triangle wave (i.e. it becomes a descending sawtooth), while an
     input of 1.0 produces the longest 'high' or positive-slope
     portion.  The audio-rate `Wave Mod' input is multiplied by the
     control input `WMod gain' and used to modulate the duty cycle.

 `LP filter' - the raw output of these plugins can be pretty bright
     (and I suspect the minimum-phase filtering of the BLEP impulses
     leads to some phase-reinforcement under certain conditions that
     makes them even brighter), so I've retained the low-pass filter
     Fons used in his VCO-plugins.  A `LP filter' control input
     value of 0.0 provides the maximum high-frequency attenuation,
     while a value of 1.0 effectively disables the filter.

Installation
============
On most POSIX-ish systems with the LADSPA SDK installed, doing:

  $ make

follow by (as root):

  $ make install

will build and install the blepvco shared object library as
/usr/lib/ladspa/blepvco.so.  You may wish to tweak a few
things in the Makefile first:

- add the directory where your ladspa.h is found to CPPFLAGS, if
    ladspa.h is not in your compiler's default include path (e.g.
    `CPPFLAGS += -I. -I/opt/audio/include -fPIC -D_REENTRANT -Wall -O3')

- change the destination directory for the install `cp', if you
    don't want it installed in /usr/lib/ladspa.

Extras
======
In the extras/ directory, you will find:

  ams_sync_simple_example.ams
  ams_sync_example_2.ams

    - example patch files for Alsa Modular Synth, showing possible
        uses of blepvco oscillators. (Created with AMS 1.8.4)

  minblep.c

    - Daniel Werner's minBLEP generation code, with a couple bug
        fixes, adapted to use FFTW, and changed to generate impulses
        which are the difference between the minimum-phase, band-
        limited step or slope-change impulses, and their `ideal' or
        `naive' forms.  This is not required to build blepvco -- it's
        only there for the curious, or for those who might want to
        alter the impulse parameters.

