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)