FluidSynth-DSSI
                              ===============
                    A software synthesizer plugin for the
                         DSSI Soft Synth Interface

Introduction
============
FluidSynth-DSSI is an implementation of the FluidSynth soundfont-
playing software synthesizer 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:

  http://dssi.sourceforge.net/

FluidSynth-DSSI makes use of DSSI's run_multiple_synths() interface
to allow sharing of resources (like enormous soundfonts) between
multiple plugin instances -- soundfont data is shared between
instances, and FluidSynth's usual voice allocation methods are
applied across multiple instances as if each were a FluidSynth
channel.

FluidSynth-DSSI is written by Sean Bolton, and is copyright (c)2009
under the GNU General Public License, version 2 or later.  See the
enclosed file COPYING for details.

FluidSynth itself is copyright (c)2006 Peter Hanappe and others,
under the GNU Library General Public License.

Requirements
============
You need to have the following installed:

    - 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/

    - the FluidSynth library and header files, version 1.0.3 or later.
        FluidSynth-DSSI will have additional capability (run-time
        polyphony setting and more efficient operation) if FluidSynth
        version 1.0.6 or later is used.

    - 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 system can use
        libdssialsacompat, available at:

        http://smbolton.com/linux.html

    - pkgconfig with PKG_CONFIG_PATH set appropriately to pick up
        DSSI, liblo, and fluidsynth (plus libdssialsacompat if used).

    - GTK+ version 1.2 or 2.x.  (If GTK+ is not found, the plugin
        will be built without the GUI.)

    - 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 and autoconf 2.59 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:

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 my favorite optimizations to
    CFLAGS for you if you don't include any '-Wall' or '-O' options.

4. If you wish to change the maximum number of simultaneous
    instances supported by FluidSynth-DSSI (currently 16), edit the
    file src/fluidsynth-dssi.h and change the FSD_CHANNEL_COUNT
    definition.

3. Enable debugging information if you desire: edit the files
    src/fluidsynth-dssi.h and src/FluidSynth-DSSI_gtk.c, and define
    DEBUG_DSSI or DEBUG_AUDIO as explained in the comments.

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

5. 'make install' will install the following:

    $(PREFIX)/lib/dssi/fluidsynth-dssi.so
    $(PREFIX)/lib/dssi/fluidsynth-dssi/FluidSynth-DSSI_gtk

Feedback on your experiences building FluidSynth-DSSI is appreciated.

Operation
=========
Start your DSSI host and create an instance of the FluidSynth-DSSI
plugin.  See the 'Example' section below for how to do this with
jack-dssi-host.

Initially, no soundfont will be loaded.  Use the 'Select Soundfont'
button to select a soundfont. Each instance may use only one
soundfont at a time, but when multiple instances use the same
soundfont, it is only loaded once.  FluidSynth-DSSI will use the
the DSSI project directory and the SF2_PATH enviroment variable,
if set, to search for soundfonts.

The available soundfont presets will be displayed in the 'Preset'
window.  Clicking on one will select that preset.

Under 'Global Settings', the 'gain (dB)' setting affects the output
level of all running FluidSynth-DSSI instances.

If you're using FluidSynth version 1.0.6 or later, then you will
have the ability to manage the maximum polyphony used by
FluidSynth-DSSI.  There will be a 'polyphony' setting under 'Global
Settings' in the FluidSynth-DSSI GUI, which sets the maximum number
of voices that will be played by all instances.

Test notes may be generated using the 'Send Test Note' button.  You
may select the pitch and velocity of the note using the 'Test Note'
sliders.

When you create more than one instance of the plugin, you should be
able to tell their GUIs apart by unique window titles of each
(provided your host correctly supplies each with the proper
identifier.)

Example
=======
1. Start JACK.

2. Run jack-dssi-host, starting 16 FluidSynth-DSSI instances, one
    for each MIDI channel:

    $ DSSI_PATH=/usr/local/lib/dssi sudo jack-dssi-host -16 fluidsynth-dssi.so

3. Load a soundfont for each instance.  You may do this using the
    GUI, or via the command line (replace the '19383' with the port
    number your DSSI host is using):

    $ for ee in 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15
    > do dssi_osc_send -C osc.udp://localhost:19383/dssi/fluidsynth-dssi/FluidSynth-DSSI/chan$ee \
    >      load /t/soundfonts/Reality_GMGS.sf2
    > done

4. Make some noise:

    $ pmidi -p128:0 /t/smf/simpsons_theme.mid

Bugs in FluidSynth prior to version 1.0.6
=========================================
FluidSynth versions up through 1.0.5 have a bug in the
fluid_synth_nwrite_float() function that FluidSynth-DSSI uses, which
prevents it from working correctly with block sizes less than 64.
FluidSynth-DSSI will still work with these earlier versions, but
working around the bug requires an extra buffer copy per process
cycle, so it is not as efficient as when FluidSynth versions 1.0.6
or later are used.

FluidSynth versions up through 1.0.5 have a bug in the code enabled
by the '--enable-longlong' configure option, so that it will only
work correctly on little-endian (e.g. x86) systems. It is
recommended that users of big-endian (e.g. PowerPC) systems upgrade
to 1.0.6 or later. (FluidSynth 1.0.8 no longer has the
'--enable-longlong' configure option, and uses the long long type by
default.)