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)