Read Me

FluidSynth-DSSI
===============
A software synthesizer plugin for the
Disposable Soft Synth Interface
Introduction
============
FluidSynth-DSSI is an implementation of the FluidSynth soundfont-
playing software synthesizer as a plugin for the Disposable Soft Synth
Interface (DSSI). 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)2005
under the GNU General Public License, version 2 or later. See the
enclosed file COPYING for details.
FluidSynth itself is copyright (c)2003 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, a library implementing the Open
Sound Control protocol, available at:
http://plugin.org.uk/liblo/
- the FluidSynth library and header files. FluidSynth-DSSI has
been tested with FluidSynth 1.0.5, and should work with
1.0.3 as well.
- 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://home.jps.net/~musound/
- 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://home.jps.net/~musound/
- 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.
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:
$ 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
Polyphony Management
====================
Fluidsynth (up through version 1.0.5 at least) presents DSSI with a
catch-22: Fluidsynth requires the polyphony limit be set before the
synth is instantiated, while DSSI requires the synth be instantiated
before the FluidSynth-DSSI plugin can receive any information about
the user's desired polyphony limit.
There is a patch supplied with FluidSynth-DSSI,
extra/fluidsynth-1.0.5-dssi_patch, which adds several functions to
the fluidsynth API, allowing the polyphony limit to be set after the
synth is instantiated. If you apply this patch (which hopefully
will be included in future versions of Fluidsynth) to the FluidSynth
1.0.5 source, then build FluidSynth-DSSI, the new API functions will
be detected automatically and used.
With the patch, there will be a 'polyphony' setting under 'Global
Settings' in the FluidSynth-DSSI GUI. This 'polyphony' setting sets
the maximum number of voices that will be played by all instances.
An example of using the patch:
$ tar xpzf fluidsynth-1.0.5.tar.gz
$ tar xpzf fluidsynth-dssi-0.9.1.tar.gz
$ cd fluidsynth-1.0.5
$ patch -p1 <../fluidsynth-dssi-0.9.1/extra/fluidsynth-1.0.5-dssi_patch
patching file include/fluidsynth/synth.h
patching file src/fluid_cmd.c
patching file src/fluid_cmd.h
patching file src/fluid_synth.c
patching file src/fluid_synth.h
$ ./configure && make && make install
[ lots of output ]
$ cd ../fluidsynth-dssi-0.9.1
$ ./configure
[ lots of output ]
checking for fluid_synth_set_polyphony in -lfluidsynth... yes
using augmented fluidsynth API
[ lots more output ]
$ make && make install
The configure output lines 'checking for fluid_synth_set_polyphony
in -lfluidsynth... yes' and 'using augmented fluidsynth API' shown
above indicate that the patched API was detected.
The fluid_synth_nwrite_float() Bug
==================================
Fluidsynth versions up through at least 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. If
you've applied the extra/fluidsynth-1.0.5-dssi_patch to your
libfluidsynth, then you may configure FluidSynth-DSSI with the
'--disable-nwrite-float-workaround' flag. This assumes
fluid_synth_nwrite_float() works correctly, and saves a buffer copy
per process cycle.
(Note that all known DSSI hosts split process blocks into various
sizes as part of their MIDI event processing, so even if, for
example, you're running with a JACK buffer size greater than 64,
you'll still need either the workaround enabled, or a patched
fluidsynth, to avoid distorted sound.)
The longlong Bug
================
Fluidsynth versions up through at least 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. There is
another patch included with FluidSynth-DSSI,
extra/fluidsynth-1.0.5-bigendian_longlong_patch, which fixes the
code to work on big-endian (e.g. PowerPC) systems.