ghostess - A GUI host for DSSI plugins
======================================
Copyright (C) 2010 by Sean Bolton and others.

This is sloppy, hurried HACKWARE -- please do not consider
this exemplary of the authors' skills or preferences, nor
of good DSSI or general programming practices. (In particular,
I don't want anyone attributing my mess to Chris or Steve ;-)

ghostess is licensed under the GNU General Public License,
version 2 or later, and comes with ABSOLUTELY NO WARRANTY,
including fitness for any particular purpose. See the
enclosed file COPYING for details.

New Stuff
=========
- ghostess works with JACK session managament, assuming
    you have a new enough version of JACK, and configure finds
    jack/session.h.

- ghostess works with JACK MIDI. To build it, use:
    - JACK version 0.105.0 or newer.
    - pkgconfig, liblo 0.18, and DSSI 0.9 or later.
    - if './configure --with-jackmidi' detects the
        jack_midi_get_event_count() function in your libjack.so,
        then ghostess will be built with JACK MIDI support, omitting
        the ALSA or CoreMIDI driver.

- ghostess can now export an XML patchlist for use by Freewheeling.

- blinkin' lights show MIDI activity for each instance.

- ghostess works on OS X.  To build it, I used:
    - pkgconfig, with PKG_CONFIG_PATH set appropriately (Gentoo OS-X)
    - liblo installed (liblo-0.18 from Gentoo OS-X)
    - JACK (JackOSX 0.61)
    - DSSI 0.9
    - libdssialsacompat 1.0.8a
    - './configure && make && make install'
    - Note that to use the CoreMIDI driver, you need to start
        ghostess _after_ any virtual sources you want to connect
        from, since my stupid CoreMIDI driver just connects to all
        existing sources when it starts up.


Quick-and-Dirty Intro
=====================
This assumes you are familiar with jack-dssi-host.  ghostess and
jack-dssi-host both descended from the same dssi_example_host
source, and in many ways are still very similar.  A summary of
the differences (as of 2005/4/11):

* ghostess is GPL, jack-dssi-host is BSD-ish.

* ghostess uses GNU autotools. Use the usual './configure && make &&
    make install' to build.

* ghostess has a simple GTK+ GUI.  Click on the 'UI' button for any
    instance to launch or hide its UI.  Right-click on the 'UI'
    button for more options.

* ghostess comes with a minimal universal DSSI GUI (installed as
    <prefix>/bin/ghostess_universal_gui) that can be used with any
    DSSI or LADSPA plugin.  It does not read RDF files or
    instantiate the plugin, so it's not as full-featured as a
    universal GUI could be, but it does allow for adjusting
    DSSI/LADSPA ports, selecting bank and program (for plugins with
    select_program()), and sending test notes (for plugins with any
    of the run_synth() functions).

    If ghostess cannot find a UI for a plugin, and the universal GUI
    is in the PATH, ghostess will launch it.

* ghostess allows specification of the MIDI channel for each plugin
    instance, allowing layering of multiple synths per channel.

* ghostess allows specification of initial configure, program, and
    port values from the command line.  See below for a description
    of the syntax.

* ghostess tracks configure items set on startup or sent by plugin
    UIs.

* ghostess, through its 'Save Configuration...' menu option, can
    save the current configuration of its plugins.  Basically, it
    just writes a Bourne shell script that can be used to start a
    (mostly) identical session.

* ghostess creates a separate MIDI reception thread, and makes it
    low-priority SCHED_FIFO if possible (ALSA-only, at the moment).

* ghostess has a (clumsy but functional) CoreMIDI driver, allowing
    its use on Mac OS X.

* ghostess double-forks its plugin UIs, putting them in separate
    process groups, and it does not SIGHUP everything on shutdown.
    jack-dssi-host keeps the UIs in its process group, and SIGHUPs
    them all as it exits (Linux-only, at the moment).

* jack-dssi-host uses dual gettimeofday()s in the MIDI and audio
    process threads to do event dejittering, which seems expensive.
    ghostess uses jack_frame_time() and jack_last_frame_time(). This
    means ghostess needs JACK 0.99.0 or newer.

* ghostess uses the LADSPA plugin Label and port Names when creating
    JACK port names, hopefully resulting in short-but-useful port
    names.

* unlike jack-dssi-host, ghostess will not automatically load a
    plugin if it is invoked without arguments via a symlink of the
    same name as the plugin.

* ghostess passes the JACK audio input buffers directly to plugins,
    eliminating a memcpy() that jack-dssi-host does.

* jack-dssi-host includes ~/.dssi in its default for DSSI_PATH,
    ghostess does not.

Command-Line Option Syntax
==========================
The following global options are available:

-debug <level>   - Set bitfield flags which determine which
                   debugging information is printed.  The default of
                   1 shows errors only, 0 is nothing, -1 is
                   everything.  See ghostess.h for details.

-hostname <name> - Set the name ghostess uses for itself, for JACK
                   and ALSA clients and GUI window titles.  If a
                   JACK port cannot be created with that name, the
                   PID is appended.

-projdir <dir>   - Set the 'project directory' configure item passed
                   to plugins and UIs.

-uuid <uuid>     - Set the UUID used by JACK session management. I
                   don't think there is a reason you would use this
                   outside of a managed session.

-noauto          - Disable automatic connection of plugin outputs to
                   JACK physical outputs.

-f <cfgfile>     - Read further options from the file '<cfgfile>',
                   in the same format as the command line arguments.

For specifying plugin instances, ghostess uses a '[<repetition-count>]
[<options>] <soname>[:<label>]' format, similar to jack-dssi-host,
which may be repeated for multiple instances. Specifically, the
syntax is:

    [-<n>] [-chan <c>] [-conf <k> <v>] [-prog <b> <p>] [-port <p> <f>] <soname>[:<label>]

with these parameters:

<n>        Number of instances of the following plugin to create,
           default is 1.

<c>        MIDI channel for the following instance, numbered from 0.
           If the repetition count is more than one, instances are
           given sequential channels beginning with <c> and wrapping
           from 15 to 0.

<k> <v>    Configure item key and value for the following instance
           (repeatable for different keys).

<b> <p>    Bank and program number for the following instance.

<p> <f>    Port number and value for the following instance (repeatable
           for different ports).

<soname>   Name of DSSI or LADSPA plugin library (*.so) to load.  If
           <soname> is not an absolute path, then the environment
           variable DSSI_PATH is searched (note that LADSPA_PATH is not!).

<label>    Name of DSSI or LADSPA plugin within the library to
           instantiate, default is the first.

Below is an example of the Bourne shell script saved by 'Save
Configuration...', which demonstrates almost all of these options.

#!/bin/sh
DSSI_PATH='/opt/audio/lib/dssi'
export DSSI_PATH
exec /tmp/dssi/bin/ghostess \
 -hostname 'ghostess_test' \
 -projdir '/home/smbolton/dssi' \
-comment 'hexter/hexter/inst00' \
 -chan 0 \
 -conf 'monophonic' 'on' \
 -conf 'GLOBAL:polyphony' '13' \
 -prog 0 0 \
 -port 1 440 \
 -port 2 0 \
 'hexter.so':'hexter' \
-comment 'fluidsynth-dssi/FluidSynth-DSSI/inst01' \
 -chan 3 \
 -conf 'load' '/t/soundfonts/Mega25.sf2' \
 -prog 0 0 \
 'fluidsynth-dssi.so':'FluidSynth-DSSI' \
-comment 'lp4pole_1671/lp4pole_fcrcia_oa/inst02' \
 -chan 1 \
 -port 0 1600 \
 -port 1 4 \
 '/usr/lib/ladspa/lp4pole_1671.so':'lp4pole_fcrcia_oa' \
-comment 'xsynth-dssi/Xsynth/inst03' \
 -chan 4 \
 -prog 0 0 \
 -port 1 0.996955 \
 -port 2 2 \
 -port 3 0.5 \
 -port 4 1.00305 \
 -port 5 2 \
 -port 6 0.5 \
 -port 7 0 \
 -port 8 0.5 \
 -port 9 0.1 \
 -port 10 0 \
 -port 11 0 \
 -port 12 0 \
 -port 13 0.0002 \
 -port 14 0.1 \
 -port 15 1 \
 -port 16 1e-04 \
 -port 17 0 \
 -port 18 0 \
 -port 19 14.5722 \
 -port 20 0.1 \
 -port 21 0.1 \
 -port 22 1 \
 -port 23 0.1 \
 -port 24 0 \
 -port 25 0 \
 -port 26 1e-06 \
 -port 27 11.4258 \
 -port 28 0.388616 \
 -port 29 1 \
 -port 30 0.984375 \
 -port 31 0.5 \
 -port 32 440 \
 'xsynth-dssi.so':'Xsynth' \

