NAME

       ghostess - graphical DSSI plugin host

SYNOPSIS

       ghostess  [-debug level] [-hostname hostname] [-projdir projdir] [-uuid uuid] [-noauto] [-f cfgfile] [-n]
       [-chan c] [-conf k v] [-prog b p] [-port p f] soname[:label] [...]

DESCRIPTION

       ghostess is a DSSI host that listens for MIDI events, delivers them to DSSI synth  plugins,  and  outputs
       the  resulting audio via JACK.  ghostess also supports DSSI plugins having audio inputs (effects), LADSPA
       plugins, and the use of DSSI-style user interfaces with LADSPA plugins.   ghostess  can  host  up  to  32
       plugin instances at one time.

       Depending  on  the compile-time configuration, ghostess will receive MIDI events from ALSA, JACK MIDI, or
       CoreMIDI.  Unless otherwise specified by the -chan option, each plugin instance is sequentially  assigned
       a  MIDI  channel,  wrapping  from  15 (zero-based) back to 0 when necessary. Unless -noauto is specified,
       plugin inputs and outputs are connected sequentially to the available  JACK  physical  input  and  output
       ports, respectively, wrapping back to the first port whenever the available ports are exhausted.

       At  startup,  ghostess  presents  a simple GTK+ user interface.  Each plugin instance is represented in a
       frame, labeled with the plugin name, and containing a MIDI activity indicator and a  ´UI´  button.  Left-
       clicking  the  ´UI´  button will start or hide the plugin's user interface (UI).  Right-clicking the ´UI´
       button will allowing starting, hiding, showing, or terminating the plugin's UI.

       The ´Save Configuration...´ option of ghostess's ´File´ menu allows saving the current  configuration  of
       all plugins to a file. Basically, the file is just a Bourne shell script that can be used to recreate the
       configuration.

       ghostess  comes with a minimal universal DSSI GUI, 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.

OPTIONS

       The following global options are available:

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

       -hostname hostname
              Sets  hostname  as  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 projdir
              Sets the project directory passed to both plugins and UIs to projdir.  The default is none.

       -uuid uuid
              Sets uuid as the UUID used for JACK session management. There is probably no reason  to  use  this
              outside of a managed session.

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

       -f cfgfile
              Additional configuration will be read from cfgfile, in the same format as command line options.

       For  specifying  plugin instances, ghostess uses a '[-repetition-count] [options] soname[:label]' format,
       which may be repeated for multiple instances. The plugin-specific options are:

       -n     Specifies the repitition count, or number of instances, of the following plugin to create, where n
              is an integer between 1 (the default) and 32.

       -chan c
              Sets the initial MIDI channel for the following plugin instance to c.  Channels are numbered 0  to
              15.  If  the  repetition count is more than one, instances are given sequential channels beginning
              with c and wrapping from 15 to  0.  The  default  is  for  all  instances'  MIDI  channels  to  be
              sequentially numbered, starting from 0.

       -conf k  v
              Sets  configure  item  key  k and value v for the following instance. May be repeated for multiple
              keys.

       -prog b  p
              Sets the program change bank b and program p for the following plugin (numbered from 0).

       -port p  f
              Sets the value of port p to floating point number f for the following plugin. May be repeated  for
              different ports.

       soname The  name of the DSSI or LADSPA plugin library to load, including the ´.so´ suffix.  soname may be
              an absolute path to the library file, or just the filename itself, in which case the  DSSI  search
              path is searched (see ENVIRONMENT below).

       label  The  label  of the DSSI or LADSPA plugin to load from the library soname.  If this is omitted, the
              first plugin in the library is used.

ENVIRONMENT

       ghostess will search for plugin shared libraries in the directories specified by the environment variable
       DSSI_PATH, which is a colon-separated list of directories. If DSSI_PATH is not set, a default search path
       of /usr/lib/dssi, /usr/local/lib/dssi, and (assuming the environment variable HOME is  set,)  $HOME/.dssi
       is  used.  Note  that  while  ghostess  may  be  used  to  host  LADSPA plugins, the environment variable
       LADSPA_PATH is not used to search for them.

EXAMPLES

       Assuming DSSI_PATH is correctly set, the command:

       $ ghostess hexter.so

       will start a single instance of the plugin hexter, listening on MIDI channel 0, with its output connected
       to the first JACK physical output port.

       The command:

       $ ghostess -noauto -chan 2 xsynth-dssi.so -chan 2 xsynth-dssi.so

       will start two instances of Xsynth-DSSI, both listening on MIDI channel 2,  but  will  not  automatically
       connect the plugin outputs to JACK output ports.

       The command:

       $ ghostess -debug -1 -hostname fuzzy -projdir /tmp/proj -2 -conf load
       mypatches -prog 0 4 -port 7 0.45 effects.so:fuzz

       will  start  two  instances  of  the  ´fuzz´ plugin within the effects.so library, using /tmp/proj as the
       project directory, pass configure key ´load´ with value ´mypatches´ to both instances,  set  bank  0  and
       program  4,  and  set port 7 to 0.45. Assuming it is some sort of effect, the plugins´ inputs and outputs
       will be automatically connected to the first JACK physical inputs and outputs. Full debugging information
       will be printed, and fuzzy will be used as the JACK client name.

AUTHOR

       ghostess was written by Sean Bolton, who mercilessly mangled code originally written by Chris Cannam  and
       Steve  Harris. This manual page was adapted by Sean Bolton from the jack-dssi-host manual page originally
       by Mark Hymers.

                                               September 5th, 2010                                   ghostess(1)